opendevbrowser 0.0.28 → 0.0.30

package/extension/dist/ops/ops-runtime.js

@@ -13,7 +13,10 @@ const MAX_NETWORK_EVENTS = 300;
 const SESSION_TTL_MS = 20_000;
 const SCREENSHOT_TIMEOUT_MS = 8000;
 const TAB_CLOSE_TIMEOUT_MS = 5000;
+const OPS_SESSION_DETACH_TIMEOUT_MS = 3000;
 const POPUP_ATTACH_RETRY_DELAY_MS = 100;
+const ROOT_DETACH_VERIFY_DELAY_MS = 250;
+const ROOT_DETACH_VERIFY_ATTEMPTS = 4;
 const STALE_REF_ERROR_SUFFIX = "Take a new snapshot first.";
 const DOM_OUTER_HTML_DECLARATION = `
   function() {
@@ -305,6 +308,12 @@ export class OpsRuntime {
             });
         }
     }
+    handleRelayDisconnected() {
+        this.cdp.markClientClosed();
+        for (const session of this.sessions.list()) {
+            void this.cleanupSession(session, "ops_session_expired");
+        }
+    }
     handleHello(message) {
         if (message.version !== OPS_PROTOCOL_VERSION) {
             const error = {
@@ -2576,10 +2585,19 @@ export class OpsRuntime {
             await this.cdp.setDiscoverTargetsEnabled?.(true);
         }
         catch (error) {
+            if (isAttachBlockedError(error)) {
+                return;
+            }
             logError("ops.discover_targets", error, {
                 code: "discover_targets_enable_failed",
                 extra: baseDetails
             });
+            if (baseDetails.strict) {
+                throw this.decorateCdpFailure(error, {
+                    ...baseDetails,
+                    enablementStage: "set_discover_targets"
+                });
+            }
         }
     }
     async enableTargetDomainsOnDebuggee(debuggee, baseDetails) {
@@ -4006,7 +4024,7 @@ export class OpsRuntime {
         }
         throw new Error("Wait for selector timed out");
     }
-    cleanupSession(session, event) {
+    async cleanupSession(session, event) {
         this.clearClosingTimer(session.id);
         const waiters = this.parallelWaiters.get(session.id);
         if (waiters) {
@@ -4020,8 +4038,25 @@ export class OpsRuntime {
             this.parallelWaiters.delete(session.id);
         }
         this.sessions.delete(session.id);
-        for (const target of session.targets.values()) {
-            void this.cdp.detachTab(target.tabId).catch(() => undefined);
+        const targets = Array.from(session.targets.values());
+        try {
+            const results = await withTimeout(Promise.allSettled(targets.map(async (target) => this.cdp.detachTab(target.tabId))), OPS_SESSION_DETACH_TIMEOUT_MS, "Ops session detach timed out");
+            const failedTabIds = results.flatMap((result, index) => {
+                const target = targets[index];
+                return result.status === "rejected" && target ? [target.tabId] : [];
+            });
+            if (failedTabIds.length > 0) {
+                logError("ops.session_detach", new Error("One or more ops session targets failed to detach"), {
+                    code: "session_detach_failed",
+                    extra: { sessionId: session.id, event, failedTabIds }
+                });
+            }
+        }
+        catch (error) {
+            logError("ops.session_detach", error, {
+                code: "session_detach_failed",
+                extra: { sessionId: session.id, event }
+            });
         }
         this.emitSessionEvent(session, event);
     }
@@ -4036,7 +4071,7 @@ export class OpsRuntime {
         if (!removedTarget)
             return;
         if (targetId === session.targetId || session.targets.size === 0) {
-            this.cleanupSession(session, event);
+            void this.cleanupSession(session, event);
         }
     }
     async handleDebuggerDetachForTab(tabId) {
@@ -4044,7 +4079,8 @@ export class OpsRuntime {
         if (!session)
             return;
         if (tabId === session.tabId) {
-            // Root tab detach can be transient during child-target shutdown; tab removal handler owns root teardown.
+            // Root tab detach can be transient during child-target shutdown, but it must not retain ownership forever.
+            this.scheduleRootDebuggerDetachVerification(session.id, tabId);
             return;
         }
         const targetId = this.sessions.getTargetIdByTabId(session.id, tabId);
@@ -4064,6 +4100,48 @@ export class OpsRuntime {
         }
         this.handleClosedTarget(tabId, "ops_session_closed");
     }
+    scheduleRootDebuggerDetachVerification(sessionId, tabId) {
+        if (typeof this.cdp.getTabDebuggee !== "function") {
+            return;
+        }
+        setTimeout(() => {
+            void this.verifyRootDebuggerDetach(sessionId, tabId, ROOT_DETACH_VERIFY_ATTEMPTS);
+        }, ROOT_DETACH_VERIFY_DELAY_MS);
+    }
+    async verifyRootDebuggerDetach(sessionId, tabId, attemptsRemaining) {
+        const session = this.sessions.get(sessionId);
+        if (!session || session.tabId !== tabId) {
+            return;
+        }
+        if (this.isConcreteDebuggee(this.cdp.getTabDebuggee?.(tabId))) {
+            return;
+        }
+        let liveTab = null;
+        try {
+            liveTab = await this.tabs.getTab(tabId);
+        }
+        catch {
+            liveTab = null;
+        }
+        const current = this.sessions.get(sessionId);
+        if (!current || current.tabId !== tabId) {
+            return;
+        }
+        if (!liveTab) {
+            void this.cleanupSession(current, "ops_session_closed");
+            return;
+        }
+        if (this.isConcreteDebuggee(this.cdp.getTabDebuggee?.(tabId))) {
+            return;
+        }
+        if (attemptsRemaining > 1) {
+            setTimeout(() => {
+                void this.verifyRootDebuggerDetach(sessionId, tabId, attemptsRemaining - 1);
+            }, ROOT_DETACH_VERIFY_DELAY_MS);
+            return;
+        }
+        void this.cleanupSession(current, "ops_session_closed");
+    }
     async closeTabBestEffort(tabId) {
         try {
             await withTimeout(this.tabs.closeTab(tabId), TAB_CLOSE_TIMEOUT_MS, "Ops tab close timed out");
@@ -4081,7 +4159,7 @@ export class OpsRuntime {
             if (!session) {
                 return;
             }
-            this.cleanupSession(session, event);
+            void this.cleanupSession(session, event);
         }, 0);
     }
     sendResponse(message, payload) {
@@ -4159,7 +4237,7 @@ export class OpsRuntime {
             this.closingTimers.delete(session.id);
             const current = this.sessions.get(session.id);
             if (current && current.state === "closing") {
-                this.cleanupSession(current, "ops_session_expired");
+                void this.cleanupSession(current, "ops_session_expired");
             }
         }, SESSION_TTL_MS);
         this.closingTimers.set(session.id, timeoutId);

package/extension/dist/ops/ops-session-store.js

@@ -75,6 +75,9 @@ export class OpsSessionStore {
     listOwnedBy(clientId) {
         return this.coordinator.listOwnedBy(clientId);
     }
+    list() {
+        return this.coordinator.list();
+    }
     delete(sessionId) {
         return this.coordinator.delete(sessionId);
     }

package/extension/dist/ops/target-session-coordinator.js

@@ -44,6 +44,9 @@ export class TargetSessionCoordinator {
     listOwnedBy(clientId) {
         return Array.from(this.sessions.values()).filter((session) => session.ownerClientId === clientId);
     }
+    list() {
+        return Array.from(this.sessions.values());
+    }
     delete(sessionId) {
         const session = this.sessions.get(sessionId) ?? null;
         if (!session) {

package/extension/dist/services/CDPRouter.js

@@ -912,6 +912,9 @@ export class CDPRouter {
                 return;
             }
             catch (error) {
+                if (this.isExpectedDebuggerCleanupError(error)) {
+                    continue;
+                }
                 logError("cdp.restore_root_attach", error, {
                     code: "restore_root_attach_failed",
                     extra: { tabId }
@@ -2021,6 +2024,9 @@ export class CDPRouter {
         const message = error instanceof Error ? error.message : String(error);
         return STALE_TAB_ERROR_MARKERS.some((marker) => message.includes(marker));
     }
+    isExpectedDebuggerCleanupError(error) {
+        return this.isStaleTabError(error);
+    }
     markExpectedRootDetach(tabId) {
         this.expectedRootDetachDeadlines.set(tabId, Date.now() + 1000);
     }
@@ -2074,6 +2080,9 @@ export class CDPRouter {
             });
         }
         catch (error) {
+            if (this.isExpectedDebuggerCleanupError(error)) {
+                return;
+            }
             logError("cdp.safe_detach", error, { code: "detach_failed" });
         }
     }

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "OpenDevBrowser Relay",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "description": "Optional bridge to reuse existing Chrome tabs with OpenDevBrowser.",
   "permissions": [
     "debugger",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opendevbrowser",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "description": "Browser automation runtime with snapshot-refs-actions, browser replay screencasts, public read-only desktop observation, and browser-scoped computer-use orchestration",
   "type": "module",
   "main": "dist/index.js",

package/skills/opendevbrowser-best-practices/SKILL.md

@@ -100,7 +100,7 @@ Load this section directly with:
 opendevbrowser_skill_load opendevbrowser-best-practices "validated capability lanes"
 ```
 
