@web-auto/camo 0.1.21 → 0.1.23

package/README.md

@@ -176,7 +176,7 @@ camo stop --id <instanceId>
 camo stop --alias <alias>
 camo stop idle
 camo stop all
-camo status [profileId]
+camo status [profileId]                  # Show resolved per-profile session view
 camo shutdown                          # Shutdown browser-service (all sessions)
 ```
 
@@ -186,19 +186,53 @@ Use `--width/--height` to override and update the saved profile size.
 For headless sessions, default idle timeout is `30m` (auto-stop on inactivity). Use `--idle-timeout` (e.g. `45m`, `1800s`, `0`) to customize.
 Use `--devtools` to open browser developer tools in headed mode (cannot be combined with `--headless`).
 Use `--record` to auto-enable JSONL recording at startup; `--record-name`, `--record-output`, and `--record-overlay` customize file naming/output and floating toggle UI.
+Set `CAMO_BRING_TO_FRONT_MODE=never` to keep protocol-level input and page lifecycle operations from forcing the browser window to front during headed runs.
+`CAMO_SKIP_BRING_TO_FRONT=1` remains supported as a legacy alias.
 
 ### Lifecycle & Cleanup
 
 ```bash
-camo instances                         # List global camoufox instances (live + orphaned + idle state)
-camo sessions                          # List active browser sessions
-camo cleanup [profileId]               # Cleanup session (release lock + stop)
+camo instances                         # List resolved session view (live + registered + idle state)
+camo sessions                          # List resolved session view for all profiles
+camo cleanup [profileId]               # Cleanup only one profile (remote stop + local registry/lock/watchdog)
 camo cleanup all                       # Cleanup all active sessions
 camo cleanup locks                     # Cleanup stale lock files
-camo force-stop [profileId]            # Force stop session (for stuck sessions)
+camo force-stop [profileId]            # Force stop only one profile (no alias/id targeting)
 camo lock list                         # List active session locks
 ```
 
+Session isolation rules:
+- `profileId` is the lifecycle primary key across browser-service session, local registry, watchdog, and lock.
+- `camo start/stop/cleanup/force-stop <profileId>` only target that exact profile and must not affect other profiles.
+- `camo stop --id` and `camo stop --alias` are stop-only convenience selectors; `cleanup` and `force-stop` intentionally reject indirect targeting.
+- `camo status`, `camo sessions`, and `camo instances` share the same resolved session view fields:
+  - `live`: browser-service currently has this profile session
+  - `registered`: local registry has metadata for this profile
+  - `orphaned`: registry exists but the service session is gone
+  - `needsRecovery`: registry still says active but browser-service no longer has that profile
+
+Isolation examples:
+
+```bash
+# Observe both profiles independently
+camo sessions
+camo status finger
+camo status xhs-qa-1
+
+# Stop only finger; xhs-qa-1 must remain live
+camo stop finger
+camo status finger
+camo status xhs-qa-1
+
+# cleanup / force-stop require direct profile targeting
+camo cleanup finger
+camo force-stop finger
+
+# Invalid on purpose: indirect targeting is rejected
+camo cleanup --alias shard1
+camo force-stop --id inst_xxxxxxxx
+```
+
 ### Navigation
 
 ```bash
@@ -252,7 +286,7 @@ Recorder JSONL events include:
 camo new-page [profileId] [--url <url>]
 camo close-page [profileId] [index]
 camo switch-page [profileId] <index>
