@tangle-network/browser-agent-driver 0.33.3 → 0.35.0

package/dist/runner/runner.js

@@ -25,12 +25,18 @@ import { ContextBudget } from '../context-budget.js';
 import { runOverridePipeline } from '../override-pipeline.js';
 import { withRetry, findElementForRef, safeHostname, pushGoalVerificationEvidence } from './utils.js';
 import { runExtractWithIndex, formatExtractWithIndexResult } from '../drivers/extract-with-index.js';
-import { buildSearchResultsGuidance, buildVisibleLinkRecommendation, getVisibleLinkRecommendation, getRankedVisibleLinkCandidates, rankSearchCandidates } from './search-guidance.js';
+import { buildSearchResultsGuidance, buildVisibleLinkRecommendation, getVisibleLinkRecommendation } from './search-guidance.js';
 import { buildGoalVerificationClaim, collectSearchWorkflowEvidence, shouldAcceptSearchWorkflowCompletion, shouldAcceptScriptBackedCompletion, detectCompletionContentTypeMismatch } from './goal-verification.js';
-import { verifyExpectedEffect } from './effect-verification.js';
 import { detectAiTanglePartnerTemplateVisibleState, detectAiTangleVerifiedOutputState, shouldEscalateVision } from './page-analysis.js';
-import { shouldUseVisibleLinkScout, shouldUseVisibleLinkScoutPage, shouldUseBoundedBranchExplorer, inspectBranchPreview, scoreBranchPreview } from './scout.js';
 import { buildOverrideProducers, buildScoutLinkRecommendationText, buildBranchLinkRecommendationText } from './overrides.js';
+import { buildSearchResultsScoutFeedbackImpl, buildVisibleLinkScoutRecommendationImpl, buildBranchLinkRecommendationImpl, } from './scout-feedback.js';
+import { filterScoutCandidatesByAllowedDomainsImpl, inspectDisallowedSearchClickImpl, enforceAllowedDomainBoundaryImpl, } from './domain-boundary.js';
+import { attachDecisionScreenshotImpl } from './decision-screenshot.js';
+import { verifyEffectImpl } from './effect-verify.js';
+import { executePlanImpl } from './execute-plan.js';
+import { verifyExpectedEffect } from './effect-verification.js';
+import { createReplayController } from './replay/controller.js';
+import { createReplayGuard } from './replay/guard.js';
 import { RunRegistry } from '../memory/run-registry.js';
 import { ensureBus } from './events.js';
 import { DecisionCache } from './decision-cache.js';
@@ -40,81 +46,15 @@ import { matchDeterministicPattern } from './deterministic-patterns.js';
 import { deriveDirectStartUrl, shouldAcceptRolledBookingCompletion } from './direct-start.js';
 import { prepareGoogleFlightsSearch, shouldAcceptRolledGoogleFlightsCompletion } from './google-flights-preflight.js';
 import { containsSelfContradictingCompletion } from './completion-language.js';