-Current reliable lanes:
+Current validated lanes:
 
 1. Public-first YouTube transcript retrieval.
 
@@ -113,16 +113,18 @@ Rules:
 - browser-assisted transcript fallback is opt-in only
 - if browser fallback is enabled, use an isolated automation profile instead of a daily logged-in Google profile
 
-2. Generic topical research without shopping contamination.
+2. Evidence-gated research primitive with explicit public source families.
 
 ```bash
-npx opendevbrowser research run --topic "Chrome extension debugging workflows" --days 30 --source-selection auto --browser-mode managed --mode json --output-format json
+npx opendevbrowser research run --topic "Chrome extension debugging workflows" --days 30 --sources web,community --browser-mode managed --mode json --output-format json
 ```
 
 Rules:
-- use `--source-selection auto` for general research
-- use `--source-selection shopping` or explicit `--sources ...shopping...` only when the task is deliberately commercial
-- in the current contract, `auto` and `all` both resolve to `web`, `community`, and `social`
+- load `opendevbrowser-research` before research tasks so planning, evidence review, confidence, and limitations stay skill-guided
+- treat `research run` as provider-constrained and low-level; inspect `summary.md`, `report.md`, `records.json`, `context.json`, `meta.json`, and `bundle-manifest.json` before publishing claims
+- use `--source-selection` only to explain selector semantics; use explicit `--sources web,community` for public topical examples
+- add shopping only with `--source-selection shopping` or explicit `--sources ...shopping...` when the task is deliberately commercial
+- in the current contract, `auto` and `all` both resolve to `web`, `community`, and `social`, but neither value guarantees reliability
 
 3. Deterministic shopping reruns with explicit providers.
 

