opensteer 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -14,6 +14,10 @@
   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: CLI daemon routing is now scoped by canonical `cwd`
+  (`realpath(cwd)`) + logical session (`--session`/`OPENSTEER_SESSION`) rather
+  than machine-wide session id matching; the same logical session can run in
+  parallel across different directories.
 - 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

@@ -111,6 +111,8 @@ opensteer close --session demo
 ```
 
 For non-interactive runs, set `OPENSTEER_SESSION` or `OPENSTEER_CLIENT_ID`.
+Runtime daemon routing for `OPENSTEER_SESSION` is scoped by canonical `cwd`
+(`realpath(cwd)`) + logical session id.
 
 ## For AI Agents
 
@@ -134,12 +136,6 @@ Install the Opensteer skill pack:
 opensteer skills install
 ```
 
-Fallback (direct upstream `skills` CLI):
-
-```bash
-npx skills add https://github.com/steerlabs/opensteer-skills --skill opensteer
-```
-
 Claude Code marketplace plugin:
 
 ```text

package/bin/opensteer.mjs

@@ -6,6 +6,7 @@ import {
     closeSync,
     existsSync,
     openSync,
+    realpathSync,
     readFileSync,
     readdirSync,
     unlinkSync,
@@ -55,11 +56,13 @@ const RUNTIME_PREFIX = 'opensteer-'
 const SOCKET_SUFFIX = '.sock'
 const PID_SUFFIX = '.pid'
 const LOCK_SUFFIX = '.lock'
+const METADATA_SUFFIX = '.meta.json'
 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_-]+$/
+const RUNTIME_SESSION_PREFIX = 'sc-'
 
 function getVersion() {
     try {
@@ -214,7 +217,20 @@ function isInteractiveTerminal() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY)
 }
 
-function resolveSession(flags) {
+function resolveScopeDir() {
+    const cwd = process.cwd()
+    try {
+        return realpathSync(cwd)
+    } catch {
+        return cwd
+    }
+}
+
+function buildRuntimeSession(scopeDir, logicalSession) {
+    return `${RUNTIME_SESSION_PREFIX}${hashKey(`${scopeDir}:${logicalSession}`).slice(0, 24)}`
+}
+
+function resolveSession(flags, scopeDir) {
     if (flags.session !== undefined) {
         if (flags.session === true) {
             throw new Error('--session requires a session id value.')
@@ -244,7 +260,7 @@ function resolveSession(flags) {
         process.env.OPENSTEER_CLIENT_ID.trim().length > 0
     ) {
         const clientId = process.env.OPENSTEER_CLIENT_ID.trim()
-        const clientKey = `client:${process.cwd()}:${clientId}`
+        const clientKey = `client:${scopeDir}:${clientId}`
         const bound = readClientBinding(clientKey)
         if (bound) {
             return { session: bound, source: 'client_binding' }
@@ -256,7 +272,7 @@ function resolveSession(flags) {
     }
 
     if (isInteractiveTerminal()) {
-        const ttyKey = `tty:${process.cwd()}:${process.ppid}`
+        const ttyKey = `tty:${scopeDir}:${process.ppid}`
         const bound = readClientBinding(ttyKey)
         if (bound) {
             return { session: bound, source: 'tty_default' }
@@ -284,6 +300,10 @@ function getLockPath(session) {
     return join(tmpdir(), `${RUNTIME_PREFIX}${session}${LOCK_SUFFIX}`)
 }
 
+function getMetadataPath(session) {
+    return join(tmpdir(), `${RUNTIME_PREFIX}${session}${METADATA_SUFFIX}`)
+}
+
 function buildRequest(command, flags, positional) {
     const id = 1
     const globalFlags = {}
@@ -430,20 +450,80 @@ function cleanStaleFiles(session, options = {}) {
             unlinkSync(getPidPath(session))
         } catch { }
     }
+
+    try {
+        unlinkSync(getMetadataPath(session))
+    } catch { }
 }
 
-function startServer(session) {
+function startServer(runtimeSession, logicalSession, scopeDir) {
     const child = spawn('node', [SERVER_SCRIPT], {
         detached: true,
         stdio: ['ignore', 'ignore', 'ignore'],
         env: {
             ...process.env,
-            OPENSTEER_SESSION: session,
+            OPENSTEER_SESSION: runtimeSession,
+            OPENSTEER_LOGICAL_SESSION: logicalSession,
+            OPENSTEER_SCOPE_DIR: scopeDir,
         },
     })
     child.unref()
 }
 
+function readMetadata(session) {
+    const metadataPath = getMetadataPath(session)
+    if (!existsSync(metadataPath)) {
+        return null
+    }
+
+    try {
+        const raw = JSON.parse(readFileSync(metadataPath, 'utf-8'))
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            return null
+        }
+
+        if (
+            typeof raw.logicalSession !== 'string' ||
+            !raw.logicalSession.trim() ||
+            typeof raw.scopeDir !== 'string' ||
+            !raw.scopeDir.trim() ||
+            typeof raw.runtimeSession !== 'string' ||
+            !raw.runtimeSession.trim()
+        ) {
+            return null
+        }
+
+        return {
+            logicalSession: raw.logicalSession.trim(),
+            scopeDir: raw.scopeDir,
+            runtimeSession: raw.runtimeSession.trim(),
+            createdAt:
+                typeof raw.createdAt === 'number' ? raw.createdAt : undefined,
+            updatedAt:
+                typeof raw.updatedAt === 'number' ? raw.updatedAt : undefined,
+        }
+    } catch {
+        return null
+    }
+}
+
+function writeMetadata(runtimeSession, logicalSession, scopeDir) {
+    const metadataPath = getMetadataPath(runtimeSession)
+    const existing = readMetadata(runtimeSession)
+    const now = Date.now()
+    const payload = {
+        runtimeSession,
+        logicalSession,
+        scopeDir,
+        createdAt: existing?.createdAt ?? now,
+        updatedAt: now,
+    }
+
+    try {
+        writeFileSync(metadataPath, JSON.stringify(payload, null, 2))
+    } catch { }
+}
+
 function sendCommand(socketPath, request, timeoutMs = RESPONSE_TIMEOUT) {
     return new Promise((resolve, reject) => {
         const socket = connect(socketPath)
@@ -606,8 +686,14 @@ async function waitForServerReady(session, timeout) {
     throw new Error(`Timed out waiting for server '${session}' to become healthy.`)
 }
 
-async function ensureServer(session) {
-    if (await isServerHealthy(session)) {
+async function ensureServer(context) {
+    const runtimeSession = context.runtimeSession
+    if (await isServerHealthy(runtimeSession)) {
+        writeMetadata(
+            runtimeSession,
+            context.logicalSession,
+            context.scopeDir
+        )
         return
     }
 
@@ -620,31 +706,45 @@ async function ensureServer(session) {
     const deadline = Date.now() + CONNECT_TIMEOUT
 
     while (Date.now() < deadline) {
-        if (await isServerHealthy(session)) {
+        if (await isServerHealthy(runtimeSession)) {
+            writeMetadata(
+                runtimeSession,
+                context.logicalSession,
+                context.scopeDir
+            )
             return
         }
 
-        const existingPid = readPid(getPidPath(session))
+        const existingPid = readPid(getPidPath(runtimeSession))
         if (existingPid && isPidAlive(existingPid)) {
             await sleep(POLL_INTERVAL)
             continue
         }
 
-        recoverStaleStartLock(session)
+        recoverStaleStartLock(runtimeSession)
 
-        if (acquireStartLock(session)) {
+        if (acquireStartLock(runtimeSession)) {
             try {
-                if (!(await isServerHealthy(session))) {
-                    startServer(session)
+                if (!(await isServerHealthy(runtimeSession))) {
+                    startServer(
+                        runtimeSession,
+                        context.logicalSession,
+                        context.scopeDir
+                    )
                 }
 
                 await waitForServerReady(
-                    session,
+                    runtimeSession,
                     Math.max(500, deadline - Date.now())
                 )
+                writeMetadata(
+                    runtimeSession,
+                    context.logicalSession,
+                    context.scopeDir
+                )
                 return
             } finally {
-                releaseStartLock(session)
+                releaseStartLock(runtimeSession)
             }
         }
 
@@ -652,7 +752,7 @@ async function ensureServer(session) {
     }
 
     throw new Error(
-        `Failed to start server for session '${session}' within ${CONNECT_TIMEOUT}ms.`
+        `Failed to start server for session '${context.logicalSession}' in cwd scope '${context.scopeDir}' within ${CONNECT_TIMEOUT}ms.`
     )
 }
 
@@ -665,24 +765,39 @@ function listSessions() {
             continue
         }
 
-        const name = entry.slice(
+        const runtimeSession = entry.slice(
             RUNTIME_PREFIX.length,
             entry.length - PID_SUFFIX.length
         )
-        if (!name) {
+        if (!runtimeSession) {
             continue
         }
 
         const pid = readPid(join(tmpdir(), entry))
         if (!pid || !isPidAlive(pid)) {
-            cleanStaleFiles(name)
+            cleanStaleFiles(runtimeSession)
             continue
         }
 
-        sessions.push({ name, pid })
+        const metadata = readMetadata(runtimeSession)
+        sessions.push({
+            name: metadata?.logicalSession || runtimeSession,
+            logicalSession: metadata?.logicalSession || runtimeSession,
+            runtimeSession,
+            scopeDir: metadata?.scopeDir || null,
+            pid,
+        })
     }
 
-    sessions.sort((a, b) => a.name.localeCompare(b.name))
+    sessions.sort((a, b) => {
+        const scopeA = a.scopeDir || ''
+        const scopeB = b.scopeDir || ''
+        if (scopeA !== scopeB) {
+            return scopeA.localeCompare(scopeB)
+        }
+
+        return a.logicalSession.localeCompare(b.logicalSession)
+    })
     return sessions
 }
 
@@ -692,9 +807,9 @@ async function closeAllSessions() {
     const failures = []
 
     for (const session of sessions) {
-        const socketPath = getSocketPath(session.name)
+        const socketPath = getSocketPath(session.runtimeSession)
         if (!existsSync(socketPath)) {
-            cleanStaleFiles(session.name)
+            cleanStaleFiles(session.runtimeSession)
             continue
         }
 
@@ -704,12 +819,12 @@ async function closeAllSessions() {
                 closed.push(session)
             } else {
                 failures.push(
-                    `${session.name}: ${response?.error || 'unknown close error'}`
+                    `${session.logicalSession} (${session.scopeDir || 'unknown scope'}): ${response?.error || 'unknown close error'}`
                 )
             }
         } catch (err) {
             failures.push(
-                `${session.name}: ${err instanceof Error ? err.message : String(err)}`
+                `${session.logicalSession} (${session.scopeDir || 'unknown scope'}): ${err instanceof Error ? err.message : String(err)}`
             )
         }
     }
@@ -817,7 +932,7 @@ Navigation:
 
 Sessions:
   sessions                  List active session-scoped daemons
-  status                    Show resolved session/name and session state
+  status                    Show resolved logical/runtime session and session state
 
 Observation:
   snapshot [--mode action]  Get page snapshot
@@ -868,7 +983,7 @@ Skills:
   skills --help             Show skills installer help
 
 Global Flags:
-  --session <id>            Runtime session id for daemon/browser routing
+  --session <id>            Logical session id (scoped by canonical cwd)
   --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)
@@ -881,7 +996,7 @@ Global Flags:
   --version, -v             Show version
 
 Environment:
-  OPENSTEER_SESSION         Runtime session id (equivalent to --session)
+  OPENSTEER_SESSION         Logical 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 routing: "local" (default) or "cloud"
@@ -925,27 +1040,37 @@ async function main() {
 
     let resolvedSession
     let resolvedName
+    const scopeDir = resolveScopeDir()
     try {
-        resolvedSession = resolveSession(flags)
+        resolvedSession = resolveSession(flags, scopeDir)
         resolvedName = resolveName(flags, resolvedSession.session)
     } catch (err) {
         error(err instanceof Error ? err.message : 'Failed to resolve session')
     }
 
-    const session = resolvedSession.session
+    const logicalSession = resolvedSession.session
+    const runtimeSession = buildRuntimeSession(scopeDir, logicalSession)
     const sessionSource = resolvedSession.source
     const name = resolvedName.name
     const nameSource = resolvedName.source
-    const socketPath = getSocketPath(session)
+    const socketPath = getSocketPath(runtimeSession)
+    const routingContext = {
+        logicalSession,
+        runtimeSession,
+        scopeDir,
+    }
 
     if (command === 'status') {
         output({
             ok: true,
-            resolvedSession: session,
+            resolvedSession: logicalSession,
+            logicalSession,
+            runtimeSession,
+            scopeDir,
             sessionSource,
             resolvedName: name,
             nameSource,
-            serverRunning: await isServerHealthy(session),
+            serverRunning: await isServerHealthy(runtimeSession),
             socketPath,
             sessions: listSessions(),
         })
@@ -961,20 +1086,20 @@ async function main() {
         request.args.name = name
     }
 
-    if (!(await isServerHealthy(session))) {
+    if (!(await isServerHealthy(runtimeSession))) {
         if (command !== 'open') {
             error(
-                `No server running for session '${session}' (resolved from ${sessionSource}). Run 'opensteer open' first or use 'opensteer sessions' to see active sessions.`
+                `No server running for session '${logicalSession}' in cwd scope '${scopeDir}' (resolved from ${sessionSource}). Run 'opensteer open' first or use 'opensteer sessions' to see active sessions.`
             )
         }
 
         try {
-            await ensureServer(session)
+            await ensureServer(routingContext)
         } catch (err) {
             error(
                 err instanceof Error
                     ? err.message
-                    : `Failed to start server for session '${session}'.`
+                    : `Failed to start server for session '${logicalSession}' in cwd scope '${scopeDir}'.`
             )
         }
     }
@@ -992,7 +1117,7 @@ async function main() {
         error(
             formatTransportFailure(
                 err,
-                `Failed to run '${command}' for session '${session}'`
+                `Failed to run '${command}' for session '${logicalSession}' in cwd scope '${scopeDir}'`
             )
         )
     }

package/dist/{chunk-SXPIGCSD.js → chunk-XIH3WGPY.js}

@@ -2999,8 +2999,56 @@ function applyCleaner(mode, html) {
       return cleanForAction(html);
   }
 }
+function canonicalizeDuplicateNodeIds($) {
+  const occurrencesByNodeId = /* @__PURE__ */ new Map();
+  let order = 0;
+  $("*").each(function() {
+    const element = this;
+    const nodeId = $(element).attr(OS_NODE_ID_ATTR);
+    if (!nodeId) {
+      order += 1;
+      return;
+    }
+    const list = occurrencesByNodeId.get(nodeId) || [];
+    list.push({
+      element,
+      order
+    });
+    occurrencesByNodeId.set(nodeId, list);
+    order += 1;
+  });
+  for (const occurrences of occurrencesByNodeId.values()) {
+    if (occurrences.length <= 1) continue;
+    const canonical = pickCanonicalNodeIdOccurrence($, occurrences);
+    for (const occurrence of occurrences) {
+      if (occurrence.element === canonical.element) continue;
+      $(occurrence.element).removeAttr(OS_NODE_ID_ATTR);
+    }
+  }
+}
+function pickCanonicalNodeIdOccurrence($, occurrences) {
+  let best = occurrences[0];
+  let bestScore = scoreNodeIdOccurrence($, best.element);
+  for (let i = 1; i < occurrences.length; i += 1) {
+    const candidate = occurrences[i];
+    const candidateScore = scoreNodeIdOccurrence($, candidate.element);
+    if (candidateScore > bestScore || candidateScore === bestScore && candidate.order < best.order) {
+      best = candidate;
+      bestScore = candidateScore;
+    }
+  }
+  return best;
+}
+function scoreNodeIdOccurrence($, element) {
+  const el = $(element);
+  const descendantCount = el.find("*").length;
+  const normalizedTextLength = el.text().replace(/\s+/g, " ").trim().length;
+  const attributeCount = Object.keys(el.attr() || {}).length;
+  return descendantCount * 100 + normalizedTextLength * 10 + attributeCount;
+}
 async function assignCounters(page, html, nodePaths, nodeMeta) {
   const $ = cheerio3.load(html, { xmlMode: false });
+  canonicalizeDuplicateNodeIds($);
   const counterIndex = /* @__PURE__ */ new Map();
   let nextCounter = 1;
   const assignedByNodeId = /* @__PURE__ */ new Map();
@@ -3182,44 +3230,63 @@ function stripNodeIds(html) {
   $(`[${OS_NODE_ID_ATTR}]`).removeAttr(OS_NODE_ID_ATTR);
   return $.html();
 }
+function isLiveCounterSyncFailure(error) {
+  if (!(error instanceof Error)) return false;
+  return error.message.startsWith(
+    "Failed to synchronize snapshot counters with the live DOM:"
+  );
+}
 async function prepareSnapshot(page, options = {}) {
   const mode = options.mode ?? "action";
   const withCounters = options.withCounters ?? true;
   const shouldMarkInteractive = options.markInteractive ?? true;
-  if (shouldMarkInteractive) {
-    await markInteractiveElements(page);
-  }
-  const serialized = await serializePageHTML(page);
-  const rawHtml = serialized.html;
-  const processedHtml = rawHtml;
-  const reducedHtml = applyCleaner(mode, processedHtml);
-  let cleanedHtml = reducedHtml;
-  let counterIndex = null;
-  if (withCounters) {
-    const counted = await assignCounters(
-      page,
+  const maxAttempts = withCounters ? 4 : 1;
+  let lastCounterSyncError = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    if (shouldMarkInteractive) {
+      await markInteractiveElements(page);
+    }
+    const serialized = await serializePageHTML(page);
+    const rawHtml = serialized.html;
+    const processedHtml = rawHtml;
+    const reducedHtml = applyCleaner(mode, processedHtml);
+    let cleanedHtml = reducedHtml;
+    let counterIndex = null;
+    if (withCounters) {
+      try {
+        const counted = await assignCounters(
+          page,
+          reducedHtml,
+          serialized.nodePaths,
+          serialized.nodeMeta
+        );
+        cleanedHtml = counted.html;
+        counterIndex = counted.counterIndex;
+      } catch (error) {
+        if (attempt < maxAttempts && isLiveCounterSyncFailure(error)) {
+          lastCounterSyncError = error;
+          continue;
+        }
+        throw error;
+      }
+    } else {
+      cleanedHtml = stripNodeIds(cleanedHtml);
+    }
+    if (mode === "extraction") {
+      const $unwrap = cheerio3.load(cleanedHtml, { xmlMode: false });
+      cleanedHtml = $unwrap("body").html()?.trim() || cleanedHtml;
+    }
+    return {
+      mode,
+      url: page.url(),
+      rawHtml,
+      processedHtml,
       reducedHtml,
-      serialized.nodePaths,
-      serialized.nodeMeta
-    );
-    cleanedHtml = counted.html;
-    counterIndex = counted.counterIndex;
-  } else {
-    cleanedHtml = stripNodeIds(cleanedHtml);
-  }
-  if (mode === "extraction") {
-    const $unwrap = cheerio3.load(cleanedHtml, { xmlMode: false });
-    cleanedHtml = $unwrap("body").html()?.trim() || cleanedHtml;
+      cleanedHtml,
+      counterIndex
+    };
   }
-  return {
-    mode,
-    url: page.url(),
-    rawHtml,
-    processedHtml,
-    reducedHtml,
-    cleanedHtml,
-    counterIndex
-  };
+  throw lastCounterSyncError || new Error("Failed to prepare snapshot after retrying counter sync.");
 }
 
 // src/element-path/errors.ts

package/dist/cli/server.cjs

@@ -4219,8 +4219,56 @@ function applyCleaner(mode, html) {
       return cleanForAction(html);
   }
 }
+function canonicalizeDuplicateNodeIds($) {
+  const occurrencesByNodeId = /* @__PURE__ */ new Map();
+  let order = 0;
+  $("*").each(function() {
+    const element = this;
+    const nodeId = $(element).attr(OS_NODE_ID_ATTR);
+    if (!nodeId) {
+      order += 1;
+      return;
+    }
+    const list = occurrencesByNodeId.get(nodeId) || [];
+    list.push({
+      element,
+      order
+    });
+    occurrencesByNodeId.set(nodeId, list);
+    order += 1;
+  });
+  for (const occurrences of occurrencesByNodeId.values()) {
+    if (occurrences.length <= 1) continue;
+    const canonical = pickCanonicalNodeIdOccurrence($, occurrences);
+    for (const occurrence of occurrences) {
+      if (occurrence.element === canonical.element) continue;
+      $(occurrence.element).removeAttr(OS_NODE_ID_ATTR);
+    }
+  }
+}
+function pickCanonicalNodeIdOccurrence($, occurrences) {
+  let best = occurrences[0];
+  let bestScore = scoreNodeIdOccurrence($, best.element);
+  for (let i = 1; i < occurrences.length; i += 1) {
+    const candidate = occurrences[i];
+    const candidateScore = scoreNodeIdOccurrence($, candidate.element);
+    if (candidateScore > bestScore || candidateScore === bestScore && candidate.order < best.order) {
+      best = candidate;
+      bestScore = candidateScore;
+    }
+  }
+  return best;
+}
+function scoreNodeIdOccurrence($, element) {
+  const el = $(element);
+  const descendantCount = el.find("*").length;
+  const normalizedTextLength = el.text().replace(/\s+/g, " ").trim().length;
+  const attributeCount = Object.keys(el.attr() || {}).length;
+  return descendantCount * 100 + normalizedTextLength * 10 + attributeCount;
+}
 async function assignCounters(page, html, nodePaths, nodeMeta) {
   const $ = cheerio3.load(html, { xmlMode: false });
+  canonicalizeDuplicateNodeIds($);
   const counterIndex = /* @__PURE__ */ new Map();
   let nextCounter = 1;
   const assignedByNodeId = /* @__PURE__ */ new Map();
@@ -4402,44 +4450,63 @@ function stripNodeIds(html) {
   $(`[${OS_NODE_ID_ATTR}]`).removeAttr(OS_NODE_ID_ATTR);
   return $.html();
 }
+function isLiveCounterSyncFailure(error) {
+  if (!(error instanceof Error)) return false;
+  return error.message.startsWith(
+    "Failed to synchronize snapshot counters with the live DOM:"
+  );
+}
 async function prepareSnapshot(page, options = {}) {
   const mode = options.mode ?? "action";
   const withCounters = options.withCounters ?? true;
   const shouldMarkInteractive = options.markInteractive ?? true;
-  if (shouldMarkInteractive) {
-    await markInteractiveElements(page);
-  }
-  const serialized = await serializePageHTML(page);
-  const rawHtml = serialized.html;
-  const processedHtml = rawHtml;
-  const reducedHtml = applyCleaner(mode, processedHtml);
-  let cleanedHtml = reducedHtml;
-  let counterIndex = null;
-  if (withCounters) {
-    const counted = await assignCounters(
-      page,
+  const maxAttempts = withCounters ? 4 : 1;
+  let lastCounterSyncError = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    if (shouldMarkInteractive) {
+      await markInteractiveElements(page);
+    }
+    const serialized = await serializePageHTML(page);
+    const rawHtml = serialized.html;
+    const processedHtml = rawHtml;
+    const reducedHtml = applyCleaner(mode, processedHtml);
+    let cleanedHtml = reducedHtml;
+    let counterIndex = null;
+    if (withCounters) {
+      try {
+        const counted = await assignCounters(
+          page,
+          reducedHtml,
+          serialized.nodePaths,
+          serialized.nodeMeta
+        );
+        cleanedHtml = counted.html;
+        counterIndex = counted.counterIndex;
+      } catch (error) {
+        if (attempt < maxAttempts && isLiveCounterSyncFailure(error)) {
+          lastCounterSyncError = error;
+          continue;
+        }
+        throw error;
+      }
+    } else {
+      cleanedHtml = stripNodeIds(cleanedHtml);
+    }
+    if (mode === "extraction") {
+      const $unwrap = cheerio3.load(cleanedHtml, { xmlMode: false });
+      cleanedHtml = $unwrap("body").html()?.trim() || cleanedHtml;
+    }
+    return {
+      mode,
+      url: page.url(),
+      rawHtml,
+      processedHtml,
       reducedHtml,
-      serialized.nodePaths,
-      serialized.nodeMeta
-    );
-    cleanedHtml = counted.html;
-    counterIndex = counted.counterIndex;
-  } else {
-    cleanedHtml = stripNodeIds(cleanedHtml);
-  }
-  if (mode === "extraction") {
-    const $unwrap = cheerio3.load(cleanedHtml, { xmlMode: false });
-    cleanedHtml = $unwrap("body").html()?.trim() || cleanedHtml;
+      cleanedHtml,
+      counterIndex
+    };
   }
-  return {
-    mode,
-    url: page.url(),
-    rawHtml,
-    processedHtml,
-    reducedHtml,
-    cleanedHtml,
-    counterIndex
-  };
+  throw lastCounterSyncError || new Error("Failed to prepare snapshot after retrying counter sync.");
 }
 
 // src/element-path/errors.ts
@@ -12538,6 +12605,9 @@ function getSocketPath(session2) {
 function getPidPath(session2) {
   return (0, import_path6.join)((0, import_os2.tmpdir)(), `${prefix(session2)}.pid`);
 }
+function getMetadataPath(session2) {
+  return (0, import_path6.join)((0, import_os2.tmpdir)(), `${prefix(session2)}.meta.json`);
+}
 
 // src/cli/commands.ts
 var import_promises2 = require("fs/promises");
@@ -12806,6 +12876,8 @@ if (!sessionEnv) {
   process.exit(1);
 }
 var session = sessionEnv;
+var logicalSession = process.env.OPENSTEER_LOGICAL_SESSION?.trim() || session;
+var scopeDir = process.env.OPENSTEER_SCOPE_DIR?.trim() || process.cwd();
 var socketPath = getSocketPath(session);
 var pidPath = getPidPath(session);
 function cleanup() {
@@ -12817,6 +12889,10 @@ function cleanup() {
     (0, import_fs4.unlinkSync)(pidPath);
   } catch {
   }
+  try {
+    (0, import_fs4.unlinkSync)(getMetadataPath(session));
+  } catch {
+  }
 }
 function beginShutdown() {
   if (shuttingDown) return;
@@ -12858,10 +12934,15 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `Session '${session}' is shutting down.`,
+      error: `Session '${logicalSession}' is shutting down.`,
       errorInfo: {
-        message: `Session '${session}' is shutting down.`,
-        code: "SESSION_SHUTTING_DOWN"
+        message: `Session '${logicalSession}' is shutting down.`,
+        code: "SESSION_SHUTTING_DOWN",
+        details: {
+          session: logicalSession,
+          runtimeSession: session,
+          scopeDir
+        }
       }
     });
     return;
@@ -12870,10 +12951,15 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `Session '${session}' is shutting down. Retry your command.`,
+      error: `Session '${logicalSession}' is shutting down. Retry your command.`,
       errorInfo: {
-        message: `Session '${session}' is shutting down. Retry your command.`,
-        code: "SESSION_SHUTTING_DOWN"
+        message: `Session '${logicalSession}' is shutting down. Retry your command.`,
+        code: "SESSION_SHUTTING_DOWN",
+        details: {
+          session: logicalSession,
+          runtimeSession: session,
+          scopeDir
+        }
       }
     });
     return;
@@ -12890,12 +12976,14 @@ async function handleRequest(request, socket) {
         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.`,
