@jackwener/opencli 1.7.3 → 1.7.4

package/clis/youtube/subscriptions.js

@@ -0,0 +1,57 @@
+/**
+ * YouTube subscriptions — list of subscribed channels from /feed/channels.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { extractSubscriptionChannel } from './utils.js';
+
+cli({
+    site: 'youtube',
+    name: 'subscriptions',
+    description: 'List subscribed YouTube channels',
+    domain: 'www.youtube.com',
+    strategy: Strategy.COOKIE,
+    args: [
+        { name: 'limit', type: 'int', default: 50, help: 'Max channels to return (default 50)' },
+    ],
+    columns: ['rank', 'name', 'handle', 'subscribers', 'url'],
+    func: async (page, kwargs) => {
+        const limit = Math.min(kwargs.limit || 50, 1000);
+        await page.goto('https://www.youtube.com/feed/channels');
+        await page.wait(3);
+        const data = await page.evaluate(`
+      (async () => {
+        const d = window.ytInitialData;
+        if (!d) return { error: 'YouTube data not found — are you logged in?' };
+
+        const limit = ${limit};
+
+        const items = d.contents?.twoColumnBrowseResultsRenderer
+          ?.tabs?.[0]?.tabRenderer?.content
+          ?.sectionListRenderer?.contents?.[0]
+          ?.itemSectionRenderer?.contents?.[0]
+          ?.shelfRenderer?.content
+          ?.expandedShelfContentsRenderer?.items || [];
+
+        const extractChannel = ${extractSubscriptionChannel.toString()};
+
+        const channels = [];
+        for (const item of items) {
+          if (channels.length >= limit) break;
+          const ch = extractChannel(item.channelRenderer);
+          if (ch?.name) channels.push(ch);
+        }
+
+        return channels;
+      })()
+    `);
+        if (!Array.isArray(data)) {
+            const errMsg = data && typeof data === 'object' ? String(data.error || '') : '';
+            throw new CommandExecutionError(errMsg || 'Failed to fetch subscriptions — make sure you are logged into YouTube');
+        }
+        if (data.length === 0) {
+            throw new EmptyResultError('youtube subscriptions');
+        }
+        return data.map((ch, i) => ({ rank: i + 1, ...ch }));
+    },
+});

package/clis/youtube/unlike.js

@@ -0,0 +1,62 @@
+/**
+ * YouTube unlike — remove like from a video via InnerTube like API.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { parseVideoId, prepareYoutubeApiPage, SAPISID_HASH_FN } from './utils.js';
+import { CommandExecutionError, AuthRequiredError } from '@jackwener/opencli/errors';
+
+cli({
+    site: 'youtube',
+    name: 'unlike',
+    description: 'Remove like from a YouTube video',
+    domain: 'www.youtube.com',
+    strategy: Strategy.COOKIE,
+    args: [
+        { name: 'url', required: true, positional: true, help: 'YouTube video URL or video ID' },
+    ],
+    columns: ['status', 'message'],
+    func: async (page, kwargs) => {
+        const videoId = parseVideoId(String(kwargs.url));
+        await prepareYoutubeApiPage(page);
+        const result = await page.evaluate(`
+      (async () => {
+        ${SAPISID_HASH_FN}
+
+        const cfg = window.ytcfg?.data_ || {};
+        const apiKey = cfg.INNERTUBE_API_KEY;
+        const context = cfg.INNERTUBE_CONTEXT;
+        if (!apiKey || !context) return { error: 'config', message: 'YouTube config not found' };
+
+        const authHash = await getSapisidHash('https://www.youtube.com');
+        if (!authHash) return { error: 'auth', message: 'Not logged in (SAPISID cookie missing)' };
+
+        const resp = await fetch('/youtubei/v1/like/removelike?key=' + apiKey + '&prettyPrint=false', {
+          method: 'POST',
+          credentials: 'include',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': authHash,
+            'X-Origin': 'https://www.youtube.com',
+          },
+          body: JSON.stringify({ context, target: { videoId: ${JSON.stringify(videoId)} } }),
+        });
+
+        if (resp.status === 401 || resp.status === 403) return { error: 'auth', message: 'Not logged in' };
+        if (!resp.ok) {
+          const body = await resp.json().catch(() => ({}));
+          const errStatus = body?.error?.status || '';
+          if (errStatus === 'UNAUTHENTICATED') return { error: 'auth', message: 'Not logged in' };
+          return { error: 'http', message: 'HTTP ' + resp.status + (errStatus ? ' ' + errStatus : '') };
+        }
+        return { ok: true };
+      })()
+    `);
+        if (result?.error === 'auth') {
+            throw new AuthRequiredError('www.youtube.com');
+        }
+        if (result?.error) {
+            throw new CommandExecutionError(result.message || 'Failed to remove like');
+        }
+        return [{ status: 'success', message: 'Unliked: ' + videoId }];
+    },
+});

package/clis/youtube/unsubscribe.js

@@ -0,0 +1,71 @@
+/**
+ * YouTube unsubscribe — unsubscribe from a channel via InnerTube subscription API.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { prepareYoutubeApiPage, SAPISID_HASH_FN, RESOLVE_CHANNEL_HANDLE_FN } from './utils.js';
+import { CommandExecutionError, AuthRequiredError } from '@jackwener/opencli/errors';
+
+cli({
+    site: 'youtube',
+    name: 'unsubscribe',
+    description: 'Unsubscribe from a YouTube channel',
+    domain: 'www.youtube.com',
+    strategy: Strategy.COOKIE,
+    args: [
+        { name: 'channel', required: true, positional: true, help: 'Channel ID (UCxxxx) or handle (@name)' },
+    ],
+    columns: ['status', 'message'],
+    func: async (page, kwargs) => {
+        const channelInput = String(kwargs.channel);
+        await prepareYoutubeApiPage(page);
+        const result = await page.evaluate(`
+      (async () => {
+        ${SAPISID_HASH_FN}
+
+        const cfg = window.ytcfg?.data_ || {};
+        const apiKey = cfg.INNERTUBE_API_KEY;
+        const context = cfg.INNERTUBE_CONTEXT;
+        if (!apiKey || !context) return { error: 'config', message: 'YouTube config not found' };
+
+        const authHash = await getSapisidHash('https://www.youtube.com');
+        if (!authHash) return { error: 'auth', message: 'Not logged in (SAPISID cookie missing)' };
+
+        ${RESOLVE_CHANNEL_HANDLE_FN}
+
+        let channelId = ${JSON.stringify(channelInput)};
+        channelId = await resolveChannelHandle(channelId, apiKey, context);
+
+        if (!channelId.startsWith('UC')) {
+          return { error: 'arg', message: 'Could not resolve channel ID from: ' + ${JSON.stringify(channelInput)} };
+        }
+
+        const resp = await fetch('/youtubei/v1/subscription/unsubscribe?key=' + apiKey + '&prettyPrint=false', {
+          method: 'POST',
+          credentials: 'include',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': authHash,
+            'X-Origin': 'https://www.youtube.com',
+          },
+          body: JSON.stringify({ context, channelIds: [channelId] }),
+        });
+
+        if (resp.status === 401 || resp.status === 403) return { error: 'auth', message: 'Not logged in' };
+        if (!resp.ok) {
+          const body = await resp.json().catch(() => ({}));
+          const errStatus = body?.error?.status || '';
+          if (errStatus === 'UNAUTHENTICATED') return { error: 'auth', message: 'Not logged in' };
+          return { error: 'http', message: 'HTTP ' + resp.status + (errStatus ? ' ' + errStatus : '') };
+        }
+        return { ok: true, channelId };
+      })()
+    `);
+        if (result?.error === 'auth') {
+            throw new AuthRequiredError('www.youtube.com');
+        }
+        if (result?.error) {
+            throw new CommandExecutionError(result.message || 'Failed to unsubscribe');
+        }
+        return [{ status: 'success', message: 'Unsubscribed from: ' + (result.channelId || channelInput) }];
+    },
+});

package/clis/youtube/utils.js

@@ -90,3 +90,125 @@ export async function prepareYoutubeApiPage(page) {
     await page.goto('https://www.youtube.com', { waitUntil: 'none' });
     await page.wait(2);
 }
+/**
+ * Inline InnerTube browse API helper for use inside page.evaluate() strings.
+ * Inject via FETCH_BROWSE_FN, then call: fetchBrowse(apiKey, body)
+ */
+export const FETCH_BROWSE_FN = `
+async function fetchBrowse(apiKey, body) {
+  const resp = await fetch('/youtubei/v1/browse?key=' + apiKey + '&prettyPrint=false', {
+    method: 'POST',
+    credentials: 'include',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  if (!resp.ok) return { error: 'InnerTube browse API returned HTTP ' + resp.status };
+  return resp.json();
+}
+`;
+/**
+ * Extract video objects from playlistVideoRenderer items (playlists, watch-later).
+ * Pure function — inject into page.evaluate() via: extractPlaylistVideos.toString()
+ */
+export function extractPlaylistVideos(items) {
+    return items
+        .filter(i => i.playlistVideoRenderer)
+        .map(i => {
+        const v = i.playlistVideoRenderer;
+        const infoRuns = v.videoInfo?.runs || [];
+        return {
+            rank: parseInt(v.index?.simpleText || '0', 10),
+            title: v.title?.runs?.[0]?.text || '',
+            channel: v.shortBylineText?.runs?.[0]?.text || '',
+            duration: v.lengthText?.simpleText || '',
+            views: infoRuns[0]?.text || '',
+            published: infoRuns[2]?.text || '',
+            url: 'https://www.youtube.com/watch?v=' + v.videoId,
+        };
+    });
+}
+/**
+ * Normalize a subscribed channel entry from YouTube's channelRenderer payload.
+ * Different surfaces/locales may expose the handle in channelHandleText, canonicalBaseUrl,
+ * or, in some variants, overload one of the count fields with an @handle string.
+ */
+export function extractSubscriptionChannel(channelRenderer) {
+    const readText = (value) => {
+        if (!value)
+            return '';
+        if (typeof value.simpleText === 'string')
+            return value.simpleText.trim();
+        if (Array.isArray(value.runs)) {
+            return value.runs
+                .map((run) => run?.text || '')
+                .join('')
+                .trim();
+        }
+        return '';
+    };
+    const ch = channelRenderer || {};
+    const name = readText(ch.title);
+    const baseUrl = ch.navigationEndpoint?.browseEndpoint?.canonicalBaseUrl || '';
+    const channelId = ch.channelId || ch.navigationEndpoint?.browseEndpoint?.browseId || '';
+    const subscriberCountText = readText(ch.subscriberCountText);
+    const videoCountText = readText(ch.videoCountText);
+    const handle = [
+        readText(ch.channelHandleText),
+        baseUrl.startsWith('/@') ? baseUrl.slice(1) : '',
+        subscriberCountText.startsWith('@') ? subscriberCountText : '',
+        videoCountText.startsWith('@') ? videoCountText : '',
+    ].find(Boolean) || '';
+    const subscribers = [
+        !subscriberCountText.startsWith('@') ? subscriberCountText : '',
+        !videoCountText.startsWith('@') ? videoCountText : '',
+    ].find(Boolean) || '';
+    const url = baseUrl
+        ? 'https://www.youtube.com' + baseUrl
+        : channelId ? 'https://www.youtube.com/channel/' + channelId : '';
+    return { name, handle, subscribers, url };
+}
+/**
+ * Inline @handle → channelId resolver for use inside page.evaluate() strings.
+ * Inject via RESOLVE_CHANNEL_HANDLE_FN, then call: resolveChannelHandle(input, apiKey, context)
+ */
+export const RESOLVE_CHANNEL_HANDLE_FN = `
+async function resolveChannelHandle(input, apiKey, context) {
+  if (!input.startsWith('@')) return input;
+  const resp = await fetch('/youtubei/v1/navigation/resolve_url?key=' + apiKey + '&prettyPrint=false', {
+    method: 'POST',
+    credentials: 'include',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ context, url: 'https://www.youtube.com/' + input }),
+  });
+  if (!resp.ok) return input;
+  const data = await resp.json().catch(() => ({}));
+  return data.endpoint?.browseEndpoint?.browseId || input;
+}
+`;
+/**
+ * Inline SAPISIDHASH helper for use inside page.evaluate() strings.
+ * YouTube write APIs (like, subscribe) require:
+ *   Authorization: SAPISIDHASH {time}_{SHA1(time + " " + SAPISID + " " + origin)}
+ */
+export const SAPISID_HASH_FN = `
+async function getSapisidHash(origin) {
+  const cookies = document.cookie.split('; ');
+  let sapisid = '';
+  for (const c of cookies) {
+    const eq = c.indexOf('=');
+    if (eq === -1) continue;
+    const name = c.slice(0, eq);
+    const val = c.slice(eq + 1);
+    if (name === '__Secure-3PAPISID' || name === 'SAPISID') {
+      sapisid = val;
+      if (name === '__Secure-3PAPISID') break;
+    }
+  }
+  if (!sapisid) return null;
+  const time = Math.floor(Date.now() / 1000);
+  const msgBuffer = new TextEncoder().encode(time + ' ' + sapisid + ' ' + origin);
+  const hashBuffer = await crypto.subtle.digest('SHA-1', msgBuffer);
+  const hashHex = Array.from(new Uint8Array(hashBuffer)).map(b => b.toString(16).padStart(2, '0')).join('');
+  return 'SAPISIDHASH ' + time + '_' + hashHex;
+}
+`;

