opensteer 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+- Breaking: CLI runtime routing now uses `--session`/`OPENSTEER_SESSION` instead
+  of `--name`/cwd/active-session fallback.
+- Breaking: non-interactive CLI calls now require explicit runtime identity via
+  `--session`, `OPENSTEER_SESSION`, or `OPENSTEER_CLIENT_ID`.
+- Added `OPENSTEER_CLIENT_ID` support for stable client-scoped default session
+  binding.
+- CLI `--name` is now selector-cache namespace only and no longer controls
+  daemon/browser routing.
+- Added per-session daemon startup locking + stale-lock recovery and ping-based
+  health checks to remove startup races across concurrent commands.
+- Added strict in-daemon request serialization for session commands, while
+  keeping `ping` out of the queue for reliable liveness checks.
 - Breaking: removed legacy `ai` config from `OpensteerConfig`; use top-level `model` instead.
 - Breaking: `OPENSTEER_AI_MODEL` is no longer supported; use `OPENSTEER_MODEL`.
 - Breaking: `OPENSTEER_RUNTIME` is no longer supported; use `OPENSTEER_MODE`.

package/README.md

@@ -20,6 +20,31 @@ npm install opensteer playwright
 pnpm add opensteer playwright
 ```
 
+## CLI Session Routing
+
+OpenSteer CLI now separates runtime routing from selector caching:
+
+- Runtime routing: `--session` or `OPENSTEER_SESSION`
+- Selector cache namespace: `--name` or `OPENSTEER_NAME` (used on `open`)
+
+If neither `--session` nor `OPENSTEER_SESSION` is set:
+
+- In an interactive terminal, OpenSteer creates/reuses a terminal-scoped default session.
+- In non-interactive environments (agents/CI), it fails fast unless you set
+  `OPENSTEER_SESSION` or `OPENSTEER_CLIENT_ID`.
+
+Example:
+
+```bash
+export OPENSTEER_SESSION=agent-a
+opensteer open https://example.com --name product-scraper
+opensteer snapshot
+opensteer click 3
+opensteer status
+```
+
+`opensteer status` reports `resolvedSession`, `sessionSource`, `resolvedName`, and `nameSource`.
+
 ## Quickstart
 
 ```ts

package/bin/opensteer.mjs

@@ -2,10 +2,18 @@
 
 import { createHash } from 'crypto'
 import { spawn } from 'child_process'