package/skills/opendevbrowser-best-practices/artifacts/skill-runtime-surface-matrix.md

@@ -13,7 +13,7 @@ Canonical inventory of repo-local OpenDevBrowser skill packs and the audit evide
 | `opendevbrowser-form-testing` | `workflow` | `./skills/opendevbrowser-form-testing/scripts/validate-skill-assets.sh` | snapshot -> type/click -> validation loop, multi-step forms, challenge checkpoints, network correlation | `node scripts/cli-smoke-test.mjs` plus `node scripts/login-fixture-live-probe.mjs` for invalid-submit, MFA, and persistence branches | extension unavailable at start if extension mode is audited separately |
 | `opendevbrowser-login-automation` | `workflow` | `./skills/opendevbrowser-login-automation/scripts/validate-skill-assets.sh` | login branching, invalid credential handling, MFA step-up, session validation | `node scripts/login-fixture-live-probe.mjs` | none; proof lane is repo-local |
 | `opendevbrowser-product-presentation-asset` | `workflow` | `./skills/opendevbrowser-product-presentation-asset/scripts/validate-skill-assets.sh` | `product-video run`, asset-pack assembly, screenshots, evidence mapping | `node scripts/product-video-fixture-live-probe.mjs` | none; proof lane is repo-local |
-| `opendevbrowser-research` | `workflow` | `./skills/opendevbrowser-research/scripts/validate-skill-assets.sh` | `research run`, timebox resolution, multi-source artifact generation | `opendevbrowser research run --topic "<topic>" --source-selection auto --mode json` via `scripts/skill-runtime-audit.mjs` | auth walls, rate limits, upstream source failure |
+| `opendevbrowser-research` | `workflow` | `./skills/opendevbrowser-research/scripts/validate-skill-assets.sh` | `research run`, timebox resolution, multi-source artifact generation | `opendevbrowser research run --topic "<topic>" --sources web,community --mode json` via `scripts/skill-runtime-audit.mjs` | auth walls, rate limits, upstream source failure |
 | `opendevbrowser-shopping` | `workflow` | `./skills/opendevbrowser-shopping/scripts/validate-skill-assets.sh` | `shopping run`, offer normalization, market analysis, direct provider workflows | `node scripts/provider-direct-runs.mjs` | auth walls, anti-bot challenges, rate limits, upstream outage |
 
 ## Shared runtime families