-camo list-pages [profileId]
+camo list-pages [profileId]             # Requires live=true for that profile
 ```
 
 ### Cookies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web-auto/camo",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Camoufox Browser CLI - Cross-platform browser automation",
   "type": "module",
   "bin": {

package/scripts/bump-version.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
- * Version bumper for camo CLI
- * Increments patch version maintaining 4-digit format (0.1.0001 -> 0.1.0002)
+ * Version bumper for camo CLI.
+ * Increments standard semver patch version (0.1.21 -> 0.1.22).
  */
 
 import { readFileSync, writeFileSync } from 'fs';
@@ -15,18 +15,14 @@ const packageJsonPath = join(__dirname, '..', 'package.json');
 function bumpVersion() {
   const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
   const currentVersion = pkg.version;
-  
-  // Parse version: 0.1.0001 -> [0, 1, 1]
   const parts = currentVersion.split('.');
   const major = parseInt(parts[0], 10);
   const minor = parseInt(parts[1], 10);
   let patch = parseInt(parts[2], 10);
-  
-  // Increment patch
+
   patch += 1;
-  
-  // Format with 4 digits
-  const newVersion = `${major}.${minor}.${patch.toString().padStart(4, '0')}`;
+
+  const newVersion = `${major}.${minor}.${patch}`;
   
   pkg.version = newVersion;
   writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2) + '\n');

package/src/commands/browser.mjs

@@ -7,7 +7,7 @@ import {
   getProfileWindowSize,
   setProfileWindowSize,
 } from '../utils/config.mjs';
-import { callAPI, ensureCamoufox, ensureBrowserService, getSessionByProfile, checkBrowserService } from '../utils/browser-service.mjs';
+import { callAPI, ensureCamoufox, ensureBrowserService, getSessionByProfile, checkBrowserService, getResolvedSessions } from '../utils/browser-service.mjs';
 import { resolveProfileId, ensureUrlScheme, looksLikeUrlToken, getPositionals } from '../utils/args.mjs';
 import { ensureJsExecutionEnabled } from '../utils/js-policy.mjs';
 import { acquireLock, releaseLock, cleanupStaleLocks } from '../lifecycle/lock.mjs';
@@ -298,6 +298,15 @@ async function stopAndCleanupProfile(profileId, options = {}) {
   };
 }
 
+async function loadResolvedSessions(serviceUp) {
+  if (!serviceUp) return [];
+  try {
+    return await getResolvedSessions();
+  } catch {
+    return [];
+  }
+}
+
 async function probeViewportSize(profileId) {
   try {
     const payload = await callAPI('evaluate', {
@@ -726,23 +735,17 @@ export async function handleStopCommand(args) {
   const stopIdle = target === 'idle' || args.includes('--idle');
   const stopAll = target === 'all';
   const serviceUp = await checkBrowserService();
+  const resolvedSessions = await loadResolvedSessions(serviceUp);
 
   if (stopAll) {
-    let liveSessions = [];
-    if (serviceUp) {
-      try {
-        const status = await callAPI('getStatus', {});
-        liveSessions = Array.isArray(status?.sessions) ? status.sessions : [];
-      } catch {
-        // Ignore and fallback to local registry.
+    const profileSet = new Set(resolvedSessions.map((item) => String(item?.profileId || '').trim()).filter(Boolean));
+    if (profileSet.size === 0) {
+      for (const session of listRegisteredSessions()) {
+        if (String(session?.status || '').trim() === 'closed') continue;
+        const profileId = String(session?.profileId || '').trim();
+        if (profileId) profileSet.add(profileId);
       }
     }
-    const profileSet = new Set(liveSessions.map((item) => String(item?.profileId || '').trim()).filter(Boolean));
-    for (const session of listRegisteredSessions()) {
-      if (String(session?.status || '').trim() === 'closed') continue;
-      const profileId = String(session?.profileId || '').trim();
-      if (profileId) profileSet.add(profileId);
-    }
 
     const results = [];
     for (const profileId of profileSet) {
@@ -763,15 +766,6 @@ export async function handleStopCommand(args) {
   if (stopIdle) {
     const now = Date.now();
     const registeredSessions = listRegisteredSessions();
-    let liveSessions = [];
-    if (serviceUp) {
-      try {
-        const status = await callAPI('getStatus', {});
-        liveSessions = Array.isArray(status?.sessions) ? status.sessions : [];
-      } catch {
-        // Ignore and fallback to local registry.
-      }
-    }
     const regMap = new Map(
       registeredSessions
         .filter((item) => item && String(item?.status || '').trim() === 'active')
@@ -785,7 +779,7 @@ export async function handleStopCommand(args) {
       .map((item) => item.session.profileId),
     );
     let orphanLiveHeadlessCount = 0;
-    for (const live of liveSessions) {
+    for (const live of resolvedSessions.filter((item) => item.live)) {
       const liveProfileId = String(live?.profileId || '').trim();
       if (!liveProfileId) continue;
       if (regMap.has(liveProfileId) || idleTargets.has(liveProfileId)) continue;
@@ -863,14 +857,15 @@ export async function handleStopCommand(args) {
 
 export async function handleStatusCommand(args) {
   await ensureBrowserService();
-  const result = await callAPI('getStatus', {});
   const profileId = args[1];
   if (profileId && args[0] === 'status') {
-    const session = result?.sessions?.find((s) => s.profileId === profileId) || null;
+    const sessions = await getResolvedSessions();
+    const session = sessions.find((item) => item.profileId === profileId) || null;
     console.log(JSON.stringify({ ok: true, session }, null, 2));
     return;
   }
-  console.log(JSON.stringify(result, null, 2));
+  const sessions = await getResolvedSessions();
+  console.log(JSON.stringify({ ok: true, sessions, count: sessions.length }, null, 2));
 }
 
 export async function handleGotoCommand(args) {
@@ -974,14 +969,32 @@ export async function handleScrollCommand(args) {
 
   const target = await callAPI('evaluate', {
     profileId,
-    script: buildScrollTargetScript({ selector, highlight }),
+    script: buildScrollTargetScript({ selector, highlight, requireVisibleContainer: Boolean(selector) }),
   }, { timeoutMs: INPUT_ACTION_TIMEOUT_MS });
+  const scrollTarget = target?.result || null;
+  if (!scrollTarget?.ok || !scrollTarget?.center) {
+    throw new Error(scrollTarget?.error || 'visible scroll container not found');
+  }
   const deltaX = direction === 'left' ? -amount : direction === 'right' ? amount : 0;
   const deltaY = direction === 'up' ? -amount : direction === 'down' ? amount : 0;
-  const result = await callAPI('mouse:wheel', { profileId, deltaX, deltaY }, { timeoutMs: INPUT_ACTION_TIMEOUT_MS });
+  await callAPI('mouse:click', {
+    profileId,
+    x: scrollTarget.center.x,
+    y: scrollTarget.center.y,
+    button: 'left',
+    clicks: 1,
+    delay: 30,
+  }, { timeoutMs: INPUT_ACTION_TIMEOUT_MS });
+  const result = await callAPI('mouse:wheel', {
+    profileId,
+    deltaX,
+    deltaY,
+    anchorX: scrollTarget.center.x,
+    anchorY: scrollTarget.center.y,
+  }, { timeoutMs: INPUT_ACTION_TIMEOUT_MS });
   console.log(JSON.stringify({
     ...result,
-    scrollTarget: target?.result || null,
+    scrollTarget,
     highlight,
   }, null, 2));
 }
@@ -1183,6 +1196,11 @@ export async function handleListPagesCommand(args) {
   await ensureBrowserService();
   const profileId = resolveProfileId(args, 1, getDefaultProfile);
   if (!profileId) throw new Error('Usage: camo list-pages [profileId] (or set default profile first)');
+  const sessions = await getResolvedSessions();
+  const session = sessions.find((item) => item.profileId === profileId) || null;
+  if (!session?.live) {
+    throw new Error(`Profile session not live: ${profileId}. Start via "camo start ${profileId}" first.`);
+  }
   const result = await callAPI('page:list', { profileId });
   console.log(JSON.stringify(result, null, 2));
 }
@@ -1223,33 +1241,9 @@ export async function handleShutdownCommand() {
 
 export async function handleSessionsCommand(args) {
   const serviceUp = await checkBrowserService();
+  const merged = await loadResolvedSessions(serviceUp);
   const registeredSessions = listRegisteredSessions();
-  
-  let liveSessions = [];
-  if (serviceUp) {
-    try {
-      const status = await callAPI('getStatus', {});
-      liveSessions = Array.isArray(status?.sessions) ? status.sessions : [];
-    } catch {
-      // Service may have just become unavailable
-    }
-  }
-  
-  // Merge live and registered sessions
-  const liveProfileIds = new Set(liveSessions.map(s => s.profileId));
-  const merged = [...liveSessions];
-  
-  // Add registered sessions that are not in live sessions (need recovery)
-  for (const reg of registeredSessions) {
-    if (!liveProfileIds.has(reg.profileId) && reg.status === 'active') {
-      merged.push({
-        ...reg,
-        live: false,
-        needsRecovery: true,
-      });
-    }
-  }
-  
+
   console.log(JSON.stringify({
     ok: true,
     serviceUp,

package/src/commands/lifecycle.mjs

@@ -3,84 +3,26 @@
  * Lifecycle commands: cleanup, force-stop, lock management, session recovery
  */
 import { getDefaultProfile } from '../utils/config.mjs';
-import { callAPI, ensureBrowserService, checkBrowserService } from '../utils/browser-service.mjs';
+import { callAPI, ensureBrowserService, checkBrowserService, getResolvedSessions } from '../utils/browser-service.mjs';
 import { resolveProfileId } from '../utils/args.mjs';
 import { acquireLock, getLockInfo, releaseLock, cleanupStaleLocks, listActiveLocks } from '../lifecycle/lock.mjs';
-import { 
+import {
   getSessionInfo, unregisterSession, markSessionClosed, cleanupStaleSessions,
   listRegisteredSessions, updateSession
 } from '../lifecycle/session-registry.mjs';
 import { stopAllSessionWatchdogs, stopSessionWatchdog } from '../lifecycle/session-watchdog.mjs';
 
-const DEFAULT_HEADLESS_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
-
-function computeIdleState(session, now = Date.now()) {
-  const headless = session?.headless === true;
-  const timeoutMs = headless
-    ? (Number.isFinite(Number(session?.idleTimeoutMs)) ? Math.max(0, Number(session.idleTimeoutMs)) : DEFAULT_HEADLESS_IDLE_TIMEOUT_MS)
-    : 0;
-  const lastAt = Number(session?.lastActivityAt || session?.lastSeen || session?.startTime || now);
-  const idleMs = Math.max(0, now - (Number.isFinite(lastAt) ? lastAt : now));
-  const idle = headless && timeoutMs > 0 && idleMs >= timeoutMs;
-  return { headless, timeoutMs, idleMs, idle };
-}
-
-function buildMergedSessionRows(liveSessions, registeredSessions) {
-  const now = Date.now();
-  const regMap = new Map(registeredSessions.map((item) => [item.profileId, item]));
-  const rows = [];
-  const liveMap = new Map(liveSessions.map((item) => [item.profileId, item]));
-
-  for (const live of liveSessions) {
-    const reg = regMap.get(live.profileId);
-    const idle = computeIdleState(reg || {}, now);
-    rows.push({
-      profileId: live.profileId,
-      sessionId: live.session_id || live.profileId,
-      instanceId: reg?.instanceId || live.session_id || live.profileId,
-      alias: reg?.alias || null,
-      url: live.current_url,
-      mode: live.mode,
-      headless: idle.headless,
-      idleTimeoutMs: idle.timeoutMs,
-      idleMs: idle.idleMs,
-      idle: idle.idle,
-      live: true,
-      registered: !!reg,
-      registryStatus: reg?.status,
-      lastSeen: reg?.lastSeen || null,
-      lastActivityAt: reg?.lastActivityAt || null,
-    });
+function rejectIndirectSessionTargeting(commandName, args) {
+  if (args.includes('--id')) {
+    throw new Error(`Usage: camo ${commandName} [profileId] (direct profile only; --id is only supported by "camo stop")`);
   }
-
-  for (const reg of registeredSessions) {
-    if (liveMap.has(reg.profileId)) continue;
-    if (reg.status === 'closed') continue;
-    const idle = computeIdleState(reg, now);
-    rows.push({
-      profileId: reg.profileId,
-      sessionId: reg.sessionId || reg.profileId,
-      instanceId: reg.instanceId || reg.sessionId || reg.profileId,
-      alias: reg.alias || null,
-      url: reg.url || null,
-      mode: reg.mode || null,
-      headless: idle.headless,
-      idleTimeoutMs: idle.timeoutMs,
-      idleMs: idle.idleMs,
-      idle: idle.idle,
-      live: false,
-      orphaned: true,
-      needsRecovery: reg.status === 'active',
-      registered: true,
-      registryStatus: reg.status,
-      lastSeen: reg.lastSeen || null,
-      lastActivityAt: reg.lastActivityAt || null,
-    });
+  if (args.includes('--alias')) {
+    throw new Error(`Usage: camo ${commandName} [profileId] (direct profile only; --alias is only supported by "camo stop")`);
   }
-  return rows;
 }
 
 export async function handleCleanupCommand(args) {
+  rejectIndirectSessionTargeting('cleanup', args);
   const sub = args[1];
   
   if (sub === 'locks') {
@@ -158,6 +100,7 @@ export async function handleCleanupCommand(args) {
 }
 
 export async function handleForceStopCommand(args) {
+  rejectIndirectSessionTargeting('force-stop', args);
   await ensureBrowserService();
   const profileId = resolveProfileId(args, 1, getDefaultProfile);
   if (!profileId) throw new Error('Usage: camo force-stop [profileId]');
@@ -217,24 +160,45 @@ export async function handleUnlockCommand(args) {
 export async function handleSessionsCommand(args) {
   const serviceUp = await checkBrowserService();
   const registeredSessions = listRegisteredSessions();
-  
-  let liveSessions = [];
+  let merged = [];
   if (serviceUp) {
     try {
-      const status = await callAPI('getStatus', {});
-      liveSessions = Array.isArray(status?.sessions) ? status.sessions : [];
-    } catch {}
+      merged = await getResolvedSessions();
+    } catch {
+      merged = [];
+    }
+  } else {
+    merged = registeredSessions
+      .filter((item) => String(item?.status || '').trim() !== 'closed')
+      .map((item) => ({
+        profileId: item.profileId,
+        sessionId: item.sessionId || item.profileId,
+        instanceId: item.instanceId || item.sessionId || item.profileId,
+        alias: item.alias || null,
+        url: item.url || null,
+        mode: item.mode || null,
+        ownerPid: Number(item?.ownerPid || item?.pid || 0) || null,
+        headless: item.headless === true,
+        idleTimeoutMs: Number(item.idleTimeoutMs || 0) || 0,
+        idleMs: 0,
+        idle: false,
+        live: false,
+        registered: true,
+        orphaned: true,
+        needsRecovery: String(item.status || '').trim() === 'active',
+        registryStatus: item.status || null,
+        lastSeen: item.lastSeen || null,
+        lastActivityAt: item.lastActivityAt || null,
+      }));
   }
-  
-  const merged = buildMergedSessionRows(liveSessions, registeredSessions);
-  
+
   console.log(JSON.stringify({
     ok: true,
     serviceUp,
     sessions: merged,
     count: merged.length,
     registered: registeredSessions.length,
-    live: liveSessions.length,
+    live: merged.filter((item) => item.live).length,
     orphaned: merged.filter(s => s.orphaned).length,
   }, null, 2));
 }
@@ -272,24 +236,24 @@ export async function handleRecoverCommand(args) {
   
   // Service is up - check if session is still there
   try {
-    const status = await callAPI('getStatus', {});
-    const existing = status?.sessions?.find(s => s.profileId === profileId);
-    
+    const sessions = await getResolvedSessions();
+    const existing = sessions.find((item) => item.profileId === profileId && item.live);
+
     if (existing) {
       // Session is alive - update registry
       updateSession(profileId, {
-        sessionId: existing.session_id || existing.profileId,
-        url: existing.current_url,
+        sessionId: existing.sessionId || existing.profileId,
+        url: existing.url,
         status: 'active',
         recoveredAt: Date.now(),
       });
-      acquireLock(profileId, { sessionId: existing.session_id || existing.profileId });
+      acquireLock(profileId, { sessionId: existing.sessionId || existing.profileId });
       console.log(JSON.stringify({
         ok: true,
         recovered: true,
         profileId,
-        sessionId: existing.session_id || existing.profileId,
-        url: existing.current_url,
+        sessionId: existing.sessionId || existing.profileId,
+        url: existing.url,
         message: 'Session reconnected successfully',
       }, null, 2));
     } else {

package/src/container/runtime-core/operations/index.mjs

@@ -626,7 +626,24 @@ export async function executeOperation({ profileId, operation, context = {} }) {
         selector: anchorSelector,
         filterMode,
       });
-      const result = await callAPI('mouse:wheel', { profileId: resolvedProfile, deltaX, deltaY });
+      if (!anchor?.ok || !anchor?.center) {
+        return asErrorPayload('OPERATION_FAILED', 'visible scroll container not found');
+      }
+      await callAPI('mouse:click', {
+        profileId: resolvedProfile,
+        x: anchor.center.x,
+        y: anchor.center.y,
+        button: 'left',
+        clicks: 1,
+        delay: 30,
+      });
+      const result = await callAPI('mouse:wheel', {
+        profileId: resolvedProfile,
+        deltaX,
+        deltaY,
+        anchorX: anchor.center.x,
+        anchorY: anchor.center.y,
+      });
       return {
         ok: true,
         code: 'OPERATION_DONE',
@@ -638,6 +655,7 @@ export async function executeOperation({ profileId, operation, context = {} }) {
           deltaY,
           filterMode,
           anchorSource: String(anchor?.source || 'document'),
+          anchorCenter: anchor?.center || null,
           modalLocked: anchor?.modalLocked === true,
           result,
         },

package/src/container/runtime-core/operations/selector-scripts.mjs

@@ -159,11 +159,13 @@ export function buildSelectorTypeScript({ selector, highlight, text }) {
   })()`;
 }
 
