@enricai/barnacle 1.12.3 → 1.12.5

package/dist/scraper/flow-runner.js

@@ -68,6 +68,7 @@ exports.parseSelectStep = parseSelectStep;
 exports.parseFillStep = parseFillStep;
 exports.parseFillValueIntent = parseFillValueIntent;
 exports.parseRadioStep = parseRadioStep;
+exports.parseWidgetOptionClickStep = parseWidgetOptionClickStep;
 exports.parseCheckStep = parseCheckStep;
 exports.pollEnumerate = pollEnumerate;
 exports.waitForTransitionBody = waitForTransitionBody;
@@ -388,6 +389,13 @@ const SELECT_SETTLE_MS = 400;
  * triggered it.
  */
 const PROMPT_SELECTOR_SETTLE_MS = 400;
+/**
+ * Cap on the category->leaf drill loop in {@link commitPromptOption}: a
+ * two-level cascading multiselect (category click re-renders the popup to
+ * leaves) only ever drills one level deep in the wild, so 3 gives headroom
+ * for a rarer 2-level cascade without letting a genuinely broken widget spin.
+ */
+const PROMPT_SELECTOR_MAX_DRILL_DEPTH = 3;
 /**
  * Temporary attribute {@link tryPromptSelectorPrimitive} stamps onto each
  * candidate widget during its read-only enumerate pass, so the Node-side click
@@ -3814,6 +3822,48 @@ function parseRadioStep(instruction) {
     const questionLabel = pickQuestionLabel(instruction, option);
     return { option, questionLabel };
 }
+/**
+ * Parse a cascading-multiselect CATEGORY/LEAF widget-option click step into
+ * the option to click.
+ *
+ * Why this exists (sibling of `parseRadioStep`): flow/replan generation
+ * describes a two-level cascading multiselect's category and leaf clicks as
+ * "click the top-level category 'Job Boards' to expand its sub-options" and
+ * "click the leaf option 'Internet - Job Boards/Search Engines' to commit the
+ * source value" — a `click` verb paired with a `category`/`option` noun that
+ * `parseRadioStep` deliberately does not recognize (its `answer`/`radio` noun
+ * set, and `tryRadioPrimitive`'s native `input[type=radio]` matching, are
+ * scoped to actual radio groups). Left unrecognized, this phrasing matches
+ * none of `tryPromptSelectorPrimitive`'s accepted shapes, so the primitive
+ * returns before ever inspecting the DOM and the step falls to the observe
+ * cascade's untrusted `el.click()`, which this widget family ignores.
+ *
+ * Deliberately excludes select/checkbox/radio-answer steps (checked first,
+ * mirroring `parseRadioStep`'s own precedence) so a single step never
+ * resolves through two primitives.
+ */
+function parseWidgetOptionClickStep(instruction) {
+    const lower = instruction.toLowerCase();
+    if (/\bselect(\s+or\s+check)?\b/.test(lower))
+        return null;
+    if (!/\bclick\b/.test(lower))
+        return null;
+    if (!/\b(category|option)\b/.test(lower))
+        return null;
+    // Catch-all steps ("for any remaining…") have no concrete single target.
+    if (/\bany\s+remaining\b/.test(lower))
+        return null;
+    // The OPTION is the quoted string after "click the <category|option noun>",
+    // tolerant of a short qualifier ("top-level", "leaf") between the noun and
+    // the quote — e.g. "click the top-level category 'Job Boards'" or "click
+    // the leaf option 'Internet - Job Boards/Search Engines'".
+    const optMatch = instruction.match(/\bclick\s+the\s+(?:\S+\s+)?(?:category|option)\s+'([^']+)'/i);
+    if (!optMatch)
+        return null;
+    // biome-ignore lint/style/noNonNullAssertion: guarded by the !optMatch early-return; group 1 is required by the pattern
+    const option = optMatch[1].trim();
+    return { option };
+}
 /**
  * Parse a CHECKBOX flow step into the label of the checkbox it targets.
  *
@@ -5020,19 +5070,29 @@ async function tryPromptSelectorPrimitive(params) {
     // than a SELECT step, and its Yes/No variant renders no native radio inputs
     // at all, so flow/replan generation describes it with the same answer-verb
     // phrasing used for native radios ("Click the 'Yes' answer for the question
-    // '…'"). Accept all three shapes: parseSelectStep first, then parseFillStep
-    // (fieldLabel -> questionLabel, value -> option), then parseRadioStep
-    // (option/questionLabel already in this primitive's shape) so the widget-
-    // matching/open/readback phases below run unchanged regardless of which
-    // verb the instruction used.
+    // '…'"). Also accepts a cascading-multiselect CATEGORY/LEAF click step
+    // (`parseWidgetOptionClickStep`, "click the top-level category 'X'" /
+    // "click the leaf option 'Y'") — that widget's category/leaf clicks carry
+    // no question label, matched instead by the single-unfilled-widget rule
+    // below. Accept all four shapes: parseSelectStep first, then
+    // parseFillStep (fieldLabel -> questionLabel, value -> option), then
+    // parseRadioStep (option/questionLabel already in this primitive's
+    // shape), then parseWidgetOptionClickStep (option only, no question
+    // label) so the widget-matching/open/readback phases below run unchanged
+    // regardless of which verb the instruction used.
     const parsedSelect = parseSelectStep(instruction);
     const parsedFill = parsedSelect ? null : parseFillStep(instruction);
     const parsedAnswer = parsedSelect || parsedFill ? null : parseRadioStep(instruction);
+    const parsedOptionClick = parsedSelect || parsedFill || parsedAnswer ? null : parseWidgetOptionClickStep(instruction);
     const parsed = parsedSelect
         ? parsedSelect
         : parsedFill
             ? { option: parsedFill.value, questionLabel: stripQuotedLabel(parsedFill.fieldLabel) }
-            : parsedAnswer;
+            : parsedAnswer
+                ? parsedAnswer
+                : parsedOptionClick
+                    ? { option: parsedOptionClick.option, questionLabel: null }
+                    : null;
     if (!parsed)
         return null;
     const { option, questionLabel } = parsed;
@@ -5167,33 +5227,6 @@ async function tryPromptSelectorPrimitive(params) {
             logger.info(`prompt-selector primitive: no unambiguous widget match for ${optLabel}; falling through to cascade`);
             return null;
         }
-        // Phase 2 (real gesture): open the popup. These widgets' trigger requires a
-        // genuine click — a synthetic dispatchEvent does not fire its handler.
-        // Prefer the marked widget's own interactive descendant (a real form
-        // control) over the marked container itself, since the container is
-        // frequently a non-interactive layout wrapper for widget shapes whose
-        // actual trigger sits a level deeper (see PROMPT_INTERACTIVE_CONTROL_SELECTORS).
-        const containerTriggerSel = `[${PROMPT_WIDGET_MARK_ATTR}="${chosen.wIdx}"]`;
-        const innerTriggerSel = PROMPT_INTERACTIVE_CONTROL_SELECTORS.split(",")
-            .map((s) => `${containerTriggerSel} ${s}`)
-            .join(",");
-        let triggerSel = containerTriggerSel;
-        try {
-            const innerCount = await target.locator(innerTriggerSel).count();
-            if (innerCount > 0)
-                triggerSel = innerTriggerSel;
-        }
-        catch {
-            // Fall back to the container selector.
-        }
-        try {
-            await target.locator(triggerSel).first().click();
-        }
-        catch (err) {
-            logger.info(`prompt-selector primitive: trigger click failed for ${optLabel}: ${(0, errors_1.toErrorMessage)(err)}; falling through`);
-            return null;
-        }
-        await page.waitForTimeout(PROMPT_SELECTOR_SETTLE_MS);
         const enumerateOptionsExpr = `((widgetMarkAttr, wIdx, markAttr, optionSel, searchSel) => {
       const w = document.querySelector("[" + widgetMarkAttr + '="' + wIdx + '"]');
       if (!w) return { optionsPresent: false };
@@ -5232,9 +5265,65 @@ async function tryPromptSelectorPrimitive(params) {
         const label = opts[i].getAttribute("data-automation-label") || opts[i].getAttribute("aria-label") || opts[i].textContent || "";
         options.push({ oIdx: i, text: label.replace(/\\s+/g, " ").trim() });
       }
-      return { optionsPresent: true, searchable: !!searchInput, options };
+      // scopeIsDocument distinguishes a genuinely resolved (portal or inline)
+      // popup from the document-wide last-resort fallback in
+      // PROMPT_SCOPE_ROOT_EXPR — the pre-open pre-check below must NOT treat a
+      // still-unopened widget as "already open" on the strength of some OTHER
+      // widget's stale/leftover popup elsewhere in the document; only a scope
+      // that resolved to THIS widget's own inline subtree or its own
+      // aria-controls/aria-owns target counts.
+      return { optionsPresent: true, searchable: !!searchInput, options, scopeIsDocument: scope === document };
     })(${JSON.stringify(PROMPT_WIDGET_MARK_ATTR)}, ${JSON.stringify(chosen.wIdx)}, ${JSON.stringify(PROMPT_OPTION_MARK_ATTR)}, ${JSON.stringify(PROMPT_OPTION_SELECTORS)}, ${JSON.stringify(PROMPT_SEARCH_SELECTORS)})`;
-        const optionsInitial = await pollEnumerate(page, target, enumerateOptionsExpr, (r) => r?.optionsPresent === true);
+        // Pre-check (single evaluate, no polling): a PRIOR primitive call on this
+        // same unreloaded page may have already opened/drilled this exact widget's
+        // popup (a two-level cascading multiselect authored as two flow steps —
+        // category, then leaf — re-enters here for the leaf with the popup already
+        // open). Re-clicking the trigger in that case perturbs/closes the
+        // already-rendered popup instead of reading it. Skip the open-click
+        // entirely when options are already present AND resolved to THIS widget's
+        // OWN scope (not the document-wide fallback, which could otherwise credit
+        // an unrelated widget's stale/leftover popup elsewhere on the page as
+        // "already open"); a genuinely closed popup falls through to the normal
+        // open-click + poll path below unchanged.
+        const precheck = (await target.evaluate(enumerateOptionsExpr));
+        const alreadyOpen = precheck?.optionsPresent === true &&
+            (precheck.options?.length ?? 0) > 0 &&
+            precheck.scopeIsDocument !== true;
+        if (!alreadyOpen) {
+            // Phase 2 (real gesture): open the popup. These widgets' trigger requires a
+            // genuine click — a synthetic dispatchEvent does not fire its handler.
+            // Prefer the marked widget's own interactive descendant (a real form
+            // control) over the marked container itself, since the container is
+            // frequently a non-interactive layout wrapper for widget shapes whose
+            // actual trigger sits a level deeper (see PROMPT_INTERACTIVE_CONTROL_SELECTORS).
+            const containerTriggerSel = `[${PROMPT_WIDGET_MARK_ATTR}="${chosen.wIdx}"]`;
+            const innerTriggerSel = PROMPT_INTERACTIVE_CONTROL_SELECTORS.split(",")
+                .map((s) => `${containerTriggerSel} ${s}`)
+                .join(",");
+            let triggerSel = containerTriggerSel;
+            try {
+                const innerCount = await target.locator(innerTriggerSel).count();
+                if (innerCount > 0)
+                    triggerSel = innerTriggerSel;
+            }
+            catch {
+                // Fall back to the container selector.
+            }
+            try {
+                await target.locator(triggerSel).first().click();
+            }
+            catch (err) {
+                logger.info(`prompt-selector primitive: trigger click failed for ${optLabel}: ${(0, errors_1.toErrorMessage)(err)}; falling through`);
+                return null;
+            }
+            await page.waitForTimeout(PROMPT_SELECTOR_SETTLE_MS);
+        }
+        else {
+            logger.info(`prompt-selector primitive: popup for ${optLabel} already open with rendered options; skipping trigger click`);
+        }
+        const optionsInitial = alreadyOpen
+            ? precheck
+            : await pollEnumerate(page, target, enumerateOptionsExpr, (r) => r?.optionsPresent === true);
         if (!optionsInitial?.optionsPresent) {
             logger.info(`prompt-selector primitive: popup for ${optLabel} did not render options; falling through`);
             return null;
@@ -5257,6 +5346,7 @@ async function tryPromptSelectorPrimitive(params) {
                 questionLabel,
                 chosen,
                 optionsResult,
+                enumerateOptionsExpr,
             });
         }
         try {
@@ -5290,6 +5380,7 @@ async function tryPromptSelectorPrimitive(params) {
             questionLabel,
             chosen,
             optionsResult: optionsFiltered,
+            enumerateOptionsExpr,
         });
     }
     catch (err) {
@@ -5306,82 +5397,115 @@ async function tryPromptSelectorPrimitive(params) {
  * by the value union, or its invalid marker cleared). Split out from the main
  * function because both the static and searchable-then-filtered branches need
  * the identical match/click/verify sequence.
+ *
+ * Bounded (see {@link PROMPT_SELECTOR_MAX_DRILL_DEPTH}) category->leaf drill:
+ * when a click's readback fails, that is ambiguous between a genuine
+ * non-commit and a category click that swapped the popup to a deeper level
+ * (a two-level cascading multiselect authored as a SINGLE step naming only
+ * the leaf). Re-enumerating after a failed readback and comparing the
+ * option set disambiguates the two: an unchanged set is a real failure and
+ * must still fall through to the cascade; a changed set means the drill
+ * fired, so re-match/re-click continues at the new level instead of
+ * abandoning the primitive.
  */
 async function commitPromptOption(params) {
-    const { page, target, logger, anthropic, captureFn, optLabel, option, questionLabel, chosen, optionsResult, } = params;
+    const { page, target, logger, anthropic, captureFn, optLabel, option, questionLabel, chosen, enumerateOptionsExpr, } = params;
     const norm = (s) => s.replace(/\s+/g, " ").trim().toLowerCase();
     const wantOpt = norm(option);
-    const options = optionsResult.options ?? [];
-    const detMatch = options.find((o) => norm(o.text) === wantOpt) ?? null;
-    if (detMatch === null && (anthropic === null || options.length === 0)) {
-        logger.info(`prompt-selector primitive: no option match for ${optLabel}${anthropic === null ? " (no LLM client)" : ""}; falling through to cascade`);
-        return null;
-    }
-    const verdict = detMatch === null
-        ? await (0, select_option_1.judgeSelectOptionWithLLM)({
-            client: anthropic,
-            input: {
-                questionLabel,
-                desiredHint: option,
-                candidates: [{ label: chosen.label || null, options: options.map((o) => o.text) }],
-            },
-            captureFn,
-        })
-        : null;
-    if (detMatch === null &&
-        (!verdict || verdict.selectIndex === null || verdict.optionIndex === null)) {
-        logger.info(`prompt-selector primitive: LLM found no matching option for ${optLabel}${verdict ? ` (${verdict.reason})` : ""}; falling through to cascade`);
-        return null;
-    }
-    const chosenOption = detMatch ??
-        (verdict && verdict.optionIndex !== null ? (options[verdict.optionIndex] ?? null) : null);
-    if (!chosenOption) {
-        logger.info(`prompt-selector primitive: option match out of range for ${optLabel}; falling through`);
-        return null;
-    }
-    const matchReason = detMatch ? "deterministic" : `LLM: ${(verdict?.reason ?? "").slice(0, 60)}`;
-    const optionSel = `[${PROMPT_OPTION_MARK_ATTR}="${chosenOption.oIdx}"]`;
-    try {
-        await target.locator(optionSel).first().click();
-    }
-    catch (err) {
-        logger.info(`prompt-selector primitive: option click failed for ${optLabel}: ${(0, errors_1.toErrorMessage)(err)}; falling through`);
-        return null;
-    }
-    await page.waitForTimeout(PROMPT_SELECTOR_SETTLE_MS);
-    const readbackExpr = `((wIdx, markAttr, valueSel, emptyRxSrc, emptyRxFlags, wantText) => {
-    const isInvalid = ${INVALID_MARKER_EL_EXPR};
-    const norm = (s) => (s || "").replace(/\\s+/g, " ").trim().toLowerCase();
-    const buttonValue = ${BUTTON_VALUE_EXPR};
-    const emptyRx = new RegExp(emptyRxSrc, emptyRxFlags);
-    const w = document.querySelector("[" + markAttr + '="' + wIdx + '"]');
-    if (!w) return { ok: false, id: "" };
-    // Value via the union: aria-activedescendant, own input value, a <button>'s
-    // own value text (popup-pollution-safe, see BUTTON_VALUE_EXPR), or a
-    // selection-label node (empty-state phrase treated as no value).
-    const adid = w.getAttribute && w.getAttribute("aria-activedescendant");
-    const adText = adid && document.getElementById(adid) ? norm(document.getElementById(adid).textContent) : "";
-    const own = w.tagName === "INPUT" ? norm(w.value || "") : w.tagName === "BUTTON" ? norm(buttonValue(w)) : "";
-    const lbl = w.matches(valueSel) ? w : w.querySelector(valueSel);
-    const lblRaw = lbl ? (lbl.textContent || "") : "";
-    const lblText = lblRaw.trim() && !emptyRx.test(lblRaw.trim()) ? norm(lblRaw) : "";
-    const text = adText || own || lblText;
-    const textMatches = wantText ? text.includes(wantText) : text !== "";
-    let node = w;
-    let stillInvalid = false;
-    for (let d = 0; d < 6 && node; d++) {
-      if (node.getAttribute && isInvalid(node)) { stillInvalid = true; break; }
-      node = node.parentElement;
-    }
-    return { ok: textMatches || !stillInvalid, id: w.id || "" };
-  })(${JSON.stringify(chosen.wIdx)}, ${JSON.stringify(PROMPT_WIDGET_MARK_ATTR)}, ${JSON.stringify(PROMPT_VALUE_SELECTORS)}, ${JSON.stringify(PROMPT_EMPTY_VALUE_RX_SRC)}, ${JSON.stringify(PROMPT_EMPTY_VALUE_RX_FLAGS)}, ${JSON.stringify(norm(chosenOption.text))})`;
-    const readback = (await target.evaluate(readbackExpr).catch(() => ({ ok: false, id: "" })));
-    if (!readback?.ok) {
-        logger.info(`prompt-selector primitive: selection for ${optLabel} did not commit; falling through to cascade`);
-        return null;
+    const optionSetKey = (opts) => opts
+        .map((o) => norm(o.text))
+        .sort()
+        .join("
");
+    let optionsResult = params.optionsResult;
+    for (let depth = 0; depth <= PROMPT_SELECTOR_MAX_DRILL_DEPTH; depth++) {
+        const options = optionsResult.options ?? [];
+        const detMatch = options.find((o) => norm(o.text) === wantOpt) ?? null;
+        if (detMatch === null && (anthropic === null || options.length === 0)) {
+            logger.info(`prompt-selector primitive: no option match for ${optLabel}${anthropic === null ? " (no LLM client)" : ""}; falling through to cascade`);
+            return null;
+        }
+        const verdict = detMatch === null
+            ? await (0, select_option_1.judgeSelectOptionWithLLM)({
+                client: anthropic,
+                input: {
+                    questionLabel,
+                    desiredHint: option,
+                    candidates: [{ label: chosen.label || null, options: options.map((o) => o.text) }],
+                },
+                captureFn,
+            })
+            : null;
+        if (detMatch === null &&
+            (!verdict || verdict.selectIndex === null || verdict.optionIndex === null)) {
+            logger.info(`prompt-selector primitive: LLM found no matching option for ${optLabel}${verdict ? ` (${verdict.reason})` : ""}; falling through to cascade`);
+            return null;
+        }
+        const chosenOption = detMatch ??
+            (verdict && verdict.optionIndex !== null ? (options[verdict.optionIndex] ?? null) : null);
+        if (!chosenOption) {
+            logger.info(`prompt-selector primitive: option match out of range for ${optLabel}; falling through`);
+            return null;
+        }
+        const matchReason = detMatch ? "deterministic" : `LLM: ${(verdict?.reason ?? "").slice(0, 60)}`;
+        const optionSel = `[${PROMPT_OPTION_MARK_ATTR}="${chosenOption.oIdx}"]`;
+        try {
+            await target.locator(optionSel).first().click();
+        }
+        catch (err) {
+            logger.info(`prompt-selector primitive: option click failed for ${optLabel}: ${(0, errors_1.toErrorMessage)(err)}; falling through`);
+            return null;
+        }
+        await page.waitForTimeout(PROMPT_SELECTOR_SETTLE_MS);
+        const readbackExpr = `((wIdx, markAttr, valueSel, emptyRxSrc, emptyRxFlags, wantText) => {
+      const isInvalid = ${INVALID_MARKER_EL_EXPR};
+      const norm = (s) => (s || "").replace(/\\s+/g, " ").trim().toLowerCase();
+      const buttonValue = ${BUTTON_VALUE_EXPR};
+      const emptyRx = new RegExp(emptyRxSrc, emptyRxFlags);
+      const w = document.querySelector("[" + markAttr + '="' + wIdx + '"]');
+      if (!w) return { ok: false, id: "" };
+      // Value via the union: aria-activedescendant, own input value, a <button>'s
+      // own value text (popup-pollution-safe, see BUTTON_VALUE_EXPR), or a
+      // selection-label node (empty-state phrase treated as no value).
+      const adid = w.getAttribute && w.getAttribute("aria-activedescendant");
+      const adText = adid && document.getElementById(adid) ? norm(document.getElementById(adid).textContent) : "";
+      const own = w.tagName === "INPUT" ? norm(w.value || "") : w.tagName === "BUTTON" ? norm(buttonValue(w)) : "";
+      const lbl = w.matches(valueSel) ? w : w.querySelector(valueSel);
+      const lblRaw = lbl ? (lbl.textContent || "") : "";
+      const lblText = lblRaw.trim() && !emptyRx.test(lblRaw.trim()) ? norm(lblRaw) : "";
+      const text = adText || own || lblText;
+      const textMatches = wantText ? text.includes(wantText) : text !== "";
+      let node = w;
+      let stillInvalid = false;
+      for (let d = 0; d < 6 && node; d++) {
+        if (node.getAttribute && isInvalid(node)) { stillInvalid = true; break; }
+        node = node.parentElement;
+      }
+      return { ok: textMatches || !stillInvalid, id: w.id || "" };
+    })(${JSON.stringify(chosen.wIdx)}, ${JSON.stringify(PROMPT_WIDGET_MARK_ATTR)}, ${JSON.stringify(PROMPT_VALUE_SELECTORS)}, ${JSON.stringify(PROMPT_EMPTY_VALUE_RX_SRC)}, ${JSON.stringify(PROMPT_EMPTY_VALUE_RX_FLAGS)}, ${JSON.stringify(norm(chosenOption.text))})`;
+        const readback = (await target.evaluate(readbackExpr).catch(() => ({ ok: false, id: "" })));
+        if (readback?.ok) {
+            logger.info(`prompt-selector primitive: selected "${chosenOption.text.slice(0, 40)}" for ${optLabel} (${matchReason})`);
+            return readback.id;
+        }
+        if (depth === PROMPT_SELECTOR_MAX_DRILL_DEPTH) {
+            logger.info(`prompt-selector primitive: selection for ${optLabel} did not commit; falling through to cascade`);
+            return null;
+        }
+        // Readback failed — disambiguate a genuine non-commit from a
+        // category->leaf drill by re-enumerating and comparing the option set.
+        const reEnumerated = (await target
+            .evaluate(enumerateOptionsExpr)
+            .catch(() => ({ optionsPresent: false })));
+        const newOptions = reEnumerated?.optionsPresent ? (reEnumerated.options ?? []) : [];
+        const drilled = newOptions.length > 0 && optionSetKey(newOptions) !== optionSetKey(options);
+        if (!drilled) {
+            logger.info(`prompt-selector primitive: selection for ${optLabel} did not commit; falling through to cascade`);
+            return null;
+        }
+        logger.info(`prompt-selector primitive: click for ${optLabel} drilled the popup to a new option set; re-matching at the new level`);
+        optionsResult = { options: newOptions };
     }
-    logger.info(`prompt-selector primitive: selected "${chosenOption.text.slice(0, 40)}" for ${optLabel} (${matchReason})`);
-    return readback.id;
+    return null;
 }
 /**
  * Guard for the optional-step fast-skip: is there a REQUIRED, still-empty (or
@@ -8601,6 +8725,24 @@ async function runHealingFlow(deps) {
             if (maxFlowMs !== undefined && Date.now() - start > maxFlowMs) {
                 throw new errors_2.StepVerificationError(`${formatStepPrefix(i, () => steps.length)} flow exceeded its maxFlowMs budget (${maxFlowMs}ms)`, "flow-timeout");
             }
+            // Liveness gate: a closed/crashed Stagehand session (e.g. the
+            // shutdown-supervisor force-releasing mid-flow) makes `page.url()`
+            // throw synchronously — the one call every Page implementation
+            // answers without touching the DOM. Everything downstream (observe/
+            // act probes) treats a thrown error as "page has no candidates right
+            // now" and, for an optional step, quietly skips it — so without this
+            // check the loop runs to completion and `runHealingFlow` resolves as
+            // if the flow finished, even though the session died partway through.
+            // Checking here, before any step-specific handling, means a dead
+            // session is reported as a `SessionTimeoutError` distinct from a
+            // legitimately-absent optional step, and the flow's own step count
+            // never quietly reaches `steps.length` past the point of death.
+            try {
+                page.url();
+            }
+            catch (err) {
+                throw new errors_2.SessionTimeoutError(`${formatStepPrefix(i, () => steps.length)} session appears closed/dead (page.url() threw: ${(0, errors_1.toErrorMessage)(err)}) — aborting after ${i} of ${steps.length} steps completed`);
+            }
             lastStepIndex = i;
             // Resolved fresh per step (not cached across the run) so a cross-origin
             // iframe that attaches mid-flow (e.g. after an "Apply" click reveals a