package/skills/opendevbrowser-best-practices/scripts/odb-workflow.sh

@@ -188,8 +188,9 @@ EOF
 # Public-first YouTube transcript probe
 node $TRANSCRIPT_PROBE_PATH --url "https://www.youtube.com/watch?v=aircAruvnKk" --youtube-mode auto --out artifacts/capability-fix/youtube-transcript-auto.json
 
-# Generic topical research without shopping contamination
-$CLI_PREFIX research run --topic "Chrome extension debugging workflows" --days 30 --source-selection auto --mode json --output-format json
+# Evidence-gated research primitive with explicit public source families
+# Load opendevbrowser-research first, then inspect records.json, context.json, meta.json, and report.md before publishing claims.
+$CLI_PREFIX research run --topic "Chrome extension debugging workflows" --days 30 --sources web,community --mode json --output-format json
 
 # Deterministic shopping reruns with explicit providers
 $CLI_PREFIX shopping run --query "wireless ergonomic mouse" --providers shopping/bestbuy,shopping/ebay --budget 150 --browser-mode managed --mode json --output-format json

package/skills/opendevbrowser-best-practices/scripts/validator-fixture-cli.sh

@@ -118,7 +118,29 @@ if (domain === "research" && command === "run") {
     );
     fs.writeFileSync(
       path.join(bundleDir, "report.md"),
-      `# Research Report\n\n- Topic: ${topic}\n- Days: ${days}\n- Source selection: ${sourceSelection}\n- Sources: ${sources}\n`
+      [
+        "# Research Report",
+        "",
+        `- Topic: ${topic}`,
+        `- Days: ${days}`,
+        `- Source selection: ${sourceSelection}`,
+        `- Sources: ${sources}`,
+        "",
+        "## Search Direction",
+        "Fixture provider pass suggested destination follow-up.",
+        "",
+        "## Candidate Triage",
+        "Accepted fixture destination and rejected shell candidates.",
+        "",
+        "## Rejected Candidates",
+        "Rejected privacy, login, and search shell examples.",
+        "",
+        "## Deep Dives",
+        "Opened the fixture destination page.",
+        "",
+        "## Synthesis Feedback",
+        "Remaining gap is independent corroboration."
+      ].join("\n")
     );
     fs.writeFileSync(
       path.join(bundleDir, "compact.md"),
@@ -148,7 +170,22 @@ if (domain === "research" && command === "run") {
       `- Days: ${days}`,
       `- Source selection: ${sourceSelection}`,
       `- Sources: ${sources}`,
-      "- Finding: ISSUE-09 pagination/result drift across sources"
+      "- Finding: ISSUE-09 pagination/result drift across sources",
+      "",
+      "## Search Direction",
+      "Fixture provider pass suggested destination follow-up.",
+      "",
+      "## Candidate Triage",
+      "Accepted fixture destination and rejected shell candidates.",
+      "",
+      "## Rejected Candidates",
+      "Rejected privacy, login, and search shell examples.",
+      "",
+      "## Deep Dives",
+      "Opened the fixture destination page.",
+      "",
+      "## Synthesis Feedback",
+      "Remaining gap is independent corroboration."
     ]);
     process.exit(0);
   }