-export function buildScrollTargetScript({ selector, highlight }) {
+export function buildScrollTargetScript({ selector, highlight, requireVisibleContainer = false }) {
   const selectorLiteral = JSON.stringify(String(selector || '').trim() || null);
   const highlightLiteral = asBoolLiteral(highlight);
+  const requireVisibleContainerLiteral = asBoolLiteral(requireVisibleContainer);
   return `(() => {
     const selector = ${selectorLiteral};
+    const requireVisibleContainer = ${requireVisibleContainerLiteral};
     const isVisible = (node) => {
       if (!(node instanceof Element)) return false;
       const rect = node.getBoundingClientRect?.();
@@ -183,11 +185,13 @@ export function buildScrollTargetScript({ selector, highlight }) {
       const style = window.getComputedStyle(node);
       const overflowY = String(style.overflowY || '');
       const overflowX = String(style.overflowX || '');
+      const scrollableSelectors = ['.comments-container', '.comment-list', '.comments-el', '.note-scroller'];
+      const selectorScrollable = scrollableSelectors.some((sel) => typeof node.matches === 'function' && node.matches(sel));
       const yScrollable = (overflowY.includes('auto') || overflowY.includes('scroll') || overflowY.includes('overlay'))
         && (node.scrollHeight - node.clientHeight > 2);
       const xScrollable = (overflowX.includes('auto') || overflowX.includes('scroll') || overflowX.includes('overlay'))
         && (node.scrollWidth - node.clientWidth > 2);
-      return yScrollable || xScrollable;
+      return yScrollable || xScrollable || selectorScrollable;
     };
     const findScrollableAncestor = (node) => {
       let cursor = node instanceof Element ? node : null;
@@ -203,9 +207,12 @@ export function buildScrollTargetScript({ selector, highlight }) {
     if (selector) {
       const list = Array.from(document.querySelectorAll(selector));
       target = list.find((node) => isVisible(node) && isScrollable(node))
-        || list.find((node) => isVisible(node))
+        || list.map((node) => findScrollableAncestor(node)).find((node) => isVisible(node))
         || null;
       if (target) source = 'selector';
+      if (!target && requireVisibleContainer) {
+        return { ok: false, error: 'visible_scroll_container_not_found', selector };
+      }
     }
     if (!target) {
       const active = document.activeElement instanceof Element ? document.activeElement : null;
@@ -250,9 +257,20 @@ export function buildScrollTargetScript({ selector, highlight }) {
       source,
       highlight: ${highlightLiteral},
       center: { x: centerX, y: centerY },
+      rect: {
+        left: Number(rect.left || 0),
+        top: Number(rect.top || 0),
+        width: Number(rect.width || 0),
+        height: Number(rect.height || 0)
+      },
       target: {
         tag: String(target.tagName || '').toLowerCase(),
-        id: target.id || null
+        id: target.id || null,
+        className: typeof target.className === 'string' ? target.className : null,
+        scrollHeight: Number(target.scrollHeight || 0),
+        clientHeight: Number(target.clientHeight || 0),
+        scrollWidth: Number(target.scrollWidth || 0),
+        clientWidth: Number(target.clientWidth || 0)
       }
     };
   })()`;

package/src/container/runtime-core/search.mjs

@@ -0,0 +1,190 @@
+import { buildSelectorCheck } from './utils.mjs';
+
+function normalizeQuery(raw) {
+  const text = String(raw || '').trim();
+  if (!text) return { query: '', queryLower: '' };
+  return { query: text, queryLower: text.toLowerCase() };
+}
+
+function normalizeDirection(raw) {
+  const text = String(raw || 'down').trim().toLowerCase();
+  if (text === 'up' || text === 'down' || text === 'both') return text;
+  return 'down';
+}
+
+function normalizeLimit(raw) {
+  const num = Number(raw);
+  if (!Number.isFinite(num) || num <= 0) return 1;
+  return Math.max(1, Math.floor(num));
+}
+
+function normalizeRect(node) {
+  const rect = node?.rect && typeof node.rect === 'object' ? node.rect : null;
+  if (!rect) return null;
+  const left = Number(rect.left ?? rect.x ?? 0);
+  const top = Number(rect.top ?? rect.y ?? 0);
+  const width = Number(rect.width ?? 0);
+  const height = Number(rect.height ?? 0);
+  if (!Number.isFinite(left) || !Number.isFinite(top) || !Number.isFinite(width) || !Number.isFinite(height)) return null;
+  if (width <= 0 || height <= 0) return null;
+  return { left, top, width, height, right: left + width, bottom: top + height };
+}
+
+function computeCenter(rect) {
+  if (!rect) return null;
+  return {
+    x: Math.round(rect.left + rect.width / 2),
+    y: Math.round(rect.top + rect.height / 2),
+  };
+}
+
+function buildSearchText(node) {
+  if (!node || typeof node !== 'object') return '';
+  const parts = [];
+  const snippet = typeof node.textSnippet === 'string' ? node.textSnippet : '';
+  if (snippet) parts.push(snippet);
+  const attrs = node.attrs && typeof node.attrs === 'object' ? node.attrs : null;
+  if (attrs) {
+    const candidates = [
+      attrs['aria-label'],
+      attrs['aria-label'.toLowerCase()],
+      attrs.title,
+      attrs.alt,
+      attrs.placeholder,
+    ];
+    for (const item of candidates) {
+      const text = typeof item === 'string' ? item.trim() : '';
+      if (text) parts.push(text);
+    }
+  }
+  return parts.join(' ').replace(/\s+/g, ' ').trim();
+}
+
+function isPathWithin(path, parentPath) {
+  const child = String(path || '').trim();
+  const parent = String(parentPath || '').trim();
+  if (!child || !parent) return false;
+  return child === parent || child.startsWith(`${parent}/`);
+}
+
+function collectMatches(node, options, path = 'root', out = []) {
+  if (!node) return out;
+  const { queryLower, visibleOnly } = options;
+  const visible = node.visible === true;
+  if (visibleOnly && !visible) {
+    return out;
+  }
+  {
+    const searchText = buildSearchText(node);
+    if (searchText && searchText.toLowerCase().includes(queryLower)) {
+      out.push({ node, path, searchText });
+    }
+  }
+  if (Array.isArray(node.children)) {
+    for (let i = 0; i < node.children.length; i += 1) {
+      collectMatches(node.children[i], options, `${path}/${i}`, out);
+    }
+  }
+  return out;
+}
+
+function sortMatches(matches, direction) {
+  const sorted = [...matches].sort((a, b) => {
+    const ra = normalizeRect(a.targetNode);
+    const rb = normalizeRect(b.targetNode);
+    const ta = ra ? ra.top : Number.POSITIVE_INFINITY;
+    const tb = rb ? rb.top : Number.POSITIVE_INFINITY;
+    if (ta !== tb) return ta - tb;
+    const la = ra ? ra.left : Number.POSITIVE_INFINITY;
+    const lb = rb ? rb.left : Number.POSITIVE_INFINITY;
+    return la - lb;
+  });
+  if (direction === 'up') return sorted.reverse();
+  return sorted;
+}
+
+function applyStartAfter(matches, startAfterPath) {
+  if (!startAfterPath) return matches;
+  const idx = matches.findIndex((item) => item.targetPath === startAfterPath || item.matchPath === startAfterPath);
+  if (idx < 0) return matches;
+  return matches.slice(idx + 1);
+}
+
+export function searchSnapshot(snapshot, rawOptions = {}) {
+  const { query, queryLower } = normalizeQuery(rawOptions.query || rawOptions.keyword || rawOptions.text);
+  if (!query) {
+    return { ok: false, code: 'QUERY_REQUIRED', message: 'search requires query keyword', data: { query } };
+  }
+  const direction = normalizeDirection(rawOptions.direction || 'down');
+  const limit = normalizeLimit(rawOptions.limit ?? rawOptions.maxResults ?? 1);
+  const visibleOnly = rawOptions.visibleOnly !== false;
+  const containerSelector = String(rawOptions.containerSelector || rawOptions.selector || '').trim() || null;
+  const startAfterPath = String(rawOptions.startAfterPath || rawOptions.afterPath || '').trim() || null;
+
+  const containerNodes = containerSelector
+    ? buildSelectorCheck(snapshot, { css: containerSelector, visible: visibleOnly })
+    : [];
+  const containerPaths = containerNodes.map((node) => node.path).filter(Boolean);
+
+  const matches = collectMatches(snapshot, { queryLower, visibleOnly }, 'root', []);
+  const enriched = matches.map((match) => {
+    let containerNode = null;
+    let containerPath = null;
+    if (containerPaths.length > 0) {
+      for (const path of containerPaths) {
+        if (isPathWithin(match.path, path)) {
+          containerPath = path;
+          break;
+        }
+      }
+      if (containerPath) {
+        containerNode = containerNodes.find((node) => node.path === containerPath) || null;
+      }
+    }
+    const targetNode = containerNode || match.node;
+    const rect = normalizeRect(targetNode);
+    const center = computeCenter(rect);
+    return {
+      matchPath: match.path,
+      targetPath: containerPath || match.path,
+      targetNode,
+      matchNode: match.node,
+      containerPath,
+      rect,
+      center,
+      searchText: match.searchText,
+    };
+  });
+
+  const filtered = containerSelector
+    ? enriched.filter((item) => item.containerPath)
+    : enriched;
+  const ordered = sortMatches(filtered, direction);
+  const sliced = applyStartAfter(ordered, startAfterPath).slice(0, limit);
+  const results = sliced.map((item) => ({
+    matchPath: item.matchPath,
+    targetPath: item.targetPath,
+    containerPath: item.containerPath,
+    rect: item.rect,
+    center: item.center,
+    text: item.searchText,
+  }));
+  const nextCursor = results.length > 0 ? results[results.length - 1].targetPath : startAfterPath;
+
+  return {
+    ok: true,
+    code: 'SEARCH_OK',
+    message: 'search done',
+    data: {
+      query,
+      direction,
+      limit,
+      visibleOnly,
+      containerSelector,
+      totalMatches: filtered.length,
+      returned: results.length,
+      nextCursor,
+      results,
+    },
+  };
+}

package/src/lifecycle/session-registry.mjs

@@ -25,6 +25,11 @@ function normalizeAlias(value) {
   return text.slice(0, 64);
 }
 
+function isAliasProtectedStatus(status) {
+  const normalized = String(status || '').trim().toLowerCase();
+  return normalized === 'active' || normalized === 'reconnecting';
+}
+
 function normalizeTimeoutMs(value) {
   const ms = Number(value);
   if (!Number.isFinite(ms) || ms < 0) return null;
@@ -159,10 +164,21 @@ export function resolveSessionTarget(target) {
   const sessions = listRegisteredSessions();
   const byProfile = sessions.find((item) => String(item?.profileId || '').trim() === value);
   if (byProfile) return { profileId: byProfile.profileId, reason: 'profile', session: byProfile };
-  const byInstanceId = sessions.find((item) => String(item?.instanceId || '').trim() === value);
-  if (byInstanceId) return { profileId: byInstanceId.profileId, reason: 'instanceId', session: byInstanceId };
-  const byAlias = sessions.find((item) => normalizeAlias(item?.alias) === normalizeAlias(value));
-  if (byAlias) return { profileId: byAlias.profileId, reason: 'alias', session: byAlias };
+  const byInstanceId = sessions.filter((item) => String(item?.instanceId || '').trim() === value);
+  if (byInstanceId.length > 1) {
+    throw new Error(`Ambiguous instance id target: ${value}`);
+  }
+  if (byInstanceId.length === 1) {
+    return { profileId: byInstanceId[0].profileId, reason: 'instanceId', session: byInstanceId[0] };
+  }
+  const normalizedAlias = normalizeAlias(value);
+  const byAlias = sessions.filter((item) => normalizeAlias(item?.alias) === normalizedAlias && isAliasProtectedStatus(item?.status));
+  if (byAlias.length > 1) {
+    throw new Error(`Ambiguous alias target: ${value}`);
+  }
+  if (byAlias.length === 1) {
+    return { profileId: byAlias[0].profileId, reason: 'alias', session: byAlias[0] };
+  }
   return null;
 }
 
@@ -173,7 +189,7 @@ export function isSessionAliasTaken(alias, exceptProfileId = '') {
   return listRegisteredSessions().some((item) => {
     if (!item) return false;
     if (except && String(item.profileId || '').trim() === except) return false;
-    if (String(item.status || '').trim() !== 'active') return false;
+    if (!isAliasProtectedStatus(item.status)) return false;
     return normalizeAlias(item.alias) === target;
   });
 }

package/src/lifecycle/session-view.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { listRegisteredSessions } from './session-registry.mjs';
+
+const DEFAULT_HEADLESS_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+
+function computeIdleState(session, now = Date.now()) {
+  const headless = session?.headless === true;
+  const timeoutMs = headless
+    ? (Number.isFinite(Number(session?.idleTimeoutMs)) ? Math.max(0, Number(session.idleTimeoutMs)) : DEFAULT_HEADLESS_IDLE_TIMEOUT_MS)
+    : 0;
+  const lastAt = Number(session?.lastActivityAt || session?.lastSeen || session?.startTime || now);
+  const idleMs = Math.max(0, now - (Number.isFinite(lastAt) ? lastAt : now));
+  const idle = headless && timeoutMs > 0 && idleMs >= timeoutMs;
+  return { headless, timeoutMs, idleMs, idle };
+}
+
+function normalizeLiveSession(session) {
+  if (!session) return null;
+  const profileId = String(session.profileId || session.session_id || '').trim();
+  if (!profileId) return null;
+  return {
+    profileId,
+    sessionId: session.session_id || session.sessionId || profileId,
+    url: session.current_url || session.url || null,
+    mode: session.mode || null,
+    ownerPid: Number(session.owner_pid || session.ownerPid || 0) || null,
+    live: true,
+    raw: session,
+  };
+}
+
+export function buildResolvedSessionView(liveSessions = [], registeredSessions = listRegisteredSessions()) {
+  const now = Date.now();
+  const regMap = new Map(registeredSessions.map((item) => [String(item?.profileId || '').trim(), item]).filter(([key]) => key));
+  const liveMap = new Map(liveSessions.map(normalizeLiveSession).filter(Boolean).map((item) => [item.profileId, item]));
+  const profileIds = new Set([...liveMap.keys(), ...regMap.keys()]);
+  const rows = [];
+
+  for (const profileId of profileIds) {
+    const live = liveMap.get(profileId) || null;
+    const reg = regMap.get(profileId) || null;
+    if (!live && reg && String(reg.status || '').trim() === 'closed') continue;
+    const idle = computeIdleState(reg || live || {}, now);
+    const registryStatus = reg?.status || null;
+    const row = {
+      profileId,
+      sessionId: live?.sessionId || reg?.sessionId || reg?.instanceId || profileId,
+      instanceId: reg?.instanceId || live?.sessionId || profileId,
+      alias: reg?.alias || null,
+      url: live?.url || reg?.url || null,
+      mode: live?.mode || reg?.mode || null,
+      ownerPid: live?.ownerPid || Number(reg?.ownerPid || reg?.pid || 0) || null,
+      headless: idle.headless,
+      idleTimeoutMs: idle.timeoutMs,
+      idleMs: idle.idleMs,
+      idle: idle.idle,
+      live: Boolean(live),
+      registered: Boolean(reg),
+      orphaned: Boolean(reg) && !live,
+      needsRecovery: Boolean(reg) && !live && registryStatus === 'active',
+      registryStatus,
+      lastSeen: reg?.lastSeen || null,
+      lastActivityAt: reg?.lastActivityAt || null,
+    };
+    rows.push(row);
+  }
+
+  return rows.sort((a, b) => String(a.profileId).localeCompare(String(b.profileId)));
+}
+
+export function resolveSessionViewByProfile(profileId, liveSessions = [], registeredSessions = listRegisteredSessions()) {
+  const id = String(profileId || '').trim();
+  if (!id) return null;
+  return buildResolvedSessionView(liveSessions, registeredSessions).find((item) => item.profileId === id) || null;
+}
+

package/src/services/browser-service/index.js

@@ -582,8 +582,14 @@ async function handleCommand(payload, manager, wsServer, options = {}) {
             const session = manager.getSession(profileId);
             if (!session)
                 throw new Error(`session for profile ${profileId} not started`);
-            const { deltaY, deltaX } = args;
-            await session.mouseWheel({ deltaY: Number(deltaY) || 0, deltaX: Number(deltaX) || 0 });
+            const { deltaY, deltaX, anchorX, anchorY } = args;
+            await session.mouseWheel({
+                deltaY: Number(deltaY) || 0,
+                deltaX: Number(deltaX) || 0,
+                ...(Number.isFinite(Number(anchorX)) && Number.isFinite(Number(anchorY))
+                    ? { anchorX: Number(anchorX), anchorY: Number(anchorY) }
+                    : {}),
+            });
             return { ok: true, body: { ok: true } };
         }
         case 'keyboard:type': {

package/src/services/browser-service/internal/BrowserSession.input.test.js

@@ -196,10 +196,38 @@ test('ensureInputReady brings page to front even when document reports focus', a
         isClosed: () => false,
     };
     const session = new BrowserSession({ profileId: `test-input-ready-${Date.now()}` });
-    await session.ensureInputReady(page);
+    await session.inputPipeline.ensureInputReady(page);
     assert.equal(page.bringToFrontCount, 1);
     assert.equal(page.waitCount, 1);
 });
+test('ensureInputReady skips bringToFront when CAMO_BRING_TO_FRONT_MODE=never', async () => {
+    const restoreSkip = setEnv('CAMO_BRING_TO_FRONT_MODE', 'never');
+    try {
+        const page = {
+            bringToFrontCount: 0,
+            waitCount: 0,
+            bringToFront: async function bringToFront() {
+                this.bringToFrontCount += 1;
+            },
+            waitForTimeout: async function waitForTimeout() {
+                this.waitCount += 1;
+            },
+            evaluate: async () => ({
+                hasFocus: false,
+                hidden: false,
+                visibilityState: 'visible',
+            }),
+            isClosed: () => false,
+        };
+        const session = new BrowserSession({ profileId: `test-input-ready-skip-${Date.now()}` });
+        await session.inputPipeline.ensureInputReady(page);
+        assert.equal(page.bringToFrontCount, 0);
+        assert.equal(page.waitCount, 1);
+    }
+    finally {
+        restoreSkip();
+    }
+});
 test('mouseWheel retries with refreshed active page after timeout', async () => {
     const restoreTimeout = setEnv('CAMO_INPUT_ACTION_TIMEOUT_MS', '80');
     const restoreAttempts = setEnv('CAMO_INPUT_ACTION_MAX_ATTEMPTS', '2');
@@ -210,17 +238,21 @@ test('mouseWheel retries with refreshed active page after timeout', async () =>
         const calls = [];
         const page1 = {
             isClosed: () => false,
+            viewportSize: () => ({ width: 1280, height: 720 }),
             bringToFront: async () => { },
             waitForTimeout: async () => { },
             mouse: {
+                move: async () => { },
                 wheel: async () => new Promise(() => { }),
             },
         };
         const page2 = {
             isClosed: () => false,
+            viewportSize: () => ({ width: 1280, height: 720 }),
             bringToFront: async () => { },
             waitForTimeout: async () => { },
             mouse: {
+                move: async () => { },
                 wheel: async () => {
                     calls.push('wheel_ok');
                 },
@@ -255,9 +287,11 @@ test('mouseWheel falls back to keyboard paging when wheel keeps timing out', asy
         const calls = [];
         const page = {
             isClosed: () => false,
+            viewportSize: () => ({ width: 1280, height: 720 }),
             bringToFront: async () => { },
             waitForTimeout: async () => { },
             mouse: {
+                move: async () => { },
                 wheel: async () => new Promise(() => { }),
             },
             keyboard: {
@@ -319,4 +353,4 @@ test('mouseWheel uses keyboard mode directly when CAMO_SCROLL_INPUT_MODE=keyboar
         restoreMode();
     }
 });
-//# sourceMappingURL=BrowserSession.input.test.js.map
+//# sourceMappingURL=BrowserSession.input.test.js.map

package/src/services/browser-service/internal/browser-session/input-ops.js

@@ -66,9 +66,11 @@ export class BrowserSessionInputOps {
         const page = await this.ensurePrimaryPage();
         await this.withInputActionLock(async () => {
             await this.runInputAction(page, 'input:ready', (activePage) => this.ensureInputReady(activePage));
-            const { deltaX = 0, deltaY } = opts;
+            const { deltaX = 0, deltaY, anchorX, anchorY } = opts;
             const normalizedDeltaX = Number(deltaX) || 0;
             const normalizedDeltaY = Number(deltaY) || 0;
+            const normalizedAnchorX = Number(anchorX);
+            const normalizedAnchorY = Number(anchorY);
             if (normalizedDeltaY === 0 && normalizedDeltaX === 0)
                 return;
             const keyboardKey = normalizedDeltaY > 0 ? 'PageDown' : 'PageUp';
@@ -88,8 +90,12 @@ export class BrowserSessionInputOps {
             try {
                 await this.runInputAction(page, 'mouse:wheel', async (activePage) => {
                     const viewport = activePage.viewportSize();
-                    const moveX = Math.max(1, Math.floor(((viewport?.width || 1280) * 0.5)));
-                    const moveY = Math.max(1, Math.floor(((viewport?.height || 720) * 0.5)));
+                    const moveX = Number.isFinite(normalizedAnchorX)
+                        ? Math.max(1, Math.min(Math.max(1, Number(viewport?.width || 1280) - 1), Math.round(normalizedAnchorX)))
+                        : Math.max(1, Math.floor(((viewport?.width || 1280) * 0.5)));
+                    const moveY = Number.isFinite(normalizedAnchorY)
+                        ? Math.max(1, Math.min(Math.max(1, Number(viewport?.height || 720) - 1), Math.round(normalizedAnchorY)))
+                        : Math.max(1, Math.floor(((viewport?.height || 720) * 0.5)));
                     await activePage.mouse.move(moveX, moveY, { steps: 1 }).catch(() => { });
                     await activePage.mouse.wheel(normalizedDeltaX, normalizedDeltaY);
                 });
@@ -124,4 +130,4 @@ export class BrowserSessionInputOps {
         });
     }
 }
-//# sourceMappingURL=input-ops.js.map
+//# sourceMappingURL=input-ops.js.map

package/src/services/browser-service/internal/browser-session/input-pipeline.js

@@ -1,4 +1,4 @@
-import { resolveInputActionMaxAttempts, resolveInputActionTimeoutMs, resolveInputRecoveryBringToFrontTimeoutMs, resolveInputRecoveryDelayMs, resolveInputReadySettleMs } from './utils.js';
+import { resolveInputActionMaxAttempts, resolveInputActionTimeoutMs, resolveInputRecoveryBringToFrontTimeoutMs, resolveInputRecoveryDelayMs, resolveInputReadySettleMs, shouldSkipBringToFront } from './utils.js';
 import { ensurePageRuntime } from '../pageRuntime.js';
 export class BrowserInputPipeline {
     ensurePrimaryPage;
@@ -11,6 +11,13 @@ export class BrowserInputPipeline {
     async ensureInputReady(page) {
         if (this.isHeadless())
             return;
+        if (shouldSkipBringToFront()) {
+            const settleMs = resolveInputReadySettleMs();
+            if (settleMs > 0) {
+                await page.waitForTimeout(settleMs).catch(() => { });
+            }
+            return;
+        }
         const bringToFrontTimeoutMs = resolveInputRecoveryBringToFrontTimeoutMs();
         let bringToFrontTimer = null;
         try {
@@ -67,6 +74,7 @@ export class BrowserInputPipeline {
     }
     async recoverInputPipeline(page) {
         const activePage = await this.resolveInputPage(page).catch(() => page);
+        if (!shouldSkipBringToFront()) {
         const bringToFrontTimeoutMs = resolveInputRecoveryBringToFrontTimeoutMs();
         let bringToFrontTimer = null;
         try {
@@ -86,6 +94,7 @@ export class BrowserInputPipeline {
             if (bringToFrontTimer)
                 clearTimeout(bringToFrontTimer);
         }
+        }
         const delayMs = resolveInputRecoveryDelayMs();
         if (delayMs > 0) {
             try {
@@ -130,4 +139,4 @@ export class BrowserInputPipeline {
         }
     }
 }
-//# sourceMappingURL=input-pipeline.js.map
+//# sourceMappingURL=input-pipeline.js.map

package/src/services/browser-service/internal/browser-session/page-management.js

@@ -1,6 +1,6 @@
 import { spawnSync } from 'node:child_process';
 import { ensurePageRuntime } from '../pageRuntime.js';
-import { resolveNavigationWaitUntil, normalizeUrl } from './utils.js';
+import { resolveNavigationWaitUntil, normalizeUrl, shouldSkipBringToFront } from './utils.js';
 export class BrowserSessionPageManagement {
     deps;
     constructor(deps) {
@@ -74,7 +74,9 @@ export class BrowserSessionPageManagement {
         const opener = this.deps.getActivePage() || ctx.pages()[0];
         if (!opener)
             throw new Error('no_opener_page');
-        await opener.bringToFront().catch(() => null);
+        if (!shouldSkipBringToFront()) {
+            await opener.bringToFront().catch(() => null);
+        }
         const before = ctx.pages().filter((p) => !p.isClosed()).length;
         for (let attempt = 1; attempt <= 3; attempt += 1) {
             const waitPage = ctx.waitForEvent('page', { timeout: 8000 }).catch(() => null);
@@ -136,11 +138,13 @@ export class BrowserSessionPageManagement {
         catch {
             /* ignore */
         }
-        try {
-            await page.bringToFront();
-        }
-        catch {
-            /* ignore */
+        if (!shouldSkipBringToFront()) {
+            try {
+                await page.bringToFront();
+            }
+            catch {
+                /* ignore */
+            }
         }
         if (url) {
             await page.goto(url, { waitUntil: resolveNavigationWaitUntil() });
@@ -165,11 +169,13 @@ export class BrowserSessionPageManagement {
         catch {
             /* ignore */
         }
-        try {
-            await page.bringToFront();
-        }
-        catch {
-            /* ignore */
+        if (!shouldSkipBringToFront()) {
+            try {
+                await page.bringToFront();
+            }
+            catch {
+                /* ignore */
+            }
         }
         await ensurePageRuntime(page, true).catch(() => { });
         this.deps.recordLastKnownUrl(page.url());
@@ -194,11 +200,13 @@ export class BrowserSessionPageManagement {
         if (nextIndex >= 0) {
             const nextPage = remaining[nextIndex];
             this.deps.setActivePage(nextPage);
-            try {
-                await nextPage.bringToFront();
-            }
-            catch {
-                /* ignore */
+            if (!shouldSkipBringToFront()) {
+                try {
+                    await nextPage.bringToFront();
+                }
+                catch {
+                    /* ignore */
+                }
             }
             await ensurePageRuntime(nextPage, true).catch(() => { });
             this.deps.recordLastKnownUrl(nextPage.url());
@@ -209,4 +217,4 @@ export class BrowserSessionPageManagement {
         return { closedIndex, activeIndex: nextIndex, total: remaining.length };
     }
 }
-//# sourceMappingURL=page-management.js.map
+//# sourceMappingURL=page-management.js.map

package/src/services/browser-service/internal/browser-session/utils.js

@@ -28,6 +28,20 @@ export function resolveInputReadySettleMs() {
     const raw = Number(process.env.CAMO_INPUT_READY_SETTLE_MS ?? 80);
     return Math.max(0, Number.isFinite(raw) ? Math.floor(raw) : 80);
 }
+export function resolveBringToFrontMode() {
+    const mode = String(process.env.CAMO_BRING_TO_FRONT_MODE ?? '').trim().toLowerCase();
+    if (mode === 'never' || mode === 'off' || mode === 'disabled')
+        return 'never';
+    if (mode === 'always' || mode === 'on' || mode === 'auto')
+        return 'auto';
+    const legacy = String(process.env.CAMO_SKIP_BRING_TO_FRONT ?? '').trim().toLowerCase();
+    if (legacy === '1' || legacy === 'true' || legacy === 'yes' || legacy === 'on')
+        return 'never';
+    return 'auto';
+}
+export function shouldSkipBringToFront() {
+    return resolveBringToFrontMode() === 'never';
+}
 export function isTimeoutLikeError(error) {
     const message = String(error?.message || error || '').toLowerCase();
     return message.includes('timed out') || message.includes('timeout');
@@ -44,6 +58,12 @@ export function normalizeUrl(raw) {
 export async function ensureInputReadyOnPage(page, headless, bringToFrontTimeoutMs, settleMs) {
     if (headless)
         return;
+    if (shouldSkipBringToFront()) {
+        if (settleMs > 0) {
+            await page.waitForTimeout(settleMs).catch(() => { });
+        }
+        return;
+    }
     let bringToFrontTimer = null;
     try {
         await Promise.race([
@@ -66,4 +86,4 @@ export async function ensureInputReadyOnPage(page, headless, bringToFrontTimeout
         await page.waitForTimeout(settleMs).catch(() => { });
     }
 }
-//# sourceMappingURL=utils.js.map
+//# sourceMappingURL=utils.js.map

package/src/utils/browser-service.mjs

@@ -7,6 +7,7 @@ import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { BROWSER_SERVICE_URL, loadConfig, setRepoRoot } from './config.mjs';
 import { touchSessionActivity } from '../lifecycle/session-registry.mjs';
+import { buildResolvedSessionView, resolveSessionViewByProfile } from '../lifecycle/session-view.mjs';
 
 const require = createRequire(import.meta.url);
 const DEFAULT_API_TIMEOUT_MS = 90000;
@@ -151,16 +152,21 @@ export async function callAPI(action, payload = {}, options = {}) {
 
 export async function getSessionByProfile(profileId) {
   const status = await callAPI('getStatus', {});
-  const activeSession = status?.sessions?.find((s) => s.profileId === profileId) || null;
-  if (activeSession) {
-    return activeSession;
-  }
   if (!profileId) {
     return null;
   }
+  const liveSessions = Array.isArray(status?.sessions) ? status.sessions : [];
+  const resolved = resolveSessionViewByProfile(profileId, liveSessions);
+  if (resolved?.live) {
+    const activeSession = liveSessions.find((session) => String(session?.profileId || '').trim() === resolved.profileId) || null;
+    if (activeSession) return activeSession;
+  }
+  if (!resolved?.live) {
+    return null;
+  }
 
-  // Some browser-service builds do not populate getStatus.sessions reliably.
-  // Fallback to page:list so runtime can still attach to an active profile tab set.
+  // Some browser-service builds do not populate current_url reliably.
+  // Fallback to page:list only to enrich an already-live profile.
   try {
     const pagePayload = await callAPI('page:list', { profileId });
     const pages = Array.isArray(pagePayload?.pages)
@@ -185,6 +191,12 @@ export async function getSessionByProfile(profileId) {
   }
 }
 
+export async function getResolvedSessions() {
+  const status = await callAPI('getStatus', {});
+  const liveSessions = Array.isArray(status?.sessions) ? status.sessions : [];
+  return buildResolvedSessionView(liveSessions);
+}
+
 function buildDomSnapshotScript(maxDepth, maxChildren) {
   return `(() => {
     const MAX_DEPTH = ${maxDepth};

package/src/utils/help.mjs

@@ -32,16 +32,16 @@ BROWSER CONTROL:
   stop --alias <alias>                      Stop by alias
   stop idle                                 Stop all idle sessions
   stop all                                  Stop all sessions
-  status [profileId]
+  status [profileId]                        Show resolved per-profile session view
   list                                      Alias of status
 
 LIFECYCLE & CLEANUP:
-  instances                                 List global camoufox instances (live + registered + idle state)
-  sessions                                  List active browser sessions
-  cleanup [profileId]                       Cleanup session (release lock + stop)
+  instances                                 List resolved session view (live + registered + idle state)
+  sessions                                  List resolved session view for all profiles
+  cleanup [profileId]                       Cleanup only one profile (remote stop + local registry/lock/watchdog)
   cleanup all                               Cleanup all active sessions
   cleanup locks                             Cleanup stale lock files
-  force-stop [profileId]                    Force stop session (for stuck sessions)
+  force-stop [profileId]                    Force stop only one profile session (no alias/id targeting)
   lock list                                 List active session locks
   lock [profileId]                          Show lock info for profile
   unlock [profileId]                        Release lock for profile
@@ -63,7 +63,7 @@ PAGES:
   new-page [profileId] [--url <url>]
   close-page [profileId] [index]
   switch-page [profileId] <index>
-  list-pages [profileId]
+  list-pages [profileId]                    List pages only when that profile is live
 
 DEVTOOLS:
   devtools logs [profileId] [--limit 120] [--since <unix_ms>] [--levels error,warn] [--clear]
@@ -180,8 +180,31 @@ ENV:
   CAMO_ROOT                                  Legacy data root (auto-appends .camo if needed)
   CAMO_WS_URL                                Optional ws://host:port override
   CAMO_WS_HOST / CAMO_WS_PORT                WS host/port for browser-service
+  CAMO_BRING_TO_FRONT_MODE                   Bring-to-front policy: auto (default) | never
+  CAMO_SKIP_BRING_TO_FRONT                   Legacy alias for CAMO_BRING_TO_FRONT_MODE=never
   CAMO_PROGRESS_EVENTS_FILE                 Optional path override for progress jsonl
   CAMO_PROGRESS_WS_HOST / CAMO_PROGRESS_WS_PORT   Progress daemon host/port (defaults: 127.0.0.1:7788)
+
+SESSION ISOLATION:
+  - profile is the lifecycle primary key. browser-service, lock, watchdog, registry all bind to the same profileId.
+  - camo start/stop/cleanup/force-stop <profileId> only targets that exact profile and must not affect other profiles.
+  - stop --id / stop --alias are convenience selectors for stop only; cleanup/force-stop never accept alias or instance id.
+  - status/sessions/instances all read the same resolved session view with these fields:
+      live: browser-service currently has this profile session
+      registered: local registry has metadata for this profile
+      orphaned: registry exists but service session is gone
+      needsRecovery: registry says active but service no longer has that profile
+  - list-pages requires live=true for that profile; otherwise camo will fail fast instead of probing other profiles.
+
+ISOLATION EXAMPLES:
+  camo sessions
+  camo status finger
+  camo stop finger
+  camo status xhs-qa-1
+  camo cleanup finger
+  camo force-stop finger
+  invalid: camo cleanup --alias shard1
+  invalid: camo force-stop --id inst_xxxxxxxx
 `);
 }