+          error: `Session '${logicalSession}' is already bound to selector namespace '${selectorNamespace}'. Requested '${requestedName}' does not match. Use the same --name for this session or start a different --session.`,
           errorInfo: {
-            message: `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.`,
+            message: `Session '${logicalSession}' is already bound to selector namespace '${selectorNamespace}'. Requested '${requestedName}' does not match. Use the same --name for this session or start a different --session.`,
             code: "SESSION_NAMESPACE_MISMATCH",
             details: {
-              session,
+              session: logicalSession,
+              runtimeSession: session,
+              scopeDir,
               activeNamespace: selectorNamespace,
               requestedNamespace: requestedName
             }
@@ -12904,9 +12992,9 @@ async function handleRequest(request, socket) {
         return;
       }
       if (!selectorNamespace) {
-        selectorNamespace = requestedName ?? session;
+        selectorNamespace = requestedName ?? logicalSession;
       }
-      const activeNamespace = selectorNamespace ?? session;
+      const activeNamespace = selectorNamespace ?? logicalSession;
       if (instance && !launchPromise) {
         try {
           if (instance.page.isClosed()) {
@@ -12943,14 +13031,17 @@ async function handleRequest(request, socket) {
         await launchPromise;
       }
       if (url) {
-        await instance.page.goto(url);
+        await instance.goto(url);
       }
       sendResponse(socket, {
         id,
         ok: true,
         result: {
           url: instance.page.url(),
-          session,
+          session: logicalSession,
+          logicalSession,
+          runtimeSession: session,
+          scopeDir,
           name: activeNamespace,
           cloudSessionId: instance.getCloudSessionId() ?? void 0,
           cloudSessionUrl: instance.getCloudSessionUrl() ?? void 0
@@ -12992,12 +13083,14 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `No browser session in session '${session}'. Call 'opensteer open --session ${session}' first, or use 'opensteer sessions' to list active sessions.`,
+      error: `No browser session in session '${logicalSession}' (scope '${scopeDir}'). Call 'opensteer open --session ${logicalSession}' first, or use 'opensteer sessions' to list active sessions.`,
       errorInfo: {
-        message: `No browser session in session '${session}'. Call 'opensteer open --session ${session}' first, or use 'opensteer sessions' to list active sessions.`,
+        message: `No browser session in session '${logicalSession}' (scope '${scopeDir}'). Call 'opensteer open --session ${logicalSession}' first, or use 'opensteer sessions' to list active sessions.`,
         code: "SESSION_NOT_OPEN",
         details: {
-          session
+          session: logicalSession,
+          runtimeSession: session,
+          scopeDir
         }
       }
     });

package/dist/cli/server.js

@@ -1,7 +1,7 @@
 import {
   Opensteer,
   normalizeError
-} from "../chunk-SXPIGCSD.js";
+} from "../chunk-XIH3WGPY.js";
 import "../chunk-3H5RRIMZ.js";
 
 // src/cli/server.ts
@@ -20,6 +20,9 @@ function getSocketPath(session2) {
 function getPidPath(session2) {
   return join(tmpdir(), `${prefix(session2)}.pid`);
 }
+function getMetadataPath(session2) {
+  return join(tmpdir(), `${prefix(session2)}.meta.json`);
+}
 
 // src/cli/commands.ts
 import { writeFile } from "fs/promises";
@@ -288,6 +291,8 @@ if (!sessionEnv) {
   process.exit(1);
 }
 var session = sessionEnv;
+var logicalSession = process.env.OPENSTEER_LOGICAL_SESSION?.trim() || session;
+var scopeDir = process.env.OPENSTEER_SCOPE_DIR?.trim() || process.cwd();
 var socketPath = getSocketPath(session);
 var pidPath = getPidPath(session);
 function cleanup() {
@@ -299,6 +304,10 @@ function cleanup() {
     unlinkSync(pidPath);
   } catch {
   }
+  try {
+    unlinkSync(getMetadataPath(session));
+  } catch {
+  }
 }
 function beginShutdown() {
   if (shuttingDown) return;
@@ -340,10 +349,15 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `Session '${session}' is shutting down.`,
+      error: `Session '${logicalSession}' is shutting down.`,
       errorInfo: {
-        message: `Session '${session}' is shutting down.`,
-        code: "SESSION_SHUTTING_DOWN"
+        message: `Session '${logicalSession}' is shutting down.`,
+        code: "SESSION_SHUTTING_DOWN",
+        details: {
+          session: logicalSession,
+          runtimeSession: session,
+          scopeDir
+        }
       }
     });
     return;
@@ -352,10 +366,15 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `Session '${session}' is shutting down. Retry your command.`,
+      error: `Session '${logicalSession}' is shutting down. Retry your command.`,
       errorInfo: {
-        message: `Session '${session}' is shutting down. Retry your command.`,
-        code: "SESSION_SHUTTING_DOWN"
+        message: `Session '${logicalSession}' is shutting down. Retry your command.`,
+        code: "SESSION_SHUTTING_DOWN",
+        details: {
+          session: logicalSession,
+          runtimeSession: session,
+          scopeDir
+        }
       }
     });
     return;
@@ -372,12 +391,14 @@ async function handleRequest(request, socket) {
         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.`,
+          error: `Session '${logicalSession}' is already bound to selector namespace '${selectorNamespace}'. Requested '${requestedName}' does not match. Use the same --name for this session or start a different --session.`,
           errorInfo: {
-            message: `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.`,
+            message: `Session '${logicalSession}' is already bound to selector namespace '${selectorNamespace}'. Requested '${requestedName}' does not match. Use the same --name for this session or start a different --session.`,
             code: "SESSION_NAMESPACE_MISMATCH",
             details: {
-              session,
+              session: logicalSession,
+              runtimeSession: session,
+              scopeDir,
               activeNamespace: selectorNamespace,
               requestedNamespace: requestedName
             }
@@ -386,9 +407,9 @@ async function handleRequest(request, socket) {
         return;
       }
       if (!selectorNamespace) {
-        selectorNamespace = requestedName ?? session;
+        selectorNamespace = requestedName ?? logicalSession;
       }
-      const activeNamespace = selectorNamespace ?? session;
+      const activeNamespace = selectorNamespace ?? logicalSession;
       if (instance && !launchPromise) {
         try {
           if (instance.page.isClosed()) {
@@ -425,14 +446,17 @@ async function handleRequest(request, socket) {
         await launchPromise;
       }
       if (url) {
-        await instance.page.goto(url);
+        await instance.goto(url);
       }
       sendResponse(socket, {
         id,
         ok: true,
         result: {
           url: instance.page.url(),
-          session,
+          session: logicalSession,
+          logicalSession,
+          runtimeSession: session,
+          scopeDir,
           name: activeNamespace,
           cloudSessionId: instance.getCloudSessionId() ?? void 0,
           cloudSessionUrl: instance.getCloudSessionUrl() ?? void 0
@@ -474,12 +498,14 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `No browser session in session '${session}'. Call 'opensteer open --session ${session}' first, or use 'opensteer sessions' to list active sessions.`,
+      error: `No browser session in session '${logicalSession}' (scope '${scopeDir}'). Call 'opensteer open --session ${logicalSession}' first, or use 'opensteer sessions' to list active sessions.`,
       errorInfo: {
-        message: `No browser session in session '${session}'. Call 'opensteer open --session ${session}' first, or use 'opensteer sessions' to list active sessions.`,
+        message: `No browser session in session '${logicalSession}' (scope '${scopeDir}'). Call 'opensteer open --session ${logicalSession}' first, or use 'opensteer sessions' to list active sessions.`,
         code: "SESSION_NOT_OPEN",
         details: {
-          session
+          session: logicalSession,
+          runtimeSession: session,
+          scopeDir
         }
       }
     });

package/dist/index.cjs

@@ -4303,8 +4303,56 @@ function applyCleaner(mode, html) {
       return cleanForAction(html);
   }
 }
+function canonicalizeDuplicateNodeIds($) {
+  const occurrencesByNodeId = /* @__PURE__ */ new Map();
+  let order = 0;
+  $("*").each(function() {
+    const element = this;
+    const nodeId = $(element).attr(OS_NODE_ID_ATTR);
+    if (!nodeId) {
+      order += 1;
+      return;
+    }
+    const list = occurrencesByNodeId.get(nodeId) || [];
+    list.push({
+      element,
+      order
+    });
+    occurrencesByNodeId.set(nodeId, list);
+    order += 1;
+  });
+  for (const occurrences of occurrencesByNodeId.values()) {
+    if (occurrences.length <= 1) continue;
+    const canonical = pickCanonicalNodeIdOccurrence($, occurrences);
+    for (const occurrence of occurrences) {
+      if (occurrence.element === canonical.element) continue;
+      $(occurrence.element).removeAttr(OS_NODE_ID_ATTR);
+    }
+  }
+}
+function pickCanonicalNodeIdOccurrence($, occurrences) {
+  let best = occurrences[0];
+  let bestScore = scoreNodeIdOccurrence($, best.element);
+  for (let i = 1; i < occurrences.length; i += 1) {
+    const candidate = occurrences[i];
+    const candidateScore = scoreNodeIdOccurrence($, candidate.element);
+    if (candidateScore > bestScore || candidateScore === bestScore && candidate.order < best.order) {
+      best = candidate;
+      bestScore = candidateScore;
+    }
+  }
+  return best;
+}
+function scoreNodeIdOccurrence($, element) {
+  const el = $(element);
+  const descendantCount = el.find("*").length;
+  const normalizedTextLength = el.text().replace(/\s+/g, " ").trim().length;
+  const attributeCount = Object.keys(el.attr() || {}).length;
+  return descendantCount * 100 + normalizedTextLength * 10 + attributeCount;
+}
 async function assignCounters(page, html, nodePaths, nodeMeta) {
   const $ = cheerio3.load(html, { xmlMode: false });
+  canonicalizeDuplicateNodeIds($);
   const counterIndex = /* @__PURE__ */ new Map();
   let nextCounter = 1;
   const assignedByNodeId = /* @__PURE__ */ new Map();
@@ -4486,44 +4534,63 @@ function stripNodeIds(html) {
   $(`[${OS_NODE_ID_ATTR}]`).removeAttr(OS_NODE_ID_ATTR);
   return $.html();
 }
+function isLiveCounterSyncFailure(error) {
+  if (!(error instanceof Error)) return false;
+  return error.message.startsWith(
+    "Failed to synchronize snapshot counters with the live DOM:"
+  );
+}
 async function prepareSnapshot(page, options = {}) {
   const mode = options.mode ?? "action";
   const withCounters = options.withCounters ?? true;
   const shouldMarkInteractive = options.markInteractive ?? true;
-  if (shouldMarkInteractive) {
-    await markInteractiveElements(page);
-  }
-  const serialized = await serializePageHTML(page);
-  const rawHtml = serialized.html;
-  const processedHtml = rawHtml;
-  const reducedHtml = applyCleaner(mode, processedHtml);
-  let cleanedHtml = reducedHtml;
-  let counterIndex = null;
-  if (withCounters) {
-    const counted = await assignCounters(
-      page,
+  const maxAttempts = withCounters ? 4 : 1;
+  let lastCounterSyncError = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    if (shouldMarkInteractive) {
+      await markInteractiveElements(page);
+    }
+    const serialized = await serializePageHTML(page);
+    const rawHtml = serialized.html;
+    const processedHtml = rawHtml;
+    const reducedHtml = applyCleaner(mode, processedHtml);
+    let cleanedHtml = reducedHtml;
+    let counterIndex = null;
+    if (withCounters) {
+      try {
+        const counted = await assignCounters(
+          page,
+          reducedHtml,
+          serialized.nodePaths,
+          serialized.nodeMeta
+        );
+        cleanedHtml = counted.html;
+        counterIndex = counted.counterIndex;
+      } catch (error) {
+        if (attempt < maxAttempts && isLiveCounterSyncFailure(error)) {
+          lastCounterSyncError = error;
+          continue;
+        }
+        throw error;
+      }
+    } else {
+      cleanedHtml = stripNodeIds(cleanedHtml);
+    }
+    if (mode === "extraction") {
+      const $unwrap = cheerio3.load(cleanedHtml, { xmlMode: false });
+      cleanedHtml = $unwrap("body").html()?.trim() || cleanedHtml;
+    }
+    return {
+      mode,
+      url: page.url(),
+      rawHtml,
+      processedHtml,
       reducedHtml,
-      serialized.nodePaths,
-      serialized.nodeMeta
-    );
-    cleanedHtml = counted.html;
-    counterIndex = counted.counterIndex;
-  } else {
-    cleanedHtml = stripNodeIds(cleanedHtml);
-  }
-  if (mode === "extraction") {
-    const $unwrap = cheerio3.load(cleanedHtml, { xmlMode: false });
-    cleanedHtml = $unwrap("body").html()?.trim() || cleanedHtml;
+      cleanedHtml,
+      counterIndex
+    };
   }
-  return {
-    mode,
-    url: page.url(),
-    rawHtml,
-    processedHtml,
-    reducedHtml,
-    cleanedHtml,
-    counterIndex
-  };
+  throw lastCounterSyncError || new Error("Failed to prepare snapshot after retrying counter sync.");
 }
 
 // src/element-path/errors.ts

package/dist/index.js

@@ -77,7 +77,7 @@ import {
   switchTab,
   typeText,
   waitForVisualStability
-} from "./chunk-SXPIGCSD.js";
+} from "./chunk-XIH3WGPY.js";
 import {
   createResolveCallback
 } from "./chunk-SPHS6YWD.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opensteer",
-  "version": "0.5.3",
-  "description": "Open-source browser automation SDK with robust selectors and deterministic replay.",
+  "version": "0.5.5",
+  "description": "Open-source browser automation SDK and CLI that lets AI agents build complex scrapers directly in your codebase.",
   "license": "MIT",
   "type": "module",
   "bin": {