package/skills/opendevbrowser-research/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: opendevbrowser-research
-description: Deterministic multi-source research workflow with strict timebox and artifact outputs.
+description: Skill-guided, evidence-gated research workflow for provider-constrained public source gathering and auditable artifact review.
 version: 2.1.0
 ---
 
 # Research Skill
 
-Use this skill when you need benchmark-style research across public `web|community|social` sources by default, with explicit shopping opt-in only for commercial comparison tasks.
+Load this skill before research tasks. Use it to plan source families, gather provider-constrained evidence, review artifacts, and publish only claims that survive the evidence gate.
+
+`opendevbrowser research run` is a low-level, best-effort primitive. It can collect and render provider results, but the skill owns source planning, blocker review, confidence, limitations, and final synthesis.
 
 ## Pack Contents
 
@@ -24,7 +26,7 @@ Use this skill when you need benchmark-style research across public `web|communi
 
 ```bash
 ./skills/opendevbrowser-research/scripts/validate-skill-assets.sh
-./skills/opendevbrowser-research/scripts/run-research.sh "browser automation" 30 context
+./skills/opendevbrowser-research/scripts/run-research.sh "browser automation" 30 context "web,community"
 ./skills/opendevbrowser-research/scripts/render-output.sh "browser automation" compact
 ```
 
@@ -37,11 +39,59 @@ Use this skill when you need benchmark-style research across public `web|communi
 ## Core Rules
 
 - Define timebox first (`--days` or `--from/--to`).
-- Prefer explicit sources for high-stakes claims.
+- Choose explicit source families before invoking the CLI primitive: `web`, `community`, `social`, `shopping`, or a deliberate combination such as `web,community`.
+- Treat `auto` as a source-family selector, not a reliability guarantee.
 - Persist artifacts and return reproducible paths.
-- Mark unsupported claims as tentative; do not overstate certainty.
+- Mark unsupported claims as tentative or exclude them from the final answer.
 - Honor bounded retries and backoff windows under 429 pressure.
 