-/**
- * Detect when the agent is filling a multi-field form one input at a time and
- * inject a hint that demands a `fill` batch on the next turn.
- *
- * Trigger conditions (all must hold):
- *   1. The agent's most recent action was a single-step `type` on the
- *      current URL
- *   2. The current snapshot has 2+ unused fillable refs (textbox /
- *      searchbox / combobox) that the agent hasn't typed into yet
- *   3. We haven't already injected this hint in the last turn (to avoid
- *      hint loops if the agent ignores it)
- *
- * The detector fires after one type action when two or more unused fields
- * remain, which catches common two-field-per-step forms before the agent
- * burns extra turns.
- *
- * The hint is high-priority (100) so it survives ctxBudget truncation, and
- * it explicitly lists the unused @refs from the current snapshot so the LLM
- * doesn't have to guess. The injection is gated by BAD_BATCH_HINT=0 for
- * rollback.
- */
-export function detectBatchFillOpportunity(turns, state) {
-    if (turns.length === 0)
-        return null;
-    const lastTurn = turns[turns.length - 1];
-    // Last action must be a single-step type on the current URL
-    if (lastTurn.action.action !== 'type')
-        return null;
-    if (lastTurn.state.url !== state.url)
-        return null;
-    // Collect the @refs the agent has typed into across the ENTIRE run on
-    // the same URL. The detector should never ask the agent to re-fill a
-    // field it already filled, even if the earlier fill happened many
-    // turns ago.
-    const usedRefs = new Set();
-    for (const t of turns) {
-        if (t.state.url !== state.url)
-            continue;
-        const a = t.action;
-        if (a.action === 'type' && 'selector' in a && typeof a.selector === 'string') {
-            usedRefs.add(a.selector);
-        }
-        if (a.action === 'fill') {
-            for (const k of Object.keys(a.fields ?? {}))
-                usedRefs.add(k);
-            for (const k of Object.keys(a.selects ?? {}))
-                usedRefs.add(k);
-            for (const k of a.checks ?? [])
-                usedRefs.add(k);
-        }
-    }
-    // Find unused fillable refs in the current snapshot. We look for textbox,
-    // searchbox, combobox, and spinbutton roles — anything that takes text.
-    // Snapshot lines look like: `  - textbox "First name" [ref=t1f2a]`
-    const unusedRefs = [];
-    for (const line of state.snapshot.split('\n')) {
-        const match = line.match(/\b(textbox|searchbox|combobox|spinbutton)\b[^"]*"([^"]*)"[^[]*\[ref=([^\]]+)\]/i);
-        if (!match)
-            continue;
-        const role = match[1].toLowerCase();
-        const name = match[2];
-        const ref = `@${match[3]}`;
-        if (usedRefs.has(ref))
-            continue;
-        unusedRefs.push({ ref, name, role });
-    }
-    // Need at least 2 unused fields to make batching worthwhile
-    if (unusedRefs.length < 2)
-        return null;
-    const refList = unusedRefs
-        .slice(0, 12) // cap so we don't explode the prompt
-        .map((u) => `  - ${u.ref} (${u.role}: "${u.name}")`)
-        .join('\n');
-    return `\n[BATCH FILL REQUIRED]\nYou just typed into a single field, but ${unusedRefs.length} more fillable fields are visible on this same form. STOP. Your NEXT action MUST be a \`fill\` action that batches ALL remaining unused fields on this page in one turn. Do not emit another single-step \`type\` — emit \`fill\` with multiple entries.\n\nUnused fillable @refs from the current snapshot (use these in your \`fill.fields\` map):\n${refList}\n\nExample:\n{\"action\":\"fill\",\"fields\":{\"${unusedRefs[0].ref}\":\"value1\",\"${unusedRefs[1].ref}\":\"value2\"}}\n`;
-}
+import { detectBatchFillOpportunity } from './batch-fill.js';
+import { DEFAULT_MAX_TURNS, DEFAULT_RETRIES, DEFAULT_RETRY_DELAY_MS, DEFAULT_SUPERVISOR, EXTENSION_TURNS_GRANTED, } from './constants.js';
+import { DEFI_BRAIN_CONTEXT } from './prompt-snippets.js';
+import { hasPlaceholderPattern, isMeaningfulRunScriptOutput } from './completion-policy.js';
+import { selectMicroPlanFollowUps } from './micro-plan.js';
+import { decideMaxTurnsExtension } from './max-turns-extension.js';
+// Re-export helpers that moved into sibling modules so existing import paths
+// (e.g. tests importing from './runner.js') keep working unchanged.
+export { detectBatchFillOpportunity, hasPlaceholderPattern, isMeaningfulRunScriptOutput };
 /** Build a structured session record from a completed run */
 function buildSession(scenario, result) {
     const lastTurn = result.turns[result.turns.length - 1];
@@ -129,99 +69,6 @@ function buildSession(scenario, result) {
         durationMs: result.totalMs,
     };
 }
-const DEFAULT_MAX_TURNS = 20;
-const DEFAULT_RETRIES = 3;
-const DEFAULT_RETRY_DELAY_MS = 1000;
-const DEFAULT_MICRO_PLAN_ACTIONS = 2;
-// Safe action verbs for micro-plans emitted by the model.
-const SAFE_MICRO_ACTIONS = new Set(['click', 'type', 'press', 'hover', 'select', 'scroll', 'wait', 'clickAt', 'typeAt', 'clickLabel', 'typeLabel']);
-const DEFAULT_SUPERVISOR = {
-    enabled: true,
-    useVision: true,
-    minTurnsBeforeInvoke: 5,
-    cooldownTurns: 3,
-    maxInterventions: 2,
-    hardStallWindow: 4,
-};
-const DEFI_BRAIN_CONTEXT = '\nWALLET/DeFi MODE ACTIVE — crypto app patterns:\n' +
-    '- PERSISTENT WIDGETS: Many DeFi apps have always-on support/chat widgets (bottom-right) that show as alertdialog. These CANNOT be dismissed. Ignore them and interact with the page directly.\n' +
-    '- WALLET CONNECTION: Look for "Connect Wallet" button, select MetaMask. The wallet extension handles the approval popup automatically.\n' +
-    '- TOKEN SELECTION: If you need to change a token, click the token selector button (usually shows token symbol/icon), search for the token name, and select it from the dropdown.\n' +
-    '- TRANSACTION FLOW: Enter amount → wait for quote/estimate to load → click action button (Swap/Supply/etc.) → review dialog appears → stop before confirming in MetaMask.\n' +
-    '- LOADING STATES: DeFi apps make many RPC calls. Wait for balances and quotes to appear before clicking action buttons. If a button says "Enter amount" or is disabled, the app is still loading.\n' +
-    '- NATIVE ETH: Prefer native ETH over wrapped tokens (WETH) when possible — avoids ERC-20 spending approval steps.\n' +
-    '- NETWORK SELECTOR: Do NOT change the network/chain. If a network dropdown opens accidentally, close it immediately.\n' +
-    '- COOKIE BANNERS: Dismiss immediately via Escape or Reject button — don\'t spend multiple turns on consent dialogs.\n';
-/**
- * Detect placeholder patterns in a planner-generated complete.result.
- *
- * The planner has to commit to its `complete.result` text BEFORE any prior
- * runScript step actually runs, so on extraction tasks it fabricates
- * placeholders. We detect those patterns and substitute the runScript
- * output (deterministic, no extra LLM call).
- *
- * Patterns we catch:
- *   - JSON `null` literals (e.g. `{"x": null, "y": null}`)
- *   - "<from prior step>", "<placeholder>", "<value from ...>", "<extracted ...>", "<observed ...>"
- *   - "{{...}}" template markers
- *
- * Conservative on purpose — we only substitute when the planner clearly
- * didn't know real values at planning time. A complete.result that contains
- * actual data (no nulls, no placeholder markers) passes through unchanged.
- */
-export function hasPlaceholderPattern(text) {
-    if (typeof text !== 'string' || text.length === 0)
-        return false;
-    if (/<from prior step>|<placeholder>|<value from|<extracted|<observed|<previous step|<runscript output>/i.test(text)) {
-        return true;
-    }
-    if (/\{\{[^}]+\}\}/.test(text)) {
-        return true;
-    }
-    // JSON-shape detection: a result that parses as JSON and contains null
-    // values is almost always a planner-fabricated extraction shell. Pure
-    // strings with the word "null" elsewhere don't match because we look
-    // for the JSON null literal pattern (`: null` or `[null`).
-    if (/:\s*null\b|\[\s*null\b/.test(text)) {
-        return true;
-    }
-    return false;
-}
-/** Returns true only when runScript output contains usable extracted data. */
-export function isMeaningfulRunScriptOutput(output) {
-    if (typeof output !== 'string')
-        return false;
-    const trimmed = output.trim();
-    if (trimmed.length === 0)
-        return false;
-    if (trimmed === 'null' || trimmed === 'undefined' || trimmed === '""' || trimmed === "''")
-        return false;
-    // Empty JSON shells: `{}`, `[]`, `{"x": null}`, `[null, null]`
-    if (trimmed === '{}' || trimmed === '[]')
-        return false;
-    if (hasPlaceholderPattern(trimmed))
-        return false;
-    // If the output parses as JSON and EVERY top-level value is null/empty,
-    // treat it as not meaningful. This catches `{"x": null, "y": ""}` even
-    // though the placeholder regex would already catch the null one.
-    try {
-        const parsed = JSON.parse(trimmed);
-        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-            const values = Object.values(parsed);
-            if (values.length > 0) {
-                const allEmpty = values.every((v) => v === null || v === undefined || v === '' || v === 0);
-                if (allEmpty)
-                    return false;
-            }
-        }
-        if (Array.isArray(parsed) && parsed.length === 0)
-            return false;
-    }
-    catch {
-        // Not JSON, that's fine — fall through to "meaningful" if we got here.
-    }
-    return true;
-}
 export function shouldUsePlannerForScenario(scenario, mode = 'always') {
     if (mode !== 'auto')
         return true;
@@ -242,6 +89,12 @@ export function shouldUsePlannerForScenario(scenario, mode = 'always') {
     return true;
 }
 export class BrowserAgent {
+    // Public fields below satisfy the extracted host interfaces (RunnerScoutHost,
+    // RunnerDomainHost, RunnerDecisionScreenshotHost, RunnerEffectVerifyHost,
+    // RunnerExecuteHost). The free functions in scout-feedback.ts,
+    // domain-boundary.ts, decision-screenshot.ts, effect-verify.ts, and
+    // execute-plan.ts read them through those interfaces; `implements` makes tsc
+    // prove the surface is complete.
     driver;
     brain;
     config;
@@ -249,11 +102,15 @@ export class BrowserAgent {
     beforeTurn;
     onPhaseTiming;
     referenceTrajectory;
+    replayPlan;
     projectStore;
     runRegistry;
     knowledge;
     selectorCache;
+    // Public so the extracted effect-verify.ts / execute-plan.ts hosts can read
+    // and write the cached post-action snapshot.
     cachedPostState;
+    // Public so the extracted execute-plan.ts host can emit loop events.
     bus;
     currentRunId = '';
     // In-session decision cache. Lazy-skips brain.decide() when the (snapshot,
@@ -272,6 +129,7 @@ export class BrowserAgent {
         this.beforeTurn = options.beforeTurn;
         this.onPhaseTiming = options.onPhaseTiming;
         this.referenceTrajectory = options.referenceTrajectory;
+        this.replayPlan = options.replayPlan;
         this.bus = ensureBus(options.eventBus);
         this.extensions = options.extensions;
         if (this.extensions) {
@@ -335,9 +193,6 @@ export class BrowserAgent {
         // when they reach the configured cap while still making page progress.
         let maxTurns = isVisionMode ? Math.max(baseMaxTurns, 30) : baseMaxTurns;
         let extensionGranted = false;
-        const EXTENSION_TURNS_GRANTED = 5;
-        const EXTENSION_HARD_CAP = 25;
-        const EXTENSION_PROGRESS_LOOKBACK = 3;
         const retries = this.config.retries ?? DEFAULT_RETRIES;
         const retryDelayMs = this.config.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
         const turns = [];
@@ -499,6 +354,59 @@ export class BrowserAgent {
             maxInterventions: this.config.supervisor?.maxInterventions ?? DEFAULT_SUPERVISOR.maxInterventions,
             hardStallWindow: this.config.supervisor?.hardStallWindow ?? DEFAULT_SUPERVISOR.hardStallWindow,
         };
+        // Replay-first path (sibling to the planner-first path below): when replay
+        // is enabled and a strict-matched plan was supplied, re-execute the recorded
+        // steps with ZERO per-action LLM calls. A fully-replayed-and-verified
+        // outcome returns immediately; anything else (a self-heal abort, or a clean
+        // replay whose goal verification did not confirm achievement) falls through
+        // to the planner / per-action loop FROM THE CURRENT PAGE STATE — the page is
+        // already navigated above, so there is no re-navigation. Replay appends to
+        // the same `turns` array, so the unified timeline is preserved and the loop
+        // offset (`plannerStartTurn`) is advanced past the replayed turns.
+        let replayTurnsConsumed = 0;
+        if (this.config.replay?.enabled && this.replayPlan && scenario.startUrl) {
+            const replayOutcome = await createReplayController().replay(this.replayPlan, {
+                goal: scenario.goal,
+                driver: this.driver,
+                guard: createReplayGuard(),
+                verifyGoal: (state, goal, claimed) => this.brain.verifyGoalCompletion(state, goal, claimed),
+                verifyEffect: (input) => verifyExpectedEffect(input),
+                ...(scenario.signal ? { signal: scenario.signal } : {}),
+                ...(this.config.debug ? { debug: true } : {}),
+                onEvent: (event) => this.handleReplayEvent(runId, event),
+            });
+            for (const turn of replayOutcome.turns) {
+                turns.push(turn);
+                this.onTurn?.(turn);
+            }
+            replayTurnsConsumed = turns.length;
+            if (replayOutcome.kind === 'completed' && replayOutcome.goalVerification.achieved) {
+                return buildResult({
+                    success: true,
+                    result: replayOutcome.finalResult,
+                    turns,
+                    totalMs: Date.now() - startTime,
+                    goalVerification: replayOutcome.goalVerification,
+                });
+            }
+            // healed | completed-but-not-achieved → fall through from the live state.
+            // (`no-candidate` is impossible here — a plan was supplied.)
+            if (replayOutcome.kind !== 'no-candidate') {
+                // Only prime the loop's first observe when we captured a usable
+                // snapshot; an empty snapshot would otherwise short-circuit observe().
+                if (replayOutcome.lastState.snapshot) {
+                    this.cachedPostState = replayOutcome.lastState;
+                }
+                const fallbackReason = replayOutcome.kind === 'healed'
+                    ? replayOutcome.reason
+                    : `replay completed ${replayOutcome.completedSteps}/${replayOutcome.totalSteps} steps but goal verification did not confirm achievement`;
+                this.brain.injectFeedback(`[REPLAY] A recorded shortcut for this goal was attempted but did not fully complete it (${fallbackReason}). `
+                    + `${replayTurnsConsumed} step(s) were already executed against the live page. Continue toward the goal from the current page state.`);
+                if (this.config.debug) {
+                    console.log(`[Runner] Replay fell through after ${replayTurnsConsumed} step(s): ${fallbackReason}`);
+                }
+            }
+        }
         // Planner-first path: make one LLM call to generate a plan, then execute
         // it deterministically. On deviation, replan from the current page state
         // with deviation context; after the retry budget is exhausted, fall back
@@ -507,7 +415,7 @@ export class BrowserAgent {
         // Plan execution writes to the same `turns` array, so post-run analysis
         // sees a unified timeline regardless of which path completed the run.
         let planFallbackContext = '';
-        let plannerStartTurn = 0;
+        let plannerStartTurn = replayTurnsConsumed;
         const plannerEnabled = this.config.plannerEnabled === true && process.env.BAD_PLANNER !== '0'
             && shouldUsePlannerForScenario(scenario, this.config.plannerMode ?? 'always');
         const maxReplans = 3;
@@ -538,7 +446,9 @@ export class BrowserAgent {
             if (initialState) {
                 this.cachedPostState = initialState;
                 let planLoopState = initialState;
-                let cumulativeTurnsConsumed = 0;
+                // Start past any replayed turns so the planner's turn numbering and the
+                // per-action loop offset stay contiguous with the replay timeline.
+                let cumulativeTurnsConsumed = replayTurnsConsumed;
                 let attempt = 0;
                 let lastDeviationReason = '';
                 let lastFailedStepIndex = 0;
@@ -675,24 +585,23 @@ export class BrowserAgent {
         for (let i = 1 + plannerStartTurn; i <= maxTurns; i++) {
             // Grant a one-time max-turns extension when the run reaches its cap
             // while still making recent progress.
-            if (i === maxTurns
-                && !extensionGranted
-                && !isVisionMode
-                && maxTurns < EXTENSION_HARD_CAP
-                && runState.lastProgressTurn >= maxTurns - EXTENSION_PROGRESS_LOOKBACK) {
-                const extendedMax = Math.min(maxTurns + EXTENSION_TURNS_GRANTED, EXTENSION_HARD_CAP);
-                const extra = extendedMax - maxTurns;
-                if (extra > 0) {
-                    this.bus.emitNow({
-                        type: 'recovery-fired',
-                        runId,
-                        turn: i,
-                        strategy: 'max-turns-extension',
-                        feedback: `Granted +${extra} extra turns (cap ${maxTurns} → ${extendedMax}); progress at turn ${runState.lastProgressTurn}.`,
-                    });
-                    maxTurns = extendedMax;
-                    extensionGranted = true;
-                }
+            const turnsExtension = decideMaxTurnsExtension({
+                turn: i,
+                maxTurns,
+                extensionGranted,
+                isVisionMode,
+                lastProgressTurn: runState.lastProgressTurn,
+            });
+            if (turnsExtension) {
+                this.bus.emitNow({
+                    type: 'recovery-fired',
+                    runId,
+                    turn: i,
+                    strategy: 'max-turns-extension',
+                    feedback: `Granted +${turnsExtension.extra} extra turns (cap ${maxTurns} → ${turnsExtension.extendedMax}); progress at turn ${runState.lastProgressTurn}.`,
+                });
+                maxTurns = turnsExtension.extendedMax;
+                extensionGranted = true;
             }
             // Honor user-driven pause or abort from the interrupt controller.
             if (this.beforeTurn) {
@@ -810,6 +719,7 @@ export class BrowserAgent {
                 }, scenario.signal);
                 this.cachedPostState = undefined;
                 const observeDurationMs = Date.now() - observeStartedAt;
+                phaseTimings.totalObserveMs = (phaseTimings.totalObserveMs ?? 0) + observeDurationMs;
                 if (phaseTimings.firstObserveMs === undefined) {
                     phaseTimings.firstObserveMs = observeDurationMs;
                     this.onPhaseTiming?.('observe', phaseTimings.firstObserveMs);
@@ -1294,6 +1204,15 @@ export class BrowserAgent {
                     }
                 }
                 const decideDurationMs = Date.now() - decideStartedAt;
+                phaseTimings.totalDecideMs = (phaseTimings.totalDecideMs ?? 0) + decideDurationMs;
+                // A pattern-match or cache-hit synthesised the decision with no LLM call;
+                // anything else round-tripped the model. Tracks the lazy-decision hit rate.
+                if (patternMatch || cached) {
+                    phaseTimings.decideSkips = (phaseTimings.decideSkips ?? 0) + 1;
+                }
+                else {
+                    phaseTimings.decideLlmCalls = (phaseTimings.decideLlmCalls ?? 0) + 1;
+                }
                 if (phaseTimings.firstDecideMs === undefined) {
                     phaseTimings.firstDecideMs = decideDurationMs;
                     this.onPhaseTiming?.('decide', phaseTimings.firstDecideMs);
@@ -1887,8 +1806,10 @@ export class BrowserAgent {
                     }, scenario.signal);
                     const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`Execute wall-clock timeout after ${executeWallClockMs}ms`)), executeWallClockMs));
                     execResult = await Promise.race([executePromise, timeoutPromise]);
+                    const executeDurationMs = Date.now() - executeStartedAt;
+                    phaseTimings.totalExecuteMs = (phaseTimings.totalExecuteMs ?? 0) + executeDurationMs;
                     if (phaseTimings.firstExecuteMs === undefined) {
-                        phaseTimings.firstExecuteMs = Date.now() - executeStartedAt;
+                        phaseTimings.firstExecuteMs = executeDurationMs;
                         this.onPhaseTiming?.('execute', phaseTimings.firstExecuteMs);
                     }
                     this.bus.emitNow({
@@ -2156,27 +2077,37 @@ export class BrowserAgent {
         });
     }
     selectFollowUpActions(primaryAction, nextActions) {
-        const microPlanConfig = this.config.microPlan;
-        if (microPlanConfig?.enabled !== true || !Array.isArray(nextActions) || nextActions.length === 0) {
-            return [];
-        }
-        // Never chain follow-up actions behind terminal/meta actions.
-        if (!SAFE_MICRO_ACTIONS.has(primaryAction.action)) {
-            return [];
-        }
-        const limit = Math.max(1, Math.min(4, microPlanConfig.maxActionsPerTurn ?? DEFAULT_MICRO_PLAN_ACTIONS));
-        const remainingSlots = Math.max(0, limit - 1);
-        if (remainingSlots === 0)
-            return [];
-        const selected = [];
-        for (const action of nextActions) {
-            if (!SAFE_MICRO_ACTIONS.has(action.action))
-                continue;
-            selected.push(action);
-            if (selected.length >= remainingSlots)
+        return selectMicroPlanFollowUps(primaryAction, nextActions, this.config.microPlan);
+    }
+    /**
+     * Surface replay lifecycle events. The structured TurnEventBus union is closed
+     * and replay is opt-in, so rather than widen it we log under debug — the
+     * self-heal decision is never silent (the controller also logs + returns a
+     * reason, and the runner logs the fall-through). `runId` is accepted for
+     * symmetry with bus emits and future wiring.
+     */
+    handleReplayEvent(_runId, event) {
+        if (!this.config.debug)
+            return;
+        switch (event.type) {
+            case 'replay-started':
+                console.log(`[Replay] start: ${event.totalSteps} step(s), goalSimilarity=${event.goalSimilarity.toFixed(2)}`);
+                break;
+            case 'replay-guard-abort':
+                console.log(`[Replay] guard abort at step ${event.index + 1}: ${event.reason}`);
+                break;
+            case 'replay-effect-failed':
+                console.log(`[Replay] effect failed at step ${event.index + 1}: ${event.reason}`);
+                break;
+            case 'replay-healed':
+                console.log(`[Replay] healed ${event.completedSteps}/${event.totalSteps}: ${event.reason}`);
+                break;
+            case 'replay-completed':
+                console.log(`[Replay] completed ${event.completedSteps} step(s), achieved=${event.achieved}`);
+                break;
+            default:
                 break;
         }
-        return selected;
     }
     /** Persist knowledge, selector cache, and session history to disk */
     saveMemory(scenario, result, turns) {
@@ -2243,659 +2174,32 @@ export class BrowserAgent {
      * unified timeline. The Turn's `reasoning` field carries the plan
      * step's rationale, and `verified` carries the verification result.
      */
-    async executePlan(plan, scenario, runId, turns, runState, startingTurnIndex, 
-    /**
-     * Token usage from the Brain.plan() LLM call that produced this plan.
-     * The plan call's tokens are NOT attached to any per-step turn — there's
-     * one plan call per N steps. To make the run-level cost tally honest,
-     * we attribute the plan call to the FIRST step's Turn artifact so the
-     * downstream sum (in baseline-summary.json / report.json) reflects the
-     * real LLM spend.
-     */
-    planCallTokens) {
-        let currentTurnIndex = startingTurnIndex;
-        let lastState = turns[turns.length - 1]?.state
-            ?? { url: '', title: '', snapshot: '' };
-        // Track the last successful runScript output so placeholder complete
-        // results can be substituted with the real script output.
-        let lastRunScriptOutput = null;
-        // Track extractWithIndex matches for per-action fallback; the LLM must
-        // read the list and pick by index.
-        let lastExtractOutput = null;
-        for (let stepIdx = 0; stepIdx < plan.steps.length; stepIdx++) {
-            if (scenario.signal?.aborted) {
-                return {
-                    kind: 'deviated',
-                    lastState,
-                    failedStepIndex: stepIdx,
-                    reason: scenario.signal.reason || 'Cancelled',
-                    turnsConsumed: stepIdx,
-                };
-            }
-            const step = plan.steps[stepIdx];
-            const stepStartedAt = Date.now();
-            const turnNumber = currentTurnIndex + 1;
-            currentTurnIndex++;
-            // Refresh the snapshot before EVERY step. The plan was built from a
-            // single observe() call at turn 1; later steps may target a different
-            // page entirely (after navigate / click "Next"). The first observe
-            // here is also what verify-against will eventually consume.
-            const preStepState = await this.driver.observe().catch(() => lastState);
-            lastState = preStepState;
-            // Wrap each plan step in a Turn artifact so post-run analysis (the
-            // viewer, the events.jsonl persistence, the metrics) sees a unified
-            // timeline regardless of whether the runner used the planner or the
-            // per-action loop.
-            //
-            // Token attribution: the first step carries the Brain.plan() LLM call's
-            // token usage so run-level cost includes planning.
-            const isFirstStep = stepIdx === 0;
-            const turn = {
-                turn: turnNumber,
-                state: preStepState,
-                action: step.action,
-                reasoning: step.rationale ?? `Plan step ${stepIdx + 1}/${plan.steps.length}`,
-                expectedEffect: step.expectedEffect,
-                plan: plan.steps.map((s) => s.rationale ?? s.action.action),
-                currentStep: stepIdx,
-                durationMs: 0,
-                ...(isFirstStep && planCallTokens?.tokensUsed !== undefined ? { tokensUsed: planCallTokens.tokensUsed } : {}),
-                ...(isFirstStep && planCallTokens?.inputTokens !== undefined ? { inputTokens: planCallTokens.inputTokens } : {}),
-                ...(isFirstStep && planCallTokens?.outputTokens !== undefined ? { outputTokens: planCallTokens.outputTokens } : {}),
-                ...(isFirstStep && planCallTokens?.cacheReadInputTokens !== undefined ? { cacheReadInputTokens: planCallTokens.cacheReadInputTokens } : {}),
-                ...(isFirstStep && planCallTokens?.cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens: planCallTokens.cacheCreationInputTokens } : {}),
-            };
-            // Terminal actions: complete and abort don't go through driver.execute
-            // — the runner handles them as the end of the plan.
-            if (step.action.action === 'complete') {
-                // Substitute placeholder complete results with prior runScript output.
-                let resolvedResult = step.action.result;
-                if (lastRunScriptOutput
-                    && typeof resolvedResult === 'string'
-                    && hasPlaceholderPattern(resolvedResult)) {
-                    if (this.config.debug) {
-                        console.log(`[Runner] Substituting placeholder complete.result with runScript output (${lastRunScriptOutput.length} chars)`);
-                    }
-                    resolvedResult = lastRunScriptOutput;
-                    turn.reasoning = `${turn.reasoning ?? ''} [substituted runScript output]`.trim();
-                }
-                turn.durationMs = Date.now() - stepStartedAt;
-                turns.push(turn);
-                this.onTurn?.(turn);
-                this.bus.emitNow({
-                    type: 'plan-step-executed',
-                    runId,
-                    turn: turnNumber,
-                    stepIndex: stepIdx + 1,
-                    totalSteps: plan.steps.length,
-                    action: step.action,
-                    executeSuccess: true,
-                    verified: true,
-                    durationMs: turn.durationMs,
-                });
-                return {
-                    kind: 'completed',
-                    lastState,
-                    finalResult: resolvedResult,
-                    turnsConsumed: stepIdx + 1,
-                };
-            }
-            if (step.action.action === 'abort') {
-                turn.durationMs = Date.now() - stepStartedAt;
-                turns.push(turn);
-                this.onTurn?.(turn);
-                this.bus.emitNow({
-                    type: 'plan-deviated',
-                    runId,
-                    turn: turnNumber,
-                    stepIndex: stepIdx + 1,
-                    totalSteps: plan.steps.length,
-                    reason: `plan aborted: ${step.action.reason}`,
-                });
-                return {
-                    kind: 'deviated',
-                    lastState,
-                    failedStepIndex: stepIdx,
-                    reason: `plan aborted: ${step.action.reason}`,
-                    turnsConsumed: stepIdx + 1,
-                };
-            }
-            // Execute the action via the existing driver path. This emits
-            // execute-started / execute-completed events on the bus exactly
-            // like the per-action loop does.
-            //
-            // Cap each plan step at 10s so missing selectors fail quickly and hand
-            // control back to per-action mode.
-            this.bus.emitNow({ type: 'execute-started', runId, turn: turnNumber, action: step.action });
-            const execStartedAt = Date.now();
-            const planStepTimeoutMs = 10_000;
-            let execResult;
-            try {
-                execResult = await Promise.race([
-                    this.driver.execute(step.action),
-                    new Promise((resolve) => setTimeout(() => resolve({ success: false, error: `plan step wall-clock timeout after ${planStepTimeoutMs}ms` }), planStepTimeoutMs)),
-                ]);
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                execResult = { success: false, error: message };
-            }
-            const execDurationMs = Date.now() - execStartedAt;
-            this.bus.emitNow({
-                type: 'execute-completed',
-                runId,
-                turn: turnNumber,
-                action: step.action,
-                success: execResult.success,
-                ...(execResult.error ? { error: execResult.error } : {}),
-                ...(execResult.bounds ? { bounds: execResult.bounds } : {}),
-                durationMs: execDurationMs,
-            });
-            if (!execResult.success) {
-                turn.error = execResult.error;
-                turn.durationMs = Date.now() - stepStartedAt;
-                turn.verified = false;
-                turn.verificationFailure = `execute failed: ${execResult.error}`;
-                turns.push(turn);
-                this.onTurn?.(turn);
-                runState.recordError();
-                this.bus.emitNow({
-                    type: 'plan-step-executed',
-                    runId,
-                    turn: turnNumber,
-                    stepIndex: stepIdx + 1,
-                    totalSteps: plan.steps.length,
-                    action: step.action,
-                    executeSuccess: false,
-                    verified: false,
-                    durationMs: Date.now() - stepStartedAt,
-                    ...(execResult.error ? { verifyReason: execResult.error } : {}),
-                });
-                this.bus.emitNow({
-                    type: 'plan-deviated',
-                    runId,
-                    turn: turnNumber,
-                    stepIndex: stepIdx + 1,
-                    totalSteps: plan.steps.length,
-                    reason: `execute failed: ${execResult.error}`,
-                });
-                return {
-                    kind: 'deviated',
-                    lastState,
-                    failedStepIndex: stepIdx,
-                    reason: `execute failed at step ${stepIdx + 1}: ${execResult.error}`,
-                    turnsConsumed: stepIdx + 1,
-                };
-            }
-            runState.clearConsecutiveErrors();
-            if (execResult.bounds)
-                turn.actionBounds = execResult.bounds;
-            // Capture runScript output for placeholder substitution and evidence.
-            if (step.action.action === 'runScript' && typeof execResult.data === 'string' && execResult.data.length > 0) {
-                lastRunScriptOutput = execResult.data;
-                if (execResult.data.length > 10) {
-                    runState.recordEvidence(`EXTRACTED (turn ${currentTurnIndex}): ${execResult.data.slice(0, 500)}`);
-                }
-            }
-            // Capture extractWithIndex output for per-action fallback.
-            if (step.action.action === 'extractWithIndex' && typeof execResult.data === 'string' && execResult.data.length > 0) {
-                lastExtractOutput = execResult.data;
-                // Also push as goal verification evidence so the verifier sees what
-                // the agent extracted.
-                runState.firstSufficientEvidenceTurn ??= currentTurnIndex;
-                pushGoalVerificationEvidence(runState.goalVerificationEvidence, `EXTRACT RESULT:\n${execResult.data}`);
-                if (execResult.data.length > 10) {
-                    runState.recordEvidence(`EXTRACTED (turn ${currentTurnIndex}): ${execResult.data.slice(0, 500)}`);
-                }
-            }
-            // Verify the post-condition. We re-observe to get the post-action
-            // state, then run the same verifyExpectedEffect helper the per-action
-            // loop uses. The fresh observe is also stashed in cachedPostState so
-            // the next step's pre-step observe can reuse it.
-            this.bus.emitNow({
-                type: 'verify-started',
-                runId,
-                turn: turnNumber,
-                expectedEffect: step.expectedEffect,
-            });
-            const verifyStartedAt = Date.now();
-            // Auto-pass list — these actions either don't observably mutate
-            // the page state OR they're self-verifying (the underlying Playwright
-            // call throws on real failure, so a successful return means the
-            // mutation actually happened). Strict expectedEffect verification
-            // would generate false negatives on the per-action loop fallback for
-            // these. Plan execution trusts the execute result.
-            //
-            // - wait / scroll / hover: don't mutate observable snapshot state
-            // - runScript / evaluate / verifyPreview: meta actions
-            // - fill / clickSequence: self-verifying (Playwright throws on miss),
-            //   AND input values don't always reflect in the ARIA snapshot, so
-            //   the permissive "did state change?" check would also miss them
-            const isAutoPass = step.action.action === 'wait'
-                || step.action.action === 'scroll'
-                || step.action.action === 'hover'
-                || step.action.action === 'runScript'
-                || step.action.action === 'extractWithIndex'
-                || step.action.action === 'evaluate'
-                || step.action.action === 'verifyPreview'
-                || step.action.action === 'fill'
-                || step.action.action === 'clickSequence';
-            // Settle wait for mutating actions, mirroring verifyEffect's logic
-            const needsSettleWait = step.action.action === 'click'
-                || step.action.action === 'navigate'
-                || step.action.action === 'press'
-                || step.action.action === 'select'
-                || step.action.action === 'fill'
-                || step.action.action === 'clickSequence';
-            const observePromise = this.driver.observe().catch(() => preStepState);
-            if (needsSettleWait) {
-                await Promise.all([
-                    observePromise,
-                    new Promise((r) => setTimeout(r, 50)),
-                ]);
-            }
-            const postStepState = await observePromise;
-            this.cachedPostState = postStepState;
-            lastState = postStepState;
-            // Plan verification is more permissive than per-action verification:
-            // a step passes if (a) it's a non-mutating action, OR (b) the strict
-            // verifier passes, OR (c) the snapshot/url changed in any meaningful
-            // way (the action did SOMETHING). Strict failure-on-no-change is
-            // appropriate for the per-action loop where the agent can recover,
-            // but plan execution needs to push forward unless there's positive
-            // evidence of failure.
-            let verifyResult;
-            if (isAutoPass) {
-                verifyResult = { verified: true };
-            }
-            else {
-                const strictResult = verifyExpectedEffect({
-                    expectedEffect: step.expectedEffect,
-                    preActionState: preStepState,
-                    postActionState: postStepState,
-                });
-                if (strictResult.verified) {
-                    verifyResult = strictResult;
-                }
-                else {
-                    // Permissive fallback: did the page change at all?
-                    const stateChanged = preStepState.url !== postStepState.url
-                        || preStepState.title !== postStepState.title
-                        || preStepState.snapshot !== postStepState.snapshot;
-                    if (stateChanged) {
-                        verifyResult = { verified: true };
-                    }
-                    else {
-                        verifyResult = strictResult;
-                    }
-                }
-            }
-            turn.verified = verifyResult.verified;
-            if (!verifyResult.verified) {
-                turn.verificationFailure = verifyResult.reason;
-            }
-            turn.durationMs = Date.now() - stepStartedAt;
-            turns.push(turn);
-            this.onTurn?.(turn);
-            this.bus.emitNow({
-                type: 'verify-completed',
-                runId,
-                turn: turnNumber,
-                verified: verifyResult.verified,
-                ...(verifyResult.reason ? { reason: verifyResult.reason } : {}),
-                durationMs: Date.now() - verifyStartedAt,
-            });
-            this.bus.emitNow({
-                type: 'plan-step-executed',
-                runId,
-                turn: turnNumber,
-                stepIndex: stepIdx + 1,
-                totalSteps: plan.steps.length,
-                action: step.action,
-                executeSuccess: true,
-                verified: verifyResult.verified,
-                durationMs: Date.now() - stepStartedAt,
-                ...(verifyResult.reason ? { verifyReason: verifyResult.reason } : {}),
-            });
-            if (!verifyResult.verified) {
-                this.bus.emitNow({
-                    type: 'plan-deviated',
-                    runId,
-                    turn: turnNumber,
-                    stepIndex: stepIdx + 1,
-                    totalSteps: plan.steps.length,
-                    reason: `verification failed at step ${stepIdx + 1}: ${verifyResult.reason ?? 'expected effect not observed'}`,
-                });
-                return {
-                    kind: 'deviated',
-                    lastState,
-                    failedStepIndex: stepIdx,
-                    reason: `verification failed at step ${stepIdx + 1}: ${verifyResult.reason ?? 'expected effect not observed'}`,
-                    turnsConsumed: stepIdx + 1,
-                };
-            }
-        }
-        // Auto-complete when the plan ends with meaningful runScript output.
-        const lastStep = plan.steps[plan.steps.length - 1];
-        if (lastStep
-            && lastStep.action.action === 'runScript'
-            && isMeaningfulRunScriptOutput(lastRunScriptOutput)) {
-            const synthTurnNumber = currentTurnIndex + 1;
-            const synthTurn = {
-                turn: synthTurnNumber,
-                state: lastState,
-                action: { action: 'complete', result: lastRunScriptOutput },
-                reasoning: 'Auto-complete: plan ended after runScript, runner emitted complete with the runScript output',
-                durationMs: 0,
-            };
-            turns.push(synthTurn);
-            this.onTurn?.(synthTurn);
-            this.bus.emitNow({
-                type: 'plan-step-executed',
-                runId,
-                turn: synthTurnNumber,
-                stepIndex: plan.steps.length + 1,
-                totalSteps: plan.steps.length + 1,
-                action: synthTurn.action,
-                executeSuccess: true,
-                verified: true,
-                durationMs: 0,
-            });
-            if (this.config.debug) {
-                console.log(`[Runner] Auto-emitted complete with runScript output (${lastRunScriptOutput.length} chars) after plan exhausted`);
-            }
-            return {
-                kind: 'completed',
-                lastState,
-                finalResult: lastRunScriptOutput,
-                turnsConsumed: plan.steps.length + 1,
-            };
-        }
-        // If the plan produced extractWithIndex matches, fall through with the
-        // match list so the LLM can choose the correct index.
-        if (lastExtractOutput) {
-            return {
-                kind: 'deviated',
-                lastState,
-                failedStepIndex: plan.steps.length,
-                reason: `plan completed extractWithIndex but the LLM must read the matches and pick by index. Match list:\n${lastExtractOutput.slice(0, 4000)}\n\nPick the index whose text matches the goal, then emit complete with result: <picked text>`,
-                turnsConsumed: plan.steps.length,
-            };
-        }
-        // If the plan ends with runScript but output is empty or placeholder-like,
-        // fall through to per-action mode instead of completing with bad data.
-        if (lastStep
-            && lastStep.action.action === 'runScript'
-            && !isMeaningfulRunScriptOutput(lastRunScriptOutput)) {
-            if (this.config.debug) {
-                console.log(`[Runner] runScript returned no meaningful output (${JSON.stringify(lastRunScriptOutput).slice(0, 100)}); falling through to per-action loop for two-pass extraction`);
-            }
-            return {
-                kind: 'deviated',
-                lastState,
-                failedStepIndex: plan.steps.length - 1,
-                reason: `runScript returned no meaningful output (got: ${JSON.stringify(lastRunScriptOutput).slice(0, 200)}). The first-pass extraction failed — re-observe the page and try extractWithIndex with a wide query (e.g. 'p, span, dd, code') and a contains filter naming the expected text fragment. Pick-by-content beats pick-by-selector when the planner couldn't see the data at plan time.`,
-                turnsConsumed: plan.steps.length,
-            };
-        }
-        // All steps verified BUT the plan ended without an explicit complete/abort.
-        // This means the planner emitted a finite sequence of "work" steps and
-        // didn't terminate. The right behavior is NOT to fabricate a complete —
-        // we treat plan exhaustion as a deviation that triggers fallback to the
-        // per-action loop. The per-action loop will continue from the current
-        // state and emit `complete` when the goal is genuinely met.
-        return {
-            kind: 'deviated',
-            lastState,
-            failedStepIndex: plan.steps.length,
-            reason: 'plan exhausted without an explicit complete or abort step — falling through to per-action loop to finish the task',
-            turnsConsumed: plan.steps.length,
-        };
+    async executePlan(plan, scenario, runId, turns, runState, startingTurnIndex, planCallTokens) {
+        return executePlanImpl(this, plan, scenario, runId, turns, runState, startingTurnIndex, planCallTokens);
     }
     async verifyEffect(expectedEffect, preActionState, actionType) {
-        // Only pause for actions that mutate the page in flight (navigation,
-        // clicks that may trigger XHR/route transitions, form submits). For
-        // pure reads, scrolls, hovers, and waits the page state is already
-        // settled by the time execute returns. The previous unconditional
-        // 100ms wait was pure dead time on every turn.
-        const needsSettleWait = actionType === 'click'
-            || actionType === 'navigate'
-            || actionType === 'press'
-            || actionType === 'select';
-        // Kick observe off immediately and let the settle wait race against it.
-        // observe() polls waitForLoadState internally, so the 50ms settle is
-        // really only there to let click handlers schedule their first XHR; we
-        // don't need to *block* on it before starting observe.
-        const observePromise = this.driver.observe().catch(() => preActionState);
-        if (needsSettleWait) {
-            await Promise.all([
-                observePromise,
-                new Promise(r => setTimeout(r, 50)),
-            ]);
-        }
-        const postState = await observePromise;
-        this.cachedPostState = postState;
-        return verifyExpectedEffect({
-            expectedEffect,
-            preActionState,
-            postActionState: postState,
-        });
+        return verifyEffectImpl(this, expectedEffect, preActionState, actionType);
     }
     async buildSearchResultsScoutFeedback(state, goal, allowedDomains, seenUrls) {
-        if (!buildSearchResultsGuidance(state, goal, allowedDomains))
-            return '';
-        if (seenUrls.has(state.url))
-            return '';
-        const page = this.driver.getPage?.();
-        if (!page)
-            return '';
-        try {
-            const candidates = await page.evaluate(() => {
-                const items = [];
-                const seen = new Set();
-                const selectors = [
-                    'main a[href]',
-                    '[role="main"] a[href]',
-                    'article a[href]',
-                    '.search-results a[href]',
-                    '#search-results a[href]',
-                    '.results a[href]',
-                    'ol a[href]',
-                ];
-                const fallbackLinks = Array.from(document.querySelectorAll('a[href]'));
-                const links = selectors
-                    .flatMap((selector) => Array.from(document.querySelectorAll(selector)))
-                    .concat(fallbackLinks);
-                const noisePattern = /\b(next|previous|page \d+|show more|show fewer|filter|sort|home|contact|privacy|accessibility|search)\b/i;
-                for (const node of links) {
-                    const anchor = node;
-                    const href = anchor.href?.trim();
-                    const title = (anchor.innerText || anchor.textContent || '').replace(/\s+/g, ' ').trim();
-                    if (!href || !title || title.length < 12 || title.length > 220)
-                        continue;
-                    if (href.startsWith('javascript:') || href.startsWith('mailto:') || href.includes('#'))
-                        continue;
-                    if (href.includes('results.aspx') && !/open government|dataset|data|news release|press release/i.test(title))
-                        continue;
-                    if (noisePattern.test(title) && !/open government|dataset|data|news release|press release/i.test(title))
-                        continue;
-                    const key = `${title}::${href}`;
-                    if (seen.has(key))
-                        continue;
-                    seen.add(key);
-                    items.push({ title, href });
-                    if (items.length >= 24)
-                        break;
-                }
-                return items;
-            });
-            if (!Array.isArray(candidates) || candidates.length === 0)
-                return '';
-            const ranked = rankSearchCandidates(goal, candidates, allowedDomains);
-            const recommendation = ranked[0];
-            seenUrls.add(state.url);
-            return [
-                'SEARCH RESULTS CANDIDATES:',
-                ...ranked.map((candidate, index) => `${index + 1}. ${candidate.title} — ${candidate.href} (score ${candidate.score})`),
-                recommendation
-                    ? `BEST MATCH RECOMMENDATION: prefer "${recommendation.title}" because it best matches the requested entity, content type, and host constraints.`
-                    : '',
-            ].join('\n');
-        }
-        catch {
-            return '';
-        }
+        return buildSearchResultsScoutFeedbackImpl(this, state, goal, allowedDomains, seenUrls);
     }
     async buildVisibleLinkScoutRecommendation(state, goal, allowedDomains) {
-        const scoutConfig = this.config.scout;
-        if (!scoutConfig?.enabled)
-            return undefined;
-        if (!shouldUseVisibleLinkScoutPage(state, goal, allowedDomains))
-            return undefined;
-        const ranked = getRankedVisibleLinkCandidates(state, goal, allowedDomains);
-        const maxCandidates = Math.max(2, Math.min(scoutConfig.maxCandidates ?? 3, 5));
-        const candidates = await this.filterScoutCandidatesByAllowedDomains(ranked.slice(0, maxCandidates), allowedDomains);
-        if (!shouldUseVisibleLinkScout(candidates, scoutConfig))
-            return undefined;
-        const scoutState = scoutConfig.useVision
-            ? await this.attachDecisionScreenshot(state)
-            : state;
-        const extraContext = allowedDomains && allowedDomains.length > 0
-            ? `Host constraint: prefer only ${allowedDomains.join(', ')}.`
-            : undefined;
-        const recommendation = await this.brain.recommendLinkCandidate(goal, scoutState, candidates, extraContext);
-        const matched = candidates.find((candidate) => candidate.ref === recommendation.selector);
-        if (!matched)
-            return undefined;
-        return {
-            ref: matched.ref,
-            text: matched.text,
-            confidence: recommendation.confidence,
-            reasoning: recommendation.reasoning,
-        };
+        return buildVisibleLinkScoutRecommendationImpl(this, state, goal, allowedDomains);
     }
     async buildBranchLinkRecommendation(state, goal, allowedDomains) {
-        const scoutConfig = this.config.scout;
-        if (!scoutConfig?.enabled || !scoutConfig.readOnlyTop2Challenger)
-            return undefined;
-        if (!shouldUseVisibleLinkScoutPage(state, goal, allowedDomains))
-            return undefined;
-        const ranked = getRankedVisibleLinkCandidates(state, goal, allowedDomains);
-        const candidates = ranked.slice(0, 2);
-        if (!shouldUseBoundedBranchExplorer(candidates, scoutConfig))
-            return undefined;
-        if (!this.driver.inspectSelectorHref || !this.driver.getPage)
-            return undefined;
-        const page = this.driver.getPage();
-        if (!page)
-            return undefined;
-        const settled = await Promise.all(candidates.map(async (candidate) => {
-            const href = await this.driver.inspectSelectorHref(candidate.ref).catch(() => undefined);
-            if (!href)
-                return undefined;
-            const preview = await inspectBranchPreview(page, href, 8000);
-            if (!preview)
-                return undefined;
-            return { ref: candidate.ref, text: candidate.text, href, score: scoreBranchPreview(goal, preview, allowedDomains), preview };
-        }));
-        const previews = settled.filter((r) => r !== undefined);
-        if (previews.length < 2)
-            return undefined;
-        previews.sort((a, b) => b.score - a.score);
-        const [top, second] = previews;
-        if (top.score <= second.score)
-            return undefined;
-        if (top.score < 4)
-            return undefined;
-        return {
-            ref: top.ref,
-            text: top.text,
-            confidence: Math.min(0.95, 0.7 + Math.max(0, top.score - second.score) / 20),
-            reasoning: `Branch preview favored ${top.href} (${top.preview.title || top.preview.finalUrl}) over ${second.href} based on content-type and goal-match signals.`,
-        };
+        return buildBranchLinkRecommendationImpl(this, state, goal, allowedDomains);
     }
     async filterScoutCandidatesByAllowedDomains(candidates, allowedDomains) {
-        if (!allowedDomains || allowedDomains.length === 0 || !this.driver.inspectSelectorHref) {
-            return candidates;
-        }
-        const allowedHosts = new Set(allowedDomains.map((domain) => domain.toLowerCase()));
-        const resolved = await Promise.all(candidates.map(async (candidate) => {
-            const href = await this.driver.inspectSelectorHref(candidate.ref).catch(() => undefined);
-            const host = href ? safeHostname(href) : undefined;
-            return { candidate, host };
-        }));
-        return resolved
-            .filter(({ host }) => !host || allowedHosts.has(host))
-            .map(({ candidate }) => candidate);
+        return filterScoutCandidatesByAllowedDomainsImpl(this, candidates, allowedDomains);
     }
     async inspectDisallowedSearchClick(state, scenario, action) {
-        if (action.action !== 'click')
-            return undefined;
-        if (!scenario.allowedDomains || scenario.allowedDomains.length === 0)
-            return undefined;
-        if (!buildSearchResultsGuidance(state, scenario.goal, scenario.allowedDomains))
-            return undefined;
-        if (!this.driver.inspectSelectorHref)
-            return undefined;
-        const href = await this.driver.inspectSelectorHref(action.selector);
-        const host = href ? safeHostname(href) : undefined;
-        if (!href || !host)
-            return undefined;
-        const allowedLower = scenario.allowedDomains.map((domain) => domain.toLowerCase());
-        if (allowedLower.includes(host))
-            return undefined;
-        // First-party subdomain tolerance
-        const toRoot = (h) => {
-            const parts = h.split('.').filter(Boolean);
-            return parts.length <= 2 ? h : parts.slice(-2).join('.');
-        };
-        if (allowedLower.some((h) => toRoot(h) === toRoot(host)))
-            return undefined;
-        return [
-            `Blocked action: selector ${action.selector} resolves to ${href}, which is outside the allowed host set: ${scenario.allowedDomains.join(', ')}.`,
-            'Choose a result from an allowed host instead, even if the snippet text looks relevant.',
-        ].join(' ');
+        return inspectDisallowedSearchClickImpl(this, state, scenario, action);
     }
     async enforceAllowedDomainBoundary(preActionState, scenario) {
-        if (!scenario.allowedDomains || scenario.allowedDomains.length === 0)
-            return undefined;
-        const currentUrl = this.driver.getUrl?.() ?? preActionState.url;
-        const currentHost = safeHostname(currentUrl);
-        if (!currentHost)
-            return undefined;
-        const allowedHosts = scenario.allowedDomains.map((domain) => domain.toLowerCase());
-        if (allowedHosts.includes(currentHost))
-            return undefined;
-        // First-party subdomain tolerance: allow navigation within the same registrable domain
-        const toRoot = (h) => {
-            const parts = h.split('.').filter(Boolean);
-            return parts.length <= 2 ? h : parts.slice(-2).join('.');
-        };
-        const currentRoot = toRoot(currentHost);
-        if (allowedHosts.some((h) => toRoot(h) === currentRoot))
-            return undefined;
-        const previousHost = safeHostname(preActionState.url);
-        if (previousHost && allowedHosts.includes(previousHost)) {
-            await this.driver.execute({ action: 'navigate', url: preActionState.url }).catch(() => { });
-        }
-        else if (scenario.startUrl) {
-            await this.driver.execute({ action: 'navigate', url: scenario.startUrl }).catch(() => { });
-        }
-        return [
-            `Boundary violation: landed on ${currentUrl}, but the allowed host set is ${allowedHosts.join(', ')}.`,
-            'Return to an allowed host and continue from there; do not rely on disallowed subdomains even if their snippet looks relevant.',
-        ].join(' ');
+        return enforceAllowedDomainBoundaryImpl(this, preActionState, scenario);
     }
     async attachDecisionScreenshot(state) {
-        if (state.screenshot || !this.driver.screenshot)
-            return state;
-        try {
-            const screenshot = await this.driver.screenshot();
-            return { ...state, screenshot: screenshot.toString('base64') };
-        }
-        catch {
-            return state;
-        }
+        return attachDecisionScreenshotImpl(this, state);
     }
 }
 /** Convenience function */