-import { existsSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'fs'
+import {
+    closeSync,
+    existsSync,
+    openSync,
+    readFileSync,
+    readdirSync,
+    unlinkSync,
+    writeFileSync,
+} from 'fs'
 import { connect } from 'net'
 import { tmpdir } from 'os'
-import { basename, dirname, join } from 'path'
+import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -14,10 +22,16 @@ const SERVER_SCRIPT = join(__dirname, '..', 'dist', 'cli', 'server.js')
 const CONNECT_TIMEOUT = 15000
 const POLL_INTERVAL = 100
 const RESPONSE_TIMEOUT = 120000
+const HEALTH_TIMEOUT = 1500
 const RUNTIME_PREFIX = 'opensteer-'
 const SOCKET_SUFFIX = '.sock'
 const PID_SUFFIX = '.pid'
+const LOCK_SUFFIX = '.lock'
+const CLIENT_BINDING_PREFIX = `${RUNTIME_PREFIX}client-`
+const CLIENT_BINDING_SUFFIX = '.session'
 const CLOSE_ALL_REQUEST = { id: 1, command: 'close', args: {} }
+const PING_REQUEST = { id: 1, command: 'ping', args: {} }
+const SESSION_ID_PATTERN = /^[a-zA-Z0-9_-]+$/
 
 function getVersion() {
     try {
@@ -84,59 +98,162 @@ function sanitizeNamespace(value) {
     return bounded || 'default'
 }
 
-function getActiveNamespacePath() {
-    const hash = createHash('md5').update(process.cwd()).digest('hex').slice(0, 16)
-    return join(tmpdir(), `${RUNTIME_PREFIX}active-${hash}`)
+function isValidSessionId(value) {
+    return SESSION_ID_PATTERN.test(value)
 }
 
-function readActiveNamespace() {
+function validateSessionId(rawValue, label) {
+    const value = String(rawValue ?? '').trim()
+    if (!value) {
+        throw new Error(`${label} cannot be empty.`)
+    }
+    if (!isValidSessionId(value)) {
+        throw new Error(
+            `${label} "${value}" is invalid. Use only letters, numbers, underscores, and hyphens.`
+        )
+    }
+    return value
+}
+
+function resolveName(flags, session) {
+    if (flags.name !== undefined) {
+        if (flags.name === true) {
+            throw new Error('--name requires a namespace value.')
+        }
+        const raw = String(flags.name).trim()
+        if (raw.length > 0) {
+            return { name: sanitizeNamespace(raw), source: 'flag' }
+        }
+    }
+
+    if (
+        typeof process.env.OPENSTEER_NAME === 'string' &&
+        process.env.OPENSTEER_NAME.trim().length > 0
+    ) {
+        return {
+            name: sanitizeNamespace(process.env.OPENSTEER_NAME),
+            source: 'env',
+        }
+    }
+
+    return { name: sanitizeNamespace(session), source: 'session' }
+}
+
+function hashKey(value) {
+    return createHash('sha256').update(value).digest('hex')
+}
+
+function getClientBindingPath(clientKey) {
+    return join(
+        tmpdir(),
+        `${CLIENT_BINDING_PREFIX}${hashKey(clientKey).slice(0, 24)}${CLIENT_BINDING_SUFFIX}`
+    )
+}
+
+function readClientBinding(clientKey) {
+    const bindingPath = getClientBindingPath(clientKey)
+    if (!existsSync(bindingPath)) {
+        return null
+    }
+
     try {
-        const filePath = getActiveNamespacePath()
-        if (!existsSync(filePath)) return null
-        const ns = readFileSync(filePath, 'utf-8').trim()
-        return ns || null
+        const rawSession = readFileSync(bindingPath, 'utf-8').trim()
+        if (!rawSession) {
+            unlinkSync(bindingPath)
+            return null
+        }
+        if (!isValidSessionId(rawSession)) {
+            unlinkSync(bindingPath)
+            return null
+        }
+        return rawSession
     } catch {
         return null
     }
 }
 
-function writeActiveNamespace(namespace) {
+function writeClientBinding(clientKey, session) {
     try {
-        writeFileSync(getActiveNamespacePath(), namespace)
+        writeFileSync(getClientBindingPath(clientKey), session)
     } catch { /* best-effort */ }
 }
 
-function resolveNamespace(flags) {
-    if (flags.name !== undefined && String(flags.name).trim().length > 0) {
-        return { namespace: sanitizeNamespace(String(flags.name)), source: 'flag' }
+function createDefaultSessionId(prefix, clientKey) {
+    return `${prefix}-${hashKey(clientKey).slice(0, 12)}`
+}
+
+function isInteractiveTerminal() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY)
+}
+
+function resolveSession(flags) {
+    if (flags.session !== undefined) {
+        if (flags.session === true) {
+            throw new Error('--session requires a session id value.')
+        }
+
+        return {
+            session: validateSessionId(flags.session, 'Session id'),
+            source: 'flag',
+        }
     }
 
     if (
-        typeof process.env.OPENSTEER_NAME === 'string' &&
-        process.env.OPENSTEER_NAME.trim().length > 0
+        typeof process.env.OPENSTEER_SESSION === 'string' &&
+        process.env.OPENSTEER_SESSION.trim().length > 0
     ) {
-        return { namespace: sanitizeNamespace(process.env.OPENSTEER_NAME), source: 'env' }
+        return {
+            session: validateSessionId(
+                process.env.OPENSTEER_SESSION,
+                'OPENSTEER_SESSION'
+            ),
+            source: 'env',
+        }
     }
 
-    const active = readActiveNamespace()
-    if (active && isServerRunning(active)) {
-        return { namespace: active, source: 'active' }
+    if (
+        typeof process.env.OPENSTEER_CLIENT_ID === 'string' &&
+        process.env.OPENSTEER_CLIENT_ID.trim().length > 0
+    ) {
+        const clientId = process.env.OPENSTEER_CLIENT_ID.trim()
+        const clientKey = `client:${process.cwd()}:${clientId}`
+        const bound = readClientBinding(clientKey)
+        if (bound) {
+            return { session: bound, source: 'client_binding' }
+        }
+
+        const created = createDefaultSessionId('client', clientKey)
+        writeClientBinding(clientKey, created)
+        return { session: created, source: 'client_binding' }
     }
 
-    const cwdBase = basename(process.cwd())
-    if (cwdBase && cwdBase !== '.' && cwdBase !== '/') {
-        return { namespace: sanitizeNamespace(cwdBase), source: 'cwd' }
+    if (isInteractiveTerminal()) {
+        const ttyKey = `tty:${process.cwd()}:${process.ppid}`
+        const bound = readClientBinding(ttyKey)
+        if (bound) {
+            return { session: bound, source: 'tty_default' }
+        }
+
+        const created = createDefaultSessionId('tty', ttyKey)
+        writeClientBinding(ttyKey, created)
+        return { session: created, source: 'tty_default' }
     }
 
-    return { namespace: 'default', source: 'default' }
+    throw new Error(
+        'No session resolved for this non-interactive command. Set OPENSTEER_SESSION or OPENSTEER_CLIENT_ID, or pass --session <id>.'
+    )
 }
 
-function getSocketPath(namespace) {
-    return join(tmpdir(), `${RUNTIME_PREFIX}${namespace}${SOCKET_SUFFIX}`)
+function getSocketPath(session) {
+    return join(tmpdir(), `${RUNTIME_PREFIX}${session}${SOCKET_SUFFIX}`)
 }
 
-function getPidPath(namespace) {
-    return join(tmpdir(), `${RUNTIME_PREFIX}${namespace}${PID_SUFFIX}`)
+function getPidPath(session) {
+    return join(tmpdir(), `${RUNTIME_PREFIX}${session}${PID_SUFFIX}`)
+}
+
+function getLockPath(session) {
+    return join(tmpdir(), `${RUNTIME_PREFIX}${session}${LOCK_SUFFIX}`)
 }
 
 function buildRequest(command, flags, positional) {
@@ -270,66 +387,36 @@ function isPidAlive(pid) {
     }
 }
 
-function cleanStaleFiles(namespace) {
-    try {
-        unlinkSync(getSocketPath(namespace))
-    } catch { }
-    try {
-        unlinkSync(getPidPath(namespace))
-    } catch { }
-}
+function cleanStaleFiles(session, options = {}) {
+    const removeSocket = options.removeSocket !== false
+    const removePid = options.removePid !== false
 
-function isServerRunning(namespace) {
-    const pidPath = getPidPath(namespace)
-    const pid = readPid(pidPath)
-    if (!pid) {
-        cleanStaleFiles(namespace)
-        return false
+    if (removeSocket) {
+        try {
+            unlinkSync(getSocketPath(session))
+        } catch { }
     }
 
-    if (!isPidAlive(pid)) {
-        cleanStaleFiles(namespace)
-        return false
+    if (removePid) {
+        try {
+            unlinkSync(getPidPath(session))
+        } catch { }
     }
-
-    return existsSync(getSocketPath(namespace))
 }
 
-function startServer(namespace) {
+function startServer(session) {
     const child = spawn('node', [SERVER_SCRIPT], {
         detached: true,
         stdio: ['ignore', 'ignore', 'ignore'],
         env: {
             ...process.env,
-            OPENSTEER_NAME: namespace,
+            OPENSTEER_SESSION: session,
         },
     })
     child.unref()
 }
 
-function waitForSocket(socketPath, timeout) {
-    return new Promise((resolve, reject) => {
-        const start = Date.now()
-
-        function poll() {
-            if (Date.now() - start > timeout) {
-                reject(new Error('Timed out waiting for server to start'))
-                return
-            }
-
-            if (existsSync(socketPath)) {
-                resolve()
-                return
-            }
-
-            setTimeout(poll, POLL_INTERVAL)
-        }
-
-        poll()
-    })
-}
-
-function sendCommand(socketPath, request) {
+function sendCommand(socketPath, request, timeoutMs = RESPONSE_TIMEOUT) {
     return new Promise((resolve, reject) => {
         const socket = connect(socketPath)
         let buffer = ''
@@ -341,7 +428,7 @@ function sendCommand(socketPath, request) {
                 socket.destroy()
                 reject(new Error('Response timeout'))
             }
-        }, RESPONSE_TIMEOUT)
+        }, timeoutMs)
 
         socket.on('connect', () => {
             socket.write(JSON.stringify(request) + '\n')
@@ -381,6 +468,169 @@ function sendCommand(socketPath, request) {
     })
 }
 
+async function pingServer(session) {
+    const socketPath = getSocketPath(session)
+    if (!existsSync(socketPath)) return false
+
+    try {
+        const response = await sendCommand(socketPath, PING_REQUEST, HEALTH_TIMEOUT)
+        return Boolean(response?.ok && response?.result?.pong)
+    } catch {
+        return false
+    }
+}
+
+async function isServerHealthy(session) {
+    const pid = readPid(getPidPath(session))
+    const pidAlive = pid ? isPidAlive(pid) : false
+    const socketExists = existsSync(getSocketPath(session))
+
+    if (pid && !pidAlive) {
+        cleanStaleFiles(session)
+        return false
+    }
+
+    if (!socketExists) {
+        return false
+    }
+
+    const healthy = await pingServer(session)
+    if (healthy) {
+        return true
+    }
+
+    // If there is no pid and ping fails, the socket file is stale.
+    if (!pid) {
+        cleanStaleFiles(session, { removeSocket: true, removePid: false })
+    }
+
+    return false
+}
+
+function acquireStartLock(session) {
+    const lockPath = getLockPath(session)
+
+    try {
+        const fd = openSync(lockPath, 'wx')
+        writeFileSync(
+            fd,
+            JSON.stringify({
+                pid: process.pid,
+                createdAt: Date.now(),
+            })
+        )
+        closeSync(fd)
+        return true
+    } catch {
+        return false
+    }
+}
+
+function releaseStartLock(session) {
+    try {
+        unlinkSync(getLockPath(session))
+    } catch { /* best-effort */ }
+}
+
+function recoverStaleStartLock(session) {
+    const lockPath = getLockPath(session)
+    if (!existsSync(lockPath)) {
+        return false
+    }
+
+    try {
+        const raw = readFileSync(lockPath, 'utf-8')
+        const parsed = JSON.parse(raw)
+        const pid =
+            parsed && Number.isInteger(parsed.pid) && parsed.pid > 0
+                ? parsed.pid
+                : null
+
+        if (!pid || !isPidAlive(pid)) {
+            unlinkSync(lockPath)
+            return true
+        }
+
+        return false
+    } catch {
+        try {
+            unlinkSync(lockPath)
+            return true
+        } catch {
+            return false
+        }
+    }
+}
+
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+async function waitForServerReady(session, timeout) {
+    const start = Date.now()
+
+    while (Date.now() - start <= timeout) {
+        if (await isServerHealthy(session)) {
+            return
+        }
+        await sleep(POLL_INTERVAL)
+    }
+
+    throw new Error(`Timed out waiting for server '${session}' to become healthy.`)
+}
+
+async function ensureServer(session) {
+    if (await isServerHealthy(session)) {
+        return
+    }
+
+    if (!existsSync(SERVER_SCRIPT)) {
+        throw new Error(
+            `Server script not found: ${SERVER_SCRIPT}. Run the build script first.`
+        )
+    }
+
+    const deadline = Date.now() + CONNECT_TIMEOUT
+
+    while (Date.now() < deadline) {
+        if (await isServerHealthy(session)) {
+            return
+        }
+
+        const existingPid = readPid(getPidPath(session))
+        if (existingPid && isPidAlive(existingPid)) {
+            // A daemon process already owns this session. It may still be
+            // starting up or shutting down; avoid spawning a competing daemon.
+            await sleep(POLL_INTERVAL)
+            continue
+        }
+
+        recoverStaleStartLock(session)
+
+        if (acquireStartLock(session)) {
+            try {
+                if (!(await isServerHealthy(session))) {
+                    startServer(session)
+                }
+
+                await waitForServerReady(
+                    session,
+                    Math.max(500, deadline - Date.now())
+                )
+                return
+            } finally {
+                releaseStartLock(session)
+            }
+        }
+
+        await sleep(POLL_INTERVAL)
+    }
+
+    throw new Error(
+        `Failed to start server for session '${session}'. Check that the build is complete.`
+    )
+}
+
 function listSessions() {
     const sessions = []
     const entries = readdirSync(tmpdir())
@@ -465,11 +715,11 @@ Navigation:
   forward                   Go forward
   reload                    Reload page
   close                     Close browser and server
-  close --all               Close all active namespace-scoped servers
+  close --all               Close all active session-scoped servers
 
 Sessions:
-  sessions                  List active namespace-scoped sessions
-  status                    Show resolved namespace and session state
+  sessions                  List active session-scoped daemons
+  status                    Show resolved session/name and session state
 
 Observation:
   snapshot [--mode action]  Get page snapshot
@@ -515,7 +765,8 @@ Utility:
   extract <schema-json>     Extract structured data
 
 Global Flags:
-  --name <namespace>        Session namespace (default: CWD basename or OPENSTEER_NAME)
+  --session <id>            Runtime session id for daemon/browser routing
+  --name <namespace>        Selector namespace for cache storage on 'open'
   --headless                Launch browser in headless mode
   --connect-url <url>       Connect to a running browser (e.g. http://localhost:9222)
   --channel <browser>       Use installed browser (chrome, chrome-beta, msedge)
@@ -527,7 +778,9 @@ Global Flags:
   --version, -v             Show version
 
 Environment:
-  OPENSTEER_NAME            Default session namespace when --name is omitted
+  OPENSTEER_SESSION         Runtime session id (equivalent to --session)
+  OPENSTEER_CLIENT_ID       Stable client identity for default session binding
+  OPENSTEER_NAME            Default selector namespace for 'open' when --name is omitted
   OPENSTEER_MODE            Runtime mode: "local" (default) or "remote"
   OPENSTEER_API_KEY         Required when remote mode is selected
   OPENSTEER_BASE_URL        Override remote control-plane base URL
@@ -536,26 +789,12 @@ Environment:
 
 async function main() {
     const { command, flags, positional } = parseArgs(process.argv)
-    const { namespace, source: namespaceSource } = resolveNamespace(flags)
-    const socketPath = getSocketPath(namespace)
 
     if (command === 'sessions') {
         output({ ok: true, sessions: listSessions() })
         return
     }
 
-    if (command === 'status') {
-        output({
-            ok: true,
-            namespace,
-            namespaceSource,
-            serverRunning: isServerRunning(namespace),
-            socketPath,
-            sessions: listSessions(),
-        })
-        return
-    }
-
     if (command === 'close' && flags.all === true) {
         try {
             const closed = await closeAllSessions()
@@ -566,36 +805,66 @@ async function main() {
         return
     }
 
+    let resolvedSession
+    let resolvedName
+    try {
+        resolvedSession = resolveSession(flags)
+        resolvedName = resolveName(flags, resolvedSession.session)
+    } catch (err) {
+        error(err instanceof Error ? err.message : 'Failed to resolve session')
+    }
+
+    const session = resolvedSession.session
+    const sessionSource = resolvedSession.source
+    const name = resolvedName.name
+    const nameSource = resolvedName.source
+    const socketPath = getSocketPath(session)
+
+    if (command === 'status') {
+        output({
+            ok: true,
+            resolvedSession: session,
+            sessionSource,
+            resolvedName: name,
+            nameSource,
+            serverRunning: await isServerHealthy(session),
+            socketPath,
+            sessions: listSessions(),
+        })
+        return
+    }
+
     delete flags.name
+    delete flags.session
     delete flags.all
+
     const request = buildRequest(command, flags, positional)
+    if (command === 'open') {
+        request.args.name = name
+    }
 
-    if (!isServerRunning(namespace)) {
+    if (!(await isServerHealthy(session))) {
         if (command !== 'open') {
             error(
-                `No server running for namespace '${namespace}' (resolved from ${namespaceSource}). Run 'opensteer open' first or use 'opensteer sessions' to see active sessions.`
+                `No server running for session '${session}' (resolved from ${sessionSource}). Run 'opensteer open' first or use 'opensteer sessions' to see active sessions.`
             )
         }
-        if (!existsSync(SERVER_SCRIPT)) {
+
+        try {
+            await ensureServer(session)
+        } catch (err) {
             error(
-                `Server script not found: ${SERVER_SCRIPT}. Run the build script first.`
+                err instanceof Error
+                    ? err.message
+                    : 'Failed to start server. Check that the build is complete.'
             )
         }
-        startServer(namespace)
-        try {
-            await waitForSocket(socketPath, CONNECT_TIMEOUT)
-        } catch {
-            error('Failed to start server. Check that the build is complete.')
-        }
     }
 
     try {
         const response = await sendCommand(socketPath, request)
 
         if (response.ok) {
-            if (command === 'open') {
-                writeActiveNamespace(namespace)
-            }
             output({ ok: true, ...response.result })
         } else {
             process.stderr.write(

package/dist/cli/server.cjs

@@ -817,15 +817,15 @@ function normalizeNamespace(input) {
   if (!segments.length) return DEFAULT_NAMESPACE;
   return segments.join("/");
 }
-function resolveNamespaceDir(rootDir, namespace2) {
+function resolveNamespaceDir(rootDir, namespace) {
   const selectorsRoot = import_path2.default.resolve(rootDir, ".opensteer", "selectors");
-  const normalizedNamespace = normalizeNamespace(namespace2);
+  const normalizedNamespace = normalizeNamespace(namespace);
   const namespaceDir = import_path2.default.resolve(selectorsRoot, normalizedNamespace);
   const relative = import_path2.default.relative(selectorsRoot, namespaceDir);
   if (relative === "" || relative === ".") return namespaceDir;
   if (relative.startsWith("..") || import_path2.default.isAbsolute(relative)) {
     throw new Error(
-      `Namespace "${namespace2}" resolves outside selectors root.`
+      `Namespace "${namespace}" resolves outside selectors root.`
     );
   }
   return namespaceDir;
@@ -1275,9 +1275,9 @@ function createEmptyRegistry(name) {
 var LocalSelectorStorage = class {
   rootDir;
   namespace;
-  constructor(rootDir, namespace2) {
+  constructor(rootDir, namespace) {
     this.rootDir = rootDir;
-    this.namespace = normalizeNamespace(namespace2);
+    this.namespace = normalizeNamespace(namespace);
   }
   getRootDir() {
     return this.rootDir;
@@ -6973,7 +6973,7 @@ function withTokenQuery(wsUrl, token) {
 var import_fs3 = __toESM(require("fs"), 1);
 var import_path5 = __toESM(require("path"), 1);
 function collectLocalSelectorCacheEntries(storage) {
-  const namespace2 = storage.getNamespace();
+  const namespace = storage.getNamespace();
   const namespaceDir = storage.getNamespaceDir();
   if (!import_fs3.default.existsSync(namespaceDir)) return [];
   const entries = [];
@@ -6994,7 +6994,7 @@ function collectLocalSelectorCacheEntries(storage) {
       continue;
     }
     entries.push({
-      namespace: namespace2,
+      namespace,
       siteOrigin,
       method,
       descriptionHash,
@@ -7430,20 +7430,20 @@ var Opensteer = class _Opensteer {
             );
           }
         }
-        const session2 = await this.remote.sessionClient.create({
+        const session3 = await this.remote.sessionClient.create({
           name: this.namespace,
           model: this.config.model,
           launchContext: options.context || void 0
         });
-        sessionId = session2.sessionId;
+        sessionId = session3.sessionId;
         actionClient = await ActionWsClient.connect({
-          url: session2.actionWsUrl,
-          token: session2.actionToken,
-          sessionId: session2.sessionId
+          url: session3.actionWsUrl,
+          token: session3.actionToken,
+          sessionId: session3.sessionId
         });
         const cdpConnection = await this.remote.cdpClient.connect({
-          wsUrl: session2.cdpWsUrl,
-          token: session2.cdpToken
+          wsUrl: session3.cdpWsUrl,
+          token: session3.cdpToken
         });
         browser = cdpConnection.browser;
         this.browser = cdpConnection.browser;
@@ -7467,15 +7467,15 @@ var Opensteer = class _Opensteer {
         throw error;
       }
     }
-    const session = await this.pool.launch({
+    const session2 = await this.pool.launch({
       ...options,
       connectUrl: options.connectUrl ?? this.config.browser?.connectUrl,
       channel: options.channel ?? this.config.browser?.channel,
       profileDir: options.profileDir ?? this.config.browser?.profileDir
     });
-    this.browser = session.browser;
-    this.contextRef = session.context;
-    this.pageRef = session.page;
+    this.browser = session2.browser;
+    this.contextRef = session2.context;
+    this.pageRef = session2.page;
     this.ownsBrowser = true;
     this.snapshotCache = null;
   }
@@ -9501,14 +9501,14 @@ function getScrollDelta2(options) {
 // src/cli/paths.ts
 var import_os2 = require("os");
 var import_path6 = require("path");
-function prefix(namespace2) {
-  return `opensteer-${namespace2}`;
+function prefix(session2) {
+  return `opensteer-${session2}`;
 }
-function getSocketPath(namespace2) {
-  return (0, import_path6.join)((0, import_os2.tmpdir)(), `${prefix(namespace2)}.sock`);
+function getSocketPath(session2) {
+  return (0, import_path6.join)((0, import_os2.tmpdir)(), `${prefix(session2)}.sock`);
 }
-function getPidPath(namespace2) {
-  return (0, import_path6.join)((0, import_os2.tmpdir)(), `${prefix(namespace2)}.pid`);
+function getPidPath(session2) {
+  return (0, import_path6.join)((0, import_os2.tmpdir)(), `${prefix(session2)}.pid`);
 }
 
 // src/cli/commands.ts
@@ -9746,6 +9746,19 @@ function getCommandHandler(name) {
 // src/cli/server.ts
 var instance = null;
 var launchPromise = null;
+var selectorNamespace = null;
+var requestQueue = Promise.resolve();
+var shuttingDown = false;
+function sanitizeNamespace(value) {
+  const trimmed = String(value || "").trim();
+  if (!trimmed || trimmed === "." || trimmed === "..") {
+    return "default";
+  }
+  const replaced = trimmed.replace(/[^a-zA-Z0-9_-]+/g, "_");
+  const collapsed = replaced.replace(/_+/g, "_");
+  const bounded = collapsed.replace(/^_+|_+$/g, "");
+  return bounded || "default";
+}
 function invalidateInstance() {
   if (!instance) return;
   instance.close().catch(() => {
@@ -9759,13 +9772,14 @@ function attachLifecycleListeners(inst) {
   } catch {
   }
 }
-var namespace = process.env.OPENSTEER_NAME?.trim();
-if (!namespace) {
-  process.stderr.write("Missing OPENSTEER_NAME environment variable.\n");
+var sessionEnv = process.env.OPENSTEER_SESSION?.trim();
+if (!sessionEnv) {
+  process.stderr.write("Missing OPENSTEER_SESSION environment variable.\n");
   process.exit(1);
 }
-var socketPath = getSocketPath(namespace);
-var pidPath = getPidPath(namespace);
+var session = sessionEnv;
+var socketPath = getSocketPath(session);
+var pidPath = getPidPath(session);
 function cleanup() {
   try {
     (0, import_fs4.unlinkSync)(socketPath);
@@ -9776,14 +9790,49 @@ function cleanup() {
   } catch {
   }
 }
+function beginShutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  cleanup();
+  server.close(() => {
+    process.exit(0);
+  });
+  setTimeout(() => {
+    process.exit(0);
+  }, 250).unref();
+}
 function sendResponse(socket, response) {
   try {
     socket.write(JSON.stringify(response) + "\n");
   } catch {
   }
 }
+function enqueueRequest(request, socket) {
+  if (request.command === "ping") {
+    void handleRequest(request, socket);
+    return;
+  }
+  requestQueue = requestQueue.then(() => handleRequest(request, socket)).catch(() => {
+  });
+}
 async function handleRequest(request, socket) {
   const { id, command, args } = request;
+  if (command === "ping" && shuttingDown) {
+    sendResponse(socket, {
+      id,
+      ok: false,
+      error: `Session '${session}' is shutting down.`
+    });
+    return;
+  }
+  if (shuttingDown) {
+    sendResponse(socket, {
+      id,
+      ok: false,
+      error: `Session '${session}' is shutting down. Retry your command.`
+    });
+    return;
+  }
   if (command === "open") {
     try {
       const url = args.url;
@@ -9791,6 +9840,19 @@ async function handleRequest(request, socket) {
       const connectUrl = args["connect-url"];
       const channel = args.channel;
       const profileDir = args["profile-dir"];
+      const requestedName = typeof args.name === "string" && args.name.trim().length > 0 ? sanitizeNamespace(args.name) : null;
+      if (selectorNamespace && requestedName && requestedName !== selectorNamespace) {
+        sendResponse(socket, {
+          id,
+          ok: false,
+          error: `Session '${session}' is already bound to selector namespace '${selectorNamespace}'. Requested '${requestedName}' does not match. Use the same --name for this session or start a different --session.`
+        });
+        return;
+      }
+      if (!selectorNamespace) {
+        selectorNamespace = requestedName ?? session;
+      }
+      const activeNamespace = selectorNamespace ?? session;
       if (instance && !launchPromise) {
         try {
           if (instance.page.isClosed()) {
@@ -9802,7 +9864,7 @@ async function handleRequest(request, socket) {
       }
       if (!instance) {
         instance = new Opensteer({
-          name: namespace,
+          name: activeNamespace,
           browser: {
             headless: headless ?? false,
             connectUrl,
@@ -9834,8 +9896,9 @@ async function handleRequest(request, socket) {
         ok: true,
         result: {
           url: instance.page.url(),
-          sessionId: instance.getRemoteSessionId() ?? void 0,
-          name: namespace
+          session,
+          name: activeNamespace,
+          remoteSessionId: instance.getRemoteSessionId() ?? void 0
         }
       });
     } catch (err) {
@@ -9865,10 +9928,7 @@ async function handleRequest(request, socket) {
         error: err instanceof Error ? err.message : String(err)
       });
     }
-    setTimeout(() => {
-      cleanup();
-      process.exit(0);
-    }, 100);
+    beginShutdown();
     return;
   }
   if (command === "ping") {
@@ -9879,7 +9939,7 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `No browser session in namespace '${namespace}'. Call 'opensteer open --name ${namespace}' first, or use 'opensteer sessions' to list active sessions.`
+      error: `No browser session in session '${session}'. Call 'opensteer open --session ${session}' first, or use 'opensteer sessions' to list active sessions.`
     });
     return;
   }
@@ -9916,7 +9976,7 @@ var server = (0, import_net.createServer)((socket) => {
       if (!line.trim()) continue;
       try {
         const request = JSON.parse(line);
-        handleRequest(request, socket);
+        enqueueRequest(request, socket);
       } catch {
         sendResponse(socket, {
           id: 0,
@@ -9941,6 +10001,8 @@ server.on("error", (err) => {
   process.exit(1);
 });
 async function shutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
   if (instance) {
     try {
       await instance.close();
@@ -9948,9 +10010,13 @@ async function shutdown() {
     }
     instance = null;
   }
-  server.close();
   cleanup();
-  process.exit(0);
+  server.close(() => {
+    process.exit(0);
+  });
+  setTimeout(() => {
+    process.exit(0);
+  }, 250).unref();
 }
 process.on("SIGTERM", shutdown);
 process.on("SIGINT", shutdown);

package/dist/cli/server.js

@@ -10,14 +10,14 @@ import { writeFileSync, unlinkSync, existsSync } from "fs";
 // src/cli/paths.ts
 import { tmpdir } from "os";
 import { join } from "path";
-function prefix(namespace2) {
-  return `opensteer-${namespace2}`;
+function prefix(session2) {
+  return `opensteer-${session2}`;
 }
-function getSocketPath(namespace2) {
-  return join(tmpdir(), `${prefix(namespace2)}.sock`);
+function getSocketPath(session2) {
+  return join(tmpdir(), `${prefix(session2)}.sock`);
 }
-function getPidPath(namespace2) {
-  return join(tmpdir(), `${prefix(namespace2)}.pid`);
+function getPidPath(session2) {
+  return join(tmpdir(), `${prefix(session2)}.pid`);
 }
 
 // src/cli/commands.ts
@@ -255,6 +255,19 @@ function getCommandHandler(name) {
 // src/cli/server.ts
 var instance = null;
 var launchPromise = null;
+var selectorNamespace = null;
+var requestQueue = Promise.resolve();
+var shuttingDown = false;
+function sanitizeNamespace(value) {
+  const trimmed = String(value || "").trim();
+  if (!trimmed || trimmed === "." || trimmed === "..") {
+    return "default";
+  }
+  const replaced = trimmed.replace(/[^a-zA-Z0-9_-]+/g, "_");
+  const collapsed = replaced.replace(/_+/g, "_");
+  const bounded = collapsed.replace(/^_+|_+$/g, "");
+  return bounded || "default";
+}
 function invalidateInstance() {
   if (!instance) return;
   instance.close().catch(() => {
@@ -268,13 +281,14 @@ function attachLifecycleListeners(inst) {
   } catch {
   }
 }
-var namespace = process.env.OPENSTEER_NAME?.trim();
-if (!namespace) {
-  process.stderr.write("Missing OPENSTEER_NAME environment variable.\n");
+var sessionEnv = process.env.OPENSTEER_SESSION?.trim();
+if (!sessionEnv) {
+  process.stderr.write("Missing OPENSTEER_SESSION environment variable.\n");
   process.exit(1);
 }
-var socketPath = getSocketPath(namespace);
-var pidPath = getPidPath(namespace);
+var session = sessionEnv;
+var socketPath = getSocketPath(session);
+var pidPath = getPidPath(session);
 function cleanup() {
   try {
     unlinkSync(socketPath);
@@ -285,14 +299,49 @@ function cleanup() {
   } catch {
   }
 }
+function beginShutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  cleanup();
+  server.close(() => {
+    process.exit(0);
+  });
+  setTimeout(() => {
+    process.exit(0);
+  }, 250).unref();
+}
 function sendResponse(socket, response) {
   try {
     socket.write(JSON.stringify(response) + "\n");
   } catch {
   }
 }
+function enqueueRequest(request, socket) {
+  if (request.command === "ping") {
+    void handleRequest(request, socket);
+    return;
+  }
+  requestQueue = requestQueue.then(() => handleRequest(request, socket)).catch(() => {
+  });
+}
 async function handleRequest(request, socket) {
   const { id, command, args } = request;
+  if (command === "ping" && shuttingDown) {
+    sendResponse(socket, {
+      id,
+      ok: false,
+      error: `Session '${session}' is shutting down.`
+    });
+    return;
+  }
+  if (shuttingDown) {
+    sendResponse(socket, {
+      id,
+      ok: false,
+      error: `Session '${session}' is shutting down. Retry your command.`
+    });
+    return;
+  }
   if (command === "open") {
     try {
       const url = args.url;
@@ -300,6 +349,19 @@ async function handleRequest(request, socket) {
       const connectUrl = args["connect-url"];
       const channel = args.channel;
       const profileDir = args["profile-dir"];
+      const requestedName = typeof args.name === "string" && args.name.trim().length > 0 ? sanitizeNamespace(args.name) : null;
+      if (selectorNamespace && requestedName && requestedName !== selectorNamespace) {
+        sendResponse(socket, {
+          id,
+          ok: false,
+          error: `Session '${session}' is already bound to selector namespace '${selectorNamespace}'. Requested '${requestedName}' does not match. Use the same --name for this session or start a different --session.`
+        });
+        return;
+      }
+      if (!selectorNamespace) {
+        selectorNamespace = requestedName ?? session;
+      }
+      const activeNamespace = selectorNamespace ?? session;
       if (instance && !launchPromise) {
         try {
           if (instance.page.isClosed()) {
@@ -311,7 +373,7 @@ async function handleRequest(request, socket) {
       }
       if (!instance) {
         instance = new Opensteer({
-          name: namespace,
+          name: activeNamespace,
           browser: {
             headless: headless ?? false,
             connectUrl,
@@ -343,8 +405,9 @@ async function handleRequest(request, socket) {
         ok: true,
         result: {
           url: instance.page.url(),
-          sessionId: instance.getRemoteSessionId() ?? void 0,
-          name: namespace
+          session,
+          name: activeNamespace,
+          remoteSessionId: instance.getRemoteSessionId() ?? void 0
         }
       });
     } catch (err) {
@@ -374,10 +437,7 @@ async function handleRequest(request, socket) {
         error: err instanceof Error ? err.message : String(err)
       });
     }
-    setTimeout(() => {
-      cleanup();
-      process.exit(0);
-    }, 100);
+    beginShutdown();
     return;
   }
   if (command === "ping") {
@@ -388,7 +448,7 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `No browser session in namespace '${namespace}'. Call 'opensteer open --name ${namespace}' first, or use 'opensteer sessions' to list active sessions.`
+      error: `No browser session in session '${session}'. Call 'opensteer open --session ${session}' first, or use 'opensteer sessions' to list active sessions.`
     });
     return;
   }
@@ -425,7 +485,7 @@ var server = createServer((socket) => {
       if (!line.trim()) continue;
       try {
         const request = JSON.parse(line);
-        handleRequest(request, socket);
+        enqueueRequest(request, socket);
       } catch {
         sendResponse(socket, {
           id: 0,
@@ -450,6 +510,8 @@ server.on("error", (err) => {
   process.exit(1);
 });
 async function shutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
   if (instance) {
     try {
       await instance.close();
@@ -457,9 +519,13 @@ async function shutdown() {
     }
     instance = null;
   }
-  server.close();
   cleanup();
-  process.exit(0);
+  server.close(() => {
+    process.exit(0);
+  });
+  setTimeout(() => {
+    process.exit(0);
+  }, 250).unref();
 }
 process.on("SIGTERM", shutdown);
 process.on("SIGINT", shutdown);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "opensteer",
-    "version": "0.4.4",
+    "version": "0.4.5",
     "packageManager": "pnpm@10.29.3",
     "description": "Open-source browser automation SDK with robust selectors and deterministic replay.",
     "license": "MIT",