+## Evidence Gate
+
+Review artifacts before publishing claims. A successful command exit or rendered report is not enough.
+
+Preserved artifact files:
+
+- `summary.md`
+- `report.md`
+- `records.json`
+- `context.json`
+- `meta.json`
+- `bundle-manifest.json`
+
+Required review:
+
+1. Read `records.json` for fetched source records, timestamps, providers, extraction quality, and blockers.
+2. Read `context.json` for source ledger, evidence gaps, unsupported claims, staleness checks, and search-engine provenance when used.
+3. Read `meta.json` for provider limits, warnings, no-evidence failures, cookie diagnostics, challenge/auth/token failures, and artifact generation details.
+4. When gated providers such as Reddit block evidence, rerun with user-authorized recovery only after candidate triage has exhausted relevant public destination pages: `--browser-mode extension` for an existing signed-in relay session, `--use-cookies` only when legitimate cookies are available, and `--challenge-automation-mode browser_with_helper` for browser-scoped assistance.
+5. Use `report.md` and `summary.md` only after confirming claims map back to accepted evidence.
+6. Do not use shell-only, stale-only, login-only, not-found-only, or zero-source-evidence runs to support final claims.
+
+## Guided Research Loop
+
+Research is iterative. Do not stop at the first provider page or SERP shell.
+
+1. Start with provider or search-engine direction: query, capture candidate URLs, rank, title, and blocker notes.
+2. Reject navigation dead ends before treating them as evidence: login routes, privacy or cookie preference pages, consent gates, search result shells, not-found pages, and JavaScript-only shells.
+3. Open destination pages from the candidate set, not account, privacy, cookie, or login links. For Reddit, prefer concrete `/r/.../comments/...` result URLs over `/login`, `/search`, `/account`, `/submit`, or root navigation.
+4. If a destination is blocked, record the blocker and choose the next candidate from the same result set before escalating to cookies or an authenticated browser.
+5. Escalate to `--browser-mode extension`, `--use-cookies`, or `--challenge-automation-mode browser_with_helper` only when the selected evidence page itself needs authorized browser recovery and the user has legitimate access.
+6. Continue until you have enough accepted destination evidence for the claims, or every relevant candidate is blocked, stale, irrelevant, or unsupported.
+7. Synthesize only after the loop produces accepted evidence. If no destination evidence survives, return limitations and next-step options instead of a research answer.
+
+## Search Engine Discovery Lane
+
+This lane is optional, skill-guided, provider-constrained, and discovery-only. It can improve breadth, but it is not a reliable default and does not replace `opendevbrowser research run` or the evidence gate.
+
+1. Choose up to five engines based on topic and availability. Candidate set: Google, Bing, Brave, DuckDuckGo or Yahoo for overlap checks, Yandex for regional or index diversity, Baidu for China-specific topics, and Kagi only when the user has account access.
+2. Record engine choice rationale, query variants, region and language assumptions, auth or cookie needs, and blockers.
+3. Collect up to 10 result URLs per selected engine. Preserve engine, query, rank, URL, title if available, and retrieval notes.
+4. Dedupe canonical URLs, then select the strongest 5 to 10 destination pages for extraction.
+5. Extract selected destination pages through OpenDevBrowser browsing primitives when useful, including DOM interaction and screenshots. Use cookies or authenticated browsing only after destination-candidate triage shows the selected evidence page itself requires authorized access.
+6. Do not violate robots restrictions, login walls, consent gates, CAPTCHAs, rate limits, anti-bot controls, or access controls. Stand down and record limitations instead.
+7. Keep SERPs discovery-only. SERP snippets, result pages, shells, and blocked pages cannot be final evidence.
+8. Final claims must cite destination pages or other fetched evidence that survived review.
+
 ## Parallel Multitab Alignment
 
 - Apply shared concurrency policy from `../opendevbrowser-best-practices/SKILL.md` ("Parallel Operations").
@@ -60,22 +110,24 @@ Matrix source: `../opendevbrowser-best-practices/artifacts/browser-agent-known-i
 ## Workflow
 
 1. Resolve timebox (`days` or `from/to`).
-2. Choose sources (`auto|web|community|social|shopping|all`).
-3. Run `opendevbrowser research run`.
-4. Return requested mode output and artifact path.
+2. Choose explicit source families and document why they fit the topic.
+3. Optionally run the search-engine discovery lane to find destination candidates.
+4. Run `opendevbrowser research run` as a low-level best-effort primitive.
+5. Review `records.json`, `context.json`, and `meta.json` before trusting `report.md`.
+6. If `meta.json` shows auth, token, challenge, or cookie-gated providers, make the next run skill-first only after the candidate queue has no relevant public destination evidence left: use the existing signed-in browser session when authorized, cookies only when legitimate cookies are available, and browser-scoped challenge assistance only for that browser session.
+7. Return final claims only when they are supported by accepted evidence.
 
 ## Commands
 
 ```bash