package/clis/youtube/utils.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { extractJsonAssignmentFromHtml, prepareYoutubeApiPage } from './utils.js';
+import { extractJsonAssignmentFromHtml, extractSubscriptionChannel, prepareYoutubeApiPage } from './utils.js';
 describe('youtube utils', () => {
     it('extractJsonAssignmentFromHtml parses bootstrap objects with nested braces in strings', () => {
         const html = `
@@ -34,4 +34,35 @@ describe('youtube utils', () => {
         expect(page.goto).toHaveBeenCalledWith('https://www.youtube.com', { waitUntil: 'none' });
         expect(page.wait).toHaveBeenCalledWith(2);
     });
+    it('extractSubscriptionChannel prefers explicit handle and subscriber count fields', () => {
+        expect(extractSubscriptionChannel({
+            title: { simpleText: 'OpenAI' },
+            channelHandleText: { runs: [{ text: '@openai' }] },
+            subscriberCountText: { simpleText: '1.23M subscribers' },
+            videoCountText: { simpleText: '123 videos' },
+            navigationEndpoint: { browseEndpoint: { canonicalBaseUrl: '/channel/UC123' } },
+            channelId: 'UC123',
+        })).toEqual({
+            name: 'OpenAI',
+            handle: '@openai',
+            subscribers: '1.23M subscribers',
+            url: 'https://www.youtube.com/channel/UC123',
+        });
+    });
+    it('extractSubscriptionChannel falls back when handle/count fields are overloaded', () => {
+        expect(extractSubscriptionChannel({
+            title: {
+                runs: [{ text: 'OpenAI' }],
+            },
+            subscriberCountText: { simpleText: '@openai' },
+            videoCountText: { simpleText: '1.23M subscribers' },
+            navigationEndpoint: { browseEndpoint: { canonicalBaseUrl: '/@openai' } },
+            channelId: 'UC123',
+        })).toEqual({
+            name: 'OpenAI',
+            handle: '@openai',
+            subscribers: '1.23M subscribers',
+            url: 'https://www.youtube.com/@openai',
+        });
+    });
 });

package/clis/youtube/watch-later.js

@@ -0,0 +1,76 @@
+/**
+ * YouTube watch-later — the user's Watch Later queue.
+ * Navigates to /playlist?list=WL and reads ytInitialData directly.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { FETCH_BROWSE_FN, extractPlaylistVideos } from './utils.js';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+cli({
+    site: 'youtube',
+    name: 'watch-later',
+    description: 'Get your YouTube Watch Later queue',
+    domain: 'www.youtube.com',
+    strategy: Strategy.COOKIE,
+    args: [
+        { name: 'limit', type: 'int', default: 50, help: 'Max videos to return (default 50, max 200)' },
+    ],
+    columns: ['rank', 'title', 'channel', 'duration', 'views', 'published', 'url'],
+    func: async (page, kwargs) => {
+        const limit = Math.min(kwargs.limit || 50, 200);
+        await page.goto('https://www.youtube.com/playlist?list=WL');
+        await page.wait(3);
+        const data = await page.evaluate(`
+      (async () => {
+        const d = window.ytInitialData;
+        if (!d) return { error: 'YouTube data not found — are you logged in?' };
+
+        const limit = ${limit};
+        const cfg = window.ytcfg?.data_ || {};
+        const apiKey = cfg.INNERTUBE_API_KEY;
+        const context = cfg.INNERTUBE_CONTEXT;
+
+        const header = d.header?.playlistHeaderRenderer;
+        const title = header?.title?.simpleText || 'Watch Later';
+        const stats = (header?.stats || [])
+          .map(s => s.runs?.map(r => r.text)?.join('') || s.simpleText || '')
+          .filter(Boolean);
+
+        const tabs = d.contents?.twoColumnBrowseResultsRenderer?.tabs || [];
+        let listContents = tabs[0]?.tabRenderer?.content?.sectionListRenderer?.contents?.[0]?.itemSectionRenderer?.contents?.[0]?.playlistVideoListRenderer?.contents || [];
+
+        ${FETCH_BROWSE_FN}
+
+        const extractVideos = ${extractPlaylistVideos.toString()};
+
+        let videos = extractVideos(listContents);
+
+        let contItem = listContents[listContents.length - 1];
+        while (videos.length < limit && contItem?.continuationItemRenderer && apiKey && context) {
+          const token = contItem.continuationItemRenderer?.continuationEndpoint?.continuationCommand?.token;
+          if (!token) break;
+          const contData = await fetchBrowse(apiKey, { context, continuation: token });
+          if (contData.error) break;
+          const newItems = contData.onResponseReceivedActions?.[0]?.appendContinuationItemsAction?.continuationItems || [];
+          if (!newItems.length) break;
+          videos = videos.concat(extractVideos(newItems));
+          contItem = newItems[newItems.length - 1];
+        }
+
+        return { title, stats, videos: videos.slice(0, limit) };
+      })()
+    `);
+        if (!data || typeof data !== 'object') {
+            throw new CommandExecutionError('Failed to fetch Watch Later — make sure you are logged into YouTube');
+        }
+        if (data.error) {
+            throw new CommandExecutionError(String(data.error));
+        }
+        if (!data.videos?.length) {
+            throw new EmptyResultError('youtube watch-later');
+        }
+        const statsStr = (data.stats || []).join(' | ');
+        process.stderr.write(`${data.title}  ${statsStr}\n`);
+        return data.videos;
+    },
+});

package/dist/src/browser/base-page.js

@@ -8,8 +8,10 @@
  * Subclasses implement the transport-specific methods: goto, evaluate,
  * getCookies, screenshot, tabs, etc.
  */
-import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
-import { clickJs, typeTextJs, pressKeyJs, waitForTextJs, waitForCaptureJs, waitForSelectorJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, } from './dom-helpers.js';
+import { generateSnapshotJs, getFormStateJs } from './dom-snapshot.js';
+import { pressKeyJs, waitForTextJs, waitForCaptureJs, waitForSelectorJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, } from './dom-helpers.js';
+import { resolveTargetJs, clickResolvedJs, typeResolvedJs, scrollResolvedJs } from './target-resolver.js';
+import { TargetError } from './target-errors.js';
 import { formatSnapshot } from '../snapshotFormatter.js';
 export class BasePage {
     _lastUrl = null;
@@ -36,7 +38,13 @@ export class BasePage {
     }
     // ── Shared DOM helper implementations ──
     async click(ref) {
-        const result = await this.evaluate(clickJs(ref));
+        // Phase 1: Resolve target with fingerprint verification
+        const resolution = await this.evaluate(resolveTargetJs(ref));
+        if (!resolution.ok) {
+            throw new TargetError(resolution);
+        }
+        // Phase 2: Execute click on resolved element
+        const result = await this.evaluate(clickResolvedJs());
         // Backwards compat: old format returned 'clicked' string
         if (typeof result === 'string' || result == null)
             return;
@@ -56,13 +64,25 @@ export class BasePage {
         return false;
     }
     async typeText(ref, text) {
-        await this.evaluate(typeTextJs(ref, text));
+        // Phase 1: Resolve target with fingerprint verification
+        const resolution = await this.evaluate(resolveTargetJs(ref));
+        if (!resolution.ok) {
+            throw new TargetError(resolution);
+        }
+        // Phase 2: Execute type on resolved element
+        await this.evaluate(typeResolvedJs(text));
     }
     async pressKey(key) {
         await this.evaluate(pressKeyJs(key));
     }
     async scrollTo(ref) {
-        return this.evaluate(scrollToRefJs(ref));
+        // Phase 1: Resolve target with fingerprint verification
+        const resolution = await this.evaluate(resolveTargetJs(ref));
+        if (!resolution.ok) {
+            throw new TargetError(resolution);
+        }
+        // Phase 2: Scroll to resolved element
+        return this.evaluate(scrollResolvedJs());
     }
     async getFormState() {
         return (await this.evaluate(getFormStateJs()));

package/dist/src/browser/bridge.d.ts

@@ -18,6 +18,8 @@ export declare class BrowserBridge implements IBrowserFactory {
     }): Promise<IPage>;
     close(): Promise<void>;
     private _ensureDaemon;
+    /** Poll until daemon is fully stopped (port released). */
+    private _waitForDaemonStop;
     /** Poll getDaemonHealth() until state is 'ready' or deadline is reached. */
     private _pollUntilReady;
 }

package/dist/src/browser/bridge.js

@@ -6,9 +6,10 @@ import { fileURLToPath } from 'node:url';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { Page } from './page.js';
-import { getDaemonHealth } from './daemon-client.js';
+import { getDaemonHealth, requestDaemonShutdown } from './daemon-client.js';
 import { DEFAULT_DAEMON_PORT } from '../constants.js';
 import { BrowserConnectError } from '../errors.js';
+import { PKG_VERSION } from '../version.js';
 const DAEMON_SPAWN_TIMEOUT = 10000; // 10s to wait for daemon + extension
 /**
  * Browser factory: manages daemon lifecycle and provides IPage instances.
@@ -57,18 +58,42 @@ export class BrowserBridge {
         // Fast path: everything ready
         if (health.state === 'ready')
             return;
-        // Daemon running but no extension — wait for extension with progress
+        // Daemon running but no extension
         if (health.state === 'no-extension') {
-            if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
-                process.stderr.write('⏳ Waiting for Chrome/Chromium extension to connect...\n');
-                process.stderr.write('   Make sure Chrome or Chromium is open and the OpenCLI extension is enabled.\n');
+            // Detect stale daemon: version mismatch OR missing daemonVersion (pre-version daemon)
+            const daemonVersion = health.status?.daemonVersion;
+            const isStale = !daemonVersion || daemonVersion !== PKG_VERSION;
+            if (isStale) {
+                // Stale daemon — restart it so extension gets a fresh WebSocket endpoint
+                const reason = daemonVersion
+                    ? `v${daemonVersion} ≠ v${PKG_VERSION}`
+                    : `pre-version daemon, CLI is v${PKG_VERSION}`;
+                if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
+                    process.stderr.write(`⚠️  Stale daemon detected (${reason}). Restarting...\n`);
+                }
+                const shutdownAccepted = await requestDaemonShutdown();
+                const portReleased = shutdownAccepted && await this._waitForDaemonStop(3000);
+                if (!portReleased) {
+                    // Stale daemon replacement failed — don't blindly spawn on an occupied port
+                    throw new BrowserConnectError('Stale daemon could not be replaced', `A stale daemon (${reason}) is running but did not shut down.\n` +
+                        '  Run manually: opencli daemon stop && opencli doctor', 'daemon-not-running');
+                }
+                // Port released — fall through to spawn a fresh daemon
+            }
+            else {
+                // Same version — wait for extension to connect
+                if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
+                    process.stderr.write('⏳ Waiting for Chrome/Chromium extension to connect...\n');
+                    process.stderr.write('   Make sure Chrome or Chromium is open and the OpenCLI extension is enabled.\n');
+                }
+                if (await this._pollUntilReady(timeoutMs))
+                    return;
+                throw new BrowserConnectError('Browser Bridge extension not connected', 'Make sure Chrome/Chromium is open and the extension is enabled.\n' +
+                    'If the extension is installed, try: opencli daemon stop && opencli doctor\n' +
+                    'If not installed:\n' +
+                    '  1. Download: https://github.com/jackwener/opencli/releases\n' +
+                    '  2. Open chrome://extensions → Developer Mode → Load unpacked', 'extension-not-connected');
             }
-            if (await this._pollUntilReady(timeoutMs))
-                return;
-            throw new BrowserConnectError('Browser Bridge extension not connected', 'Install the Browser Bridge:\n' +
-                '  1. Download: https://github.com/jackwener/opencli/releases\n' +
-                '  2. In Chrome or Chromium, open chrome://extensions → Developer Mode → Load unpacked\n' +
-                '  Then run: opencli doctor', 'extension-not-connected');
         }
         // No daemon — spawn one
         const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -94,13 +119,25 @@ export class BrowserBridge {
             return;
         const finalHealth = await getDaemonHealth();
         if (finalHealth.state === 'no-extension') {
-            throw new BrowserConnectError('Browser Bridge extension not connected', 'Install the Browser Bridge:\n' +
+            throw new BrowserConnectError('Browser Bridge extension not connected', 'Make sure Chrome/Chromium is open and the extension is enabled.\n' +
+                'If the extension is installed, try: opencli daemon stop && opencli doctor\n' +
+                'If not installed:\n' +
                 '  1. Download: https://github.com/jackwener/opencli/releases\n' +
-                '  2. In Chrome or Chromium, open chrome://extensions → Developer Mode → Load unpacked\n' +
-                '  Then run: opencli doctor', 'extension-not-connected');
+                '  2. Open chrome://extensions → Developer Mode → Load unpacked', 'extension-not-connected');
         }
         throw new BrowserConnectError('Failed to start opencli daemon', `Try running manually:\n  node ${daemonPath}\nMake sure port ${DEFAULT_DAEMON_PORT} is available.`, 'daemon-not-running');
     }
+    /** Poll until daemon is fully stopped (port released). */
+    async _waitForDaemonStop(timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            await new Promise(resolve => setTimeout(resolve, 200));
+            const h = await getDaemonHealth();
+            if (h.state === 'stopped')
+                return true;
+        }
+        return false;
+    }
     /** Poll getDaemonHealth() until state is 'ready' or deadline is reached. */
     async _pollUntilReady(timeoutMs) {
         const deadline = Date.now() + timeoutMs;

package/dist/src/browser/cdp.js

@@ -255,6 +255,7 @@ class CDPPage extends BasePage {
             });
             this._networkCapturing = true;
         }
+        return true;
     }
     async readNetworkCapture() {
         // Await all in-flight body fetches so entries have responsePreview populated

package/dist/src/browser/daemon-client.d.ts

@@ -47,6 +47,7 @@ export interface DaemonStatus {
     ok: boolean;
     pid: number;
     uptime: number;
+    daemonVersion?: string;
     extensionConnected: boolean;
     extensionVersion?: string;
     extensionCompatRange?: string;

package/dist/src/browser/dom-snapshot.js

@@ -575,6 +575,7 @@ export function generateSnapshotJs(opts = {}) {
   const lines = [];
   const hiddenInteractives = [];
   const currentHashes = [];
+  const refIdentity = {};
   let iframeCount = 0;
 
   function walk(el, depth, parentPropagatingRect) {
@@ -709,11 +710,20 @@ export function generateSnapshotJs(opts = {}) {
     // Scroll marker
     if (isScrollable && !interactive) line += '|scroll|';
 
-    // Interactive index + data-ref
+    // Interactive index + data-ref + fingerprint
     if (interactive) {
       interactiveIndex++;
       if (ANNOTATE_REFS) el.setAttribute('data-opencli-ref', '' + interactiveIndex);
       line += isScrollable ? '|scroll[' + interactiveIndex + ']|' : '[' + interactiveIndex + ']';
+      // Store fingerprint for stale-ref detection
+      refIdentity['' + interactiveIndex] = {
+        tag: tag,
+        role: el.getAttribute('role') || '',
+        text: (el.textContent || '').trim().slice(0, 30),
+        ariaLabel: el.getAttribute('aria-label') || '',
+        id: el.id || '',
+        testId: el.getAttribute('data-testid') || el.getAttribute('data-test') || '',
+      };
     }
 
     // Tag + attributes
@@ -797,6 +807,8 @@ export function generateSnapshotJs(opts = {}) {
 
   // Store hashes on window for next diff snapshot
   try { window.__opencli_prev_hashes = JSON.stringify(currentHashes); } catch {}
+  // Store ref identity map for stale-ref detection by target resolver
+  try { window.__opencli_ref_identity = refIdentity; } catch {}
 
   return lines.join('\\n');
 })()