-opendevbrowser research run --topic "<topic>" --days 30 --source-selection auto --mode context
-opendevbrowser research run --topic "<topic>" --source-selection auto --mode json
+opendevbrowser research run --topic "<topic>" --days 30 --sources web,community --mode context
+opendevbrowser research run --topic "<topic>" --sources web --mode json
 opendevbrowser research run --topic "<topic>" --sources web,shopping --mode md
 ```
 
 ## Notes
 
-- `auto` is the recommended default for topical research.
-- In the current contract, both `auto` and `all` resolve to `web|community|social`.
+- `auto` and `all` are selector values in the current source-family contract, not promises of reliable coverage.
 - Use `--source-selection shopping` or explicit `--sources ...shopping...` to include shopping only when commercial intent is explicit.
 - Use `--mode path` with `scripts/write-artifacts.sh` when you need replayable handoff bundles.
 - For browser-backed release proof and mode sweeps, follow the canonical direct-run evidence policy in `../opendevbrowser-best-practices/SKILL.md`.

package/skills/opendevbrowser-research/artifacts/research-workflows.md

@@ -1,29 +1,66 @@
 # Research Workflows
 
-## Deterministic baseline workflow
+Use these workflows to plan evidence first, run provider-constrained collection second, and publish only claims that pass review.
 
-1. Define topic and strict time window
-2. Resolve source selection (`auto|all|explicit`)
-3. Run research workflow command
-4. Persist context/report artifacts
-5. Validate source diversity and freshness
+## Evidence-gated baseline workflow
 
-## Cross-source corroboration workflow
+1. Define topic, scope, and strict time window.
+2. Choose explicit source families before invoking the CLI primitive. Prefer `--sources web,community` for broad public research when both destination pages and community corroboration are useful.
+3. Record why each source family is in scope and which families are intentionally excluded.
+4. Run `opendevbrowser research run` as a low-level best-effort primitive.
+5. Inspect candidates and follow useful destination pages before synthesis. Never treat account, privacy, cookie, login, consent, search shell, not-found, or JavaScript shell pages as final evidence.
+6. If a selected destination is blocked, record the blocker and continue to the next relevant candidate before escalating to cookies or authenticated browser recovery.
+7. Persist `summary.md`, `report.md`, `records.json`, `context.json`, `meta.json`, and `bundle-manifest.json`.
+8. Review `records.json`, `context.json`, and `meta.json` before using `report.md`.
+9. If the selected evidence page itself proves auth, token, challenge, or cookie gating after public candidate triage, rerun through user-authorized browser recovery only after relevant public destination pages are exhausted: `--browser-mode extension` for an existing signed-in relay session, `--use-cookies` only when legitimate cookies are available, and `--challenge-automation-mode browser_with_helper` for browser-scoped assistance.
+10. Publish supported claims, mark weak claims as tentative, and exclude unsupported claims.
 
-1. Identify claims from first-pass output
-2. Require at least two independent source records for critical claims
-3. Mark unsupported claims as tentative
-4. Escalate when corroboration is missing
+## Iterative destination-follow workflow
 
-## Backoff/retry workflow
+Use this when the first pass returns shells, login pages, privacy/cookie pages, or search result pages.
 
-1. Detect repeated 429/upstream throttling
-2. Honor retry windows and bounded retries
-3. Resume from persisted context artifact
-4. Report partial coverage when limits persist
+1. Build a candidate queue from provider output or search-engine discovery: URL, rank, source family, title, and blocker notes.
+2. Remove dead-end routes from the queue: `/login`, `/account`, `/submit`, privacy preference pages, cookie preference pages, search result pages, consent-only pages, static assets, and not-found URLs.
+3. Open the highest-value remaining destination page with OpenDevBrowser.
+4. Extract text, source URL, title, timestamp, and visible limitations.
+5. If extraction returns a shell or blocker, mark that candidate rejected and continue with the next candidate.
+6. If extraction succeeds, add it to the claim map and decide whether more evidence is needed for corroboration.
+7. Stop only when accepted evidence is sufficient or every relevant candidate has a recorded rejection reason.
+
+## Claim-to-source review workflow
+
+1. Extract the claims that the final answer would make.
+2. Map each claim to accepted destination evidence in `records.json`.
+3. Check source date, fetch date, provider, extraction quality, and source independence.
+4. Require corroboration for critical claims when the topic allows it.
+5. Record evidence gaps, stale pages, login walls, challenge pages, rate limits, and extraction limits.
+6. Do not use shell-only, stale-only, login-only, not-found-only, or zero-source-evidence runs as final support.
+
+## Search Engine Discovery Lane
+
+This optional lane is skill-guided, provider-constrained, and discovery-only. It is for richer candidate discovery, not for runtime source-family expansion.
+
+1. Choose up to five engines based on topic and availability: Google, Bing, Brave, DuckDuckGo or Yahoo, Yandex, Baidu, and Kagi only with user account access.
+2. Record search_engine_passes with engine, query, region, language, rationale, cookie or auth needs, and blockers.
+3. Collect up to 10 SERP candidate URLs per engine with engine, query, rank, URL, title if available, and retrieval notes.
+4. Dedupe canonical URLs across engines.
+5. Select the strongest 5 to 10 destination pages for extraction.
+6. Fetch selected destination pages with OpenDevBrowser browsing primitives when useful, including DOM interaction and screenshots. Use cookies or authenticated browsing only after destination-candidate triage shows the selected evidence page itself requires legitimate user-authorized access.
+7. Stand down on robots restrictions, login walls, consent gates, CAPTCHAs, rate limits, anti-bot controls, and access controls. Record the limitation instead.
+8. Keep SERPs discovery-only. SERP snippets, search result pages, shells, and blocked pages cannot be final evidence.
+9. Cite destination-page evidence or other fetched evidence that passed review.
+
+## Backoff and blocker workflow
+
+1. Detect repeated 429 responses, provider throttling, challenge pages, login walls, token gates, consent gates, cookie diagnostics, or extraction failures.
+2. Honor retry windows and bounded retries.
+3. For gated providers such as Reddit, prefer a skill-first recovery rerun with an existing signed-in relay session, legitimate cookies only when available, and browser-scoped challenge assistance only after concrete result URLs from the candidate queue have been attempted or rejected with reasons.
+4. Resume from persisted artifacts only when the next run can add evidence without violating controls.
+5. Report partial coverage, provider constraints, and skipped lanes when limits persist.
 
 ## Compact handoff workflow
 
-1. Produce compact summary with key findings
-2. Include unresolved risks and missing evidence
-3. Attach artifact paths for replay
+1. Produce a compact summary with accepted claims only.
+2. Include evidence gaps, provider constraints, and limitations.
+3. Attach artifact paths for replay and review.
+4. Name unsupported claims that were excluded or left tentative.

package/skills/opendevbrowser-research/assets/templates/compact.md

@@ -1,7 +1,33 @@
 # Compact Research Template
 
-- Top findings:
-- Source diversity:
-- Key risks:
-- Rate-limit/backoff notes:
-- Open evidence gaps:
+- Topic and timebox:
+- Source families used:
+- Evidence-gated status:
+- Accepted claims:
+- Tentative or excluded claims:
+- Evidence gaps:
+- Provider constraints:
+- Staleness checks:
+- Search engine discovery, if used:
+  - direction from providers/search:
+  - candidate_triage:
+  - rejected_candidates:
+  - rejected privacy/login/shell pages:
+  - replacement destination followed:
+  - remaining candidate queue:
+  - deep-dive pages:
+  - next query or evidence gap:
+  - search_engine_passes:
+  - serp_candidates reviewed:
+  - selected_destination_pages:
+  - engine_failures:
+  - provenance:
+- synthesis_feedback:
+- Limitations:
+- Artifact paths:
+  - summary.md:
+  - report.md:
+  - records.json:
+  - context.json:
+  - meta.json:
+  - bundle-manifest.json: