@trusty-squire/mcp 1.1.8 → 1.1.9-rc.2

package/dist/bot/provision-session.js

@@ -27,7 +27,7 @@ import { pickVerificationLink } from "./email-verification.js";
 import { detectActiveProviderSessions, ensureOAuthSession } from "./google-login.js";
 import { loggedInEmail } from "./login-state.js";
 import { loginSessionGuidance } from "./skill-hint.js";
-import { checkSuccessSignal, bindKnownEmailTemplate, bindRecipePostcondition, bindRecipeTarget, bindRecipeValue, cssEscapeRecipeValue, fillTemplate, hasRecipeTargetCandidate, isSingleUseUrl, knownRecipeInputValue, operatorRecipeDomain, resolveRecipeFieldTarget, resolveRecipeRepairTarget, resolveRecipeTarget, verifyFilledFieldValues, writeRecipe, } from "./operator-recipe.js";
+import { checkSuccessSignal, bindKnownEmailTemplate, bindRecipePostcondition, bindRecipeTarget, bindRecipeValue, cssEscapeRecipeValue, fillTemplate, hasRecipeTargetCandidate, isSingleUseUrl, isCheckoutShapeKey, isSameRecipeDomain, knownRecipeInputValue, localeStableFieldRole, operatorRecipeDomain, checkoutFieldSetSignature, checkoutShapeKey, resolveRecipeFieldTarget, resolveRecipeRepairTarget, resolveRecipeTarget, verifyFilledFieldValues, writeRecipe, } from "./operator-recipe.js";
 import { captureOnboardingRound, currentRunId, resetCaptureChain, resolveCaptureDir, } from "./onboarding-capture.js";
 import { promoteToSkill, pickRowDisambiguator, pickStableDomHint, pickHrefHint, } from "./promote-to-skill.js";
 import { serviceSlugFromHost } from "@trusty-squire/skill-schema";
@@ -430,6 +430,49 @@ export class AmbiguousProvisionTargetError extends Error {
         this.candidates = candidates;
     }
 }
+// A `type` into an autocomplete field (Google-Places-style address picker,
+// react-select/cmdk/Radix combobox) opened a suggestion popup, but the typed
+// text didn't resolve to exactly one option — same "N candidates matched,
+// stop and ask, never guess" shape as AmbiguousProvisionTargetError. Zero
+// candidates and >1 candidates are both a stop, never a confident wrong
+// commit (see matchAutocompleteSuggestions).
+export class AutocompleteCommitRequiredError extends Error {
+    typedText;
+    candidates;
+    code = "autocomplete_commit_required";
+    constructor(typedText, candidates) {
+        super(candidates.length === 0
+            ? `autocomplete_commit_required: typing "${typedText}" opened a suggestion list but no ` +
+                `visible option started with the typed text. Retry with text that matches a suggestion, ` +
+                `or issue an explicit select/click on the option you want.`
+            : `autocomplete_commit_required: typing "${typedText}" matched ${candidates.length} ` +
+                `suggestions, not one. Narrow the typed text or issue an explicit select/click: ` +
+                `${candidates.slice(0, 8).join(", ")}`);
+        this.typedText = typedText;
+        this.candidates = candidates;
+    }
+}
+function normalizeAutocompleteText(value) {
+    return value.toLowerCase().replace(/\s+/g, " ").trim();
+}
+// Match-or-stop rule for 3.1 — pure and unit-testable without a browser. A
+// suggestion is a candidate iff the typed text (normalized) is a prefix of
+// the option's normalized text (e.g. "350 5th Ave" → "350 5th Ave, New York,
+// NY 10118, USA"). Deliberately NOT a bare substring match anywhere in the
+// string — too loose, invites the label-swap-class wrong-fill the field-role
+// guard (PR #447) exists to prevent. Returns the indices of matching options;
+// the caller commits only when there is exactly one.
+export function matchAutocompleteSuggestions(typedText, optionTexts) {
+    const typed = normalizeAutocompleteText(typedText);
+    if (typed.length === 0)
+        return [];
+    const indices = [];
+    optionTexts.forEach((text, index) => {
+        if (normalizeAutocompleteText(text).startsWith(typed))
+            indices.push(index);
+    });
+    return indices;
+}
 function elementTargetKeys(el) {
     return [el.screenPath ?? null, el.testId ?? null, elementRef(el)].flatMap((s) => {
         const v = (s ?? "").replace(/\s+/g, " ").trim();
@@ -1209,6 +1252,66 @@ export async function startProvisionSession(opts) {
         throw err;
     }
 }
+/** Start a normal guarded session on a caller-owned harness page. */
+export async function startHarnessProvisionSession(opts) {
+    const id = randomUUID();
+    if (starting || inFlight) {
+        throw new Error("operate_start refused: another operator session is already in flight");
+    }
+    if (opts.requireLiveIdentity === true) {
+        throw new Error("harness sessions cannot request live identity");
+    }
+    const targetHost = registrableHost(opts.serviceUrl);
+    const allowedHosts = [
+        ...(targetHost === null ? [] : [targetHost]),
+        ...(opts.extraAllowedHosts ?? []),
+    ]
+        .filter((host, index, hosts) => hosts.indexOf(host) === index)
+        .map((host) => ({
+        host,
+        source: "start",
+    }));
+    const session = {
+        id,
+        browser: opts.browser,
+        allowedHosts,
+        generation: 0,
+        secretSlots: new Map(),
+        sealedFieldKeys: new Set(),
+        lastElements: [],
+        prevObserve: null,
+        observeSnapshotFile: null,
+        actionTrace: [],
+        recordedValues: [],
+        committedSelectValues: new Map(),
+        captureRounds: [],
+        usedLocatorFallback: false,
+        recipeRejectionReason: null,
+        replayState: null,
+        startedAt: Date.now(),
+        hintServed: opts.hint !== undefined,
+        startUrl: opts.serviceUrl,
+        consentInboxRead: false,
+        userEmail: null,
+        ...(opts.api === undefined ? {} : { api: opts.api }),
+    };
+    sessions.set(id, session);
+    inFlight = true;
+    try {
+        audit(id, "start_harness", {
+            service_url: opts.serviceUrl,
+            allowed_hosts: hostStrings(session),
+        });
+        await opts.browser.goto(opts.serviceUrl);
+        return { ...(await observeSession(session)), hint: opts.hint ?? "" };
+    }
+    catch (error) {
+        sessions.delete(id);
+        await opts.browser.close().catch(() => undefined);
+        inFlight = false;
+        throw error;
+    }
+}
 export async function observe(sessionId, detail = "compact") {
     const session = sessionForCall(sessionId);
     if (session === undefined)
@@ -2080,7 +2183,96 @@ export async function act(sessionId, action, detail = "compact") {
                 await browser.clickViaJs(el.selector);
             else if (action.kind === "type") {
                 session.committedSelectValues.delete(el.selector);
-                await browser.type(el.selector, action.text);
+                if (!isAutocompleteScopedTypeField(action.provenance, el)) {
+                    // Free text only — e.g. a site-search/catalog-search box, which
+                    // can legitimately open its own suggestion listbox too. 3.1 only
+                    // applies to a form/recipe field where a committed value is
+                    // actually required; forcing every incidental popup into
+                    // commit-or-stop would break ordinary search typing.
+                    await browser.type(el.selector, action.text);
+                }
+                else {
+                    // 3.1 — a Google-Places-style address field or a react-select/cmdk/
+                    // Radix combobox can open a suggestion popup as a side effect of
+                    // typing, not just of an explicit `select`. Snapshot pre-existing
+                    // popups BEFORE typing (it can open mid-keystroke), then detect what
+                    // opened afterward.
+                    await browser.markPreexistingTypeSuggestionPopups();
+                    await browser.type(el.selector, action.text);
+                    // Cleanup (clear our tracking markers, and dismiss with Escape
+                    // ONLY when a detected popup is plausibly still open) must run no
+                    // matter how this resolves — no popup, an ambiguous stop, a
+                    // failed commit, or success — mirroring selectFromCombobox's own
+                    // try/finally. Scoping the try to only the
+                    // suggestionTexts.length > 0 branch left the "preexisting"
+                    // markers set by markPreexistingTypeSuggestionPopups uncleared on
+                    // the no-popup path; markComboboxPreexistingElements only ADDS
+                    // markers, so a stale one could exclude a genuine popup from
+                    // detection on a LATER type/select into the same element. Escape
+                    // fires on the ambiguous-stop and failed-commit paths (popup
+                    // never interacted with / click may not have registered — still
+                    // open either way) but NEVER after a confirmed commit: the widget
+                    // already closed its popup on selection, so Escape would land on
+                    // nothing and bubble to close an enclosing modal/dialog instead.
+                    let dismissPopupWithEscape = false;
+                    try {
+                        const suggestionTexts = await browser.detectTypeSuggestionPopup(el.selector);
+                        if (suggestionTexts.length > 0) {
+                            dismissPopupWithEscape = true;
+                            const candidates = matchAutocompleteSuggestions(action.text, suggestionTexts);
+                            if (candidates.length !== 1) {
+                                // Pass the MATCHED subset, not the full popup — passing every
+                                // suggestion made candidates.length effectively the popup
+                                // size (always > 0 here), so the constructor's zero-match
+                                // branch was dead code and the multi-match message reported
+                                // the wrong count.
+                                throw new AutocompleteCommitRequiredError(action.text, candidates.map((i) => suggestionTexts[i]));
+                            }
+                            const pickedText = suggestionTexts[candidates[0]];
+                            await browser.commitTypeSuggestion(candidates[0]);
+                            // Never trust that a click "looked right" — POSITIVELY confirm
+                            // the commit took (same hard constraint as the field-role
+                            // guard, PR #447: a miss is a stop, never a silent
+                            // pass-through). Checking only the typed-into selector's own
+                            // `.value` false-fails on react-select/cmdk-style widgets,
+                            // which clear their search input on selection and render the
+                            // committed choice in a nearby element instead —
+                            // confirmAutocompleteCommitted checks that too, bounded to the
+                            // field's own neighborhood, and returns false (never a guess)
+                            // when nothing confirms it.
+                            const committed = await browser.confirmAutocompleteCommitted(el.selector, pickedText);
+                            if (!committed) {
+                                throw new Error(`autocomplete commit for "${action.text}" did not take — nothing on the page ` +
+                                    `confirms the field now holds "${pickedText}" after selecting it.`);
+                            }
+                            dismissPopupWithEscape = false;
+                            // Rewrite the completed action to the field's LIVE post-commit
+                            // value (not the raw typed draft) before it reaches
+                            // recordTrace/recordedValues, so the recorded trace reflects
+                            // what actually ended up on the page. Recording pickedText
+                            // would diverge from the live value exactly when the commit
+                            // was confirmed via a NEARBY element (react-select/cmdk clear
+                            // their search input on selection), and the cold-path
+                            // transition attestation (attestRecordedFieldsBeforeTransition
+                            // → verifyFilledFieldValues) re-reads the live value — a
+                            // pickedText literal would flag every such commit as a
+                            // mismatch and disqualify recipe recording. Reading the same
+                            // live value here is attestation-consistent by construction.
+                            // Known limitation: after a nearby-signal-only commit the
+                            // field itself can be empty, so the recorded literal is "" —
+                            // that field won't cleanly template into a saved recipe, but
+                            // the live run is unaffected.
+                            const refreshed = await browser.extractInteractiveElements();
+                            session.lastElements = refreshed;
+                            const liveField = refreshed.find((field) => field.selector === el.selector);
+                            const liveValue = typeof liveField?.value === "string" ? liveField.value : pickedText;
+                            completedAction = { ...action, text: liveValue };
+                        }
+                    }
+                    finally {
+                        await browser.discardTypeSuggestionPopup(dismissPopupWithEscape);
+                    }
+                }
             }
             else if (action.kind === "upload") {
                 await browser.uploadFile(el.selector, action.path);
@@ -2280,6 +2472,9 @@ export function recipeTargetFor(el, inventory = [], userEmail = null) {
     const domHint = pickStableDomHint(el);
     const hrefHint = pickHrefHint(el);
     const scrub = (value) => scrubKnownEmail(value, userEmail);
+    // Locale-stable role for money-path fill safety (autocomplete > data-role >
+    // distinguishing input type). Never label text — labels flip under i18n.
+    const fieldRole = localeStableFieldRole(el);
     return {
         ...(domHint !== undefined
             ? {
@@ -2300,6 +2495,7 @@ export function recipeTargetFor(el, inventory = [], userEmail = null) {
         ...(el.visibleText !== null && el.visibleText.length > 0
             ? { visible_text: scrub(el.visibleText) }
             : {}),
+        ...(fieldRole !== null ? { field_role: fieldRole } : {}),
     };
 }
 function recordTrace(session, action, el, sensitiveSource) {
@@ -2706,6 +2902,9 @@ export async function rememberRecipe(sessionId, opts) {
     const scrubbedStartUrl = scrubKnownEmail(session.startUrl, session.userEmail);
     const trace = traceWithVerifiedProvenance(session, opts.inputs);
     const postcondition = scrubRecipePostcondition(session, opts.postcondition, opts.inputs);
+    if (opts.entry_mode !== undefined && opts.verb === undefined) {
+        throw new Error("runtime recipe entry requires a keyed verb");
+    }
     const recipe = {
         name: opts.name,
         schema_version: 1,
@@ -2715,7 +2914,9 @@ export async function rememberRecipe(sessionId, opts) {
             : {}),
         // Canonical, stable replay entry — the page the session started at, never a
         // mid-flow single-use link inferred from the trace.
-        ...(isSingleUseUrl(session.startUrl) || scrubbedStartUrl !== session.startUrl
+        ...(opts.entry_mode === "runtime_service_url" ||
+            isSingleUseUrl(session.startUrl) ||
+            scrubbedStartUrl !== session.startUrl
             ? { entry_mode: "runtime_service_url" }
             : { entry_url: session.startUrl }),
         allowed_hosts: [...new Set(egressSeedHosts(session))],
@@ -2735,13 +2936,50 @@ export async function rememberRecipe(sessionId, opts) {
         secrets: secrets.length,
         file,
     });
+    const checkoutLegFile = await rememberCheckoutLeg(session, opts.verb, trace).catch(() => null);
     return {
         file,
         name: opts.name,
         steps: recipe.trace.length,
         secrets: secrets.map((s) => s.slot),
         verified,
+        ...(checkoutLegFile !== null ? { checkout_leg_file: checkoutLegFile } : {}),
+    };
+}
+// replay-per-leg-signature — split off and save the checkout portion of a
+// just-recorded money-path trace as its OWN recipe, keyed by the checkout
+// page's live field-name-set signature instead of domain. Best-effort and
+// silent on any reason it can't produce one (non-money verb, no money field
+// captured, empty live field set) — the whole-task recipe above is already
+// saved and stands on its own either way; this only ever ADDS a second,
+// narrower, cross-domain-reusable recipe alongside it.
+async function rememberCheckoutLeg(session, verb, trace) {
+    if (verb === undefined || !MONEY_REPLAY_VERBS.has(verb))
+        return null;
+    const legStart = checkoutLegStartIndex(trace);
+    if (legStart === null)
+        return null;
+    const legTrace = trace.slice(legStart);
+    const fieldNames = await session.browser.extractCheckoutFieldNames();
+    const signature = checkoutFieldSetSignature(fieldNames);
+    if (signature === null)
+        return null;
+    const legSlots = new Set(legTrace
+        .filter((entry) => entry.action.kind === "type_secret")
+        .map((entry) => entry.action.slot)
+        .filter((slot) => slot !== undefined));
+    const checkoutRecipe = {
+        name: `checkout-leg--${signature.slice(0, 12)}`,
+        schema_version: 1,
+        goal: "Fill the checkout leg's fields",
+        verb,
+        domain: checkoutShapeKey(signature),
+        allowed_hosts: [],
+        trace: legTrace,
+        secrets: [...legSlots].map((slot) => ({ slot, stored: false })),
+        postcondition: checkoutLegPostcondition(legTrace),
     };
+    return await writeRecipe(checkoutRecipe);
 }
 // Read a single page snapshot for postcondition checking. Field VALUES are
 // reduced to lengths here so a token/secret success-signal can't leak.
@@ -2810,6 +3048,21 @@ export async function verifyActiveRecipePostcondition(sessionId, recipeName) {
     }
     return await verifyPostcondition(sessionId, state.boundPostcondition);
 }
+// replay-per-leg-signature — the checkout leg's registry/local-store key,
+// computed from the CURRENT live page. Callers use this to resolve (and,
+// on a hit, replay via replayOperatorRecipe) a checkout-leg recipe
+// independently of whatever (or whether any) whole-task recipe applies to
+// this session's domain — the mechanism that lets a checkout plan recorded
+// on one store resolve on a different, unrelated store of the same
+// checkout platform. Returns null when the live page has no field-name-set
+// to key by (nothing to resolve yet).
+export async function checkoutShapeSignatureForSession(sessionId) {
+    const session = sessionForCall(sessionId);
+    if (session === undefined)
+        throw new Error(`unknown provision session ${sessionId}`);
+    const fieldNames = await session.browser.extractCheckoutFieldNames();
+    return checkoutFieldSetSignature(fieldNames);
+}
 const MONEY_REPLAY_VERBS = new Set([
     "purchase",
     "subscribe",
@@ -2835,6 +3088,25 @@ function boundReplayTarget(action, bindings) {
     return target === null ? null : bindRecipeTarget(target, bindings, action.email_hole);
 }
 const MONEY_FIELD_TARGET = /(?:^|[\s._-])(?:address|street|line\s*[12]|city|state|province|postal|zip|country|e-?mail|phone|first\s*name|last\s*name|full\s*name|quantity|qty)(?:$|[\s._-])/i;
+// 3.1 must only engage for a form/recipe field where a committed value is
+// actually required (a checkout form field, or one the host tagged with a
+// recipe hole) — not arbitrary typing. The popup-shape detection
+// (role=listbox/menu/dialog, etc.) also matches an incidental suggestion
+// popup on an ordinary site-search/catalog-search box; without this scope,
+// typing a search query either auto-clicks a suggestion (navigating as a
+// side effect of "type") or throws, with no way to keep free text. Reuses
+// the existing MONEY_FIELD_TARGET shape check (moneyFieldName's sibling,
+// just read off the live element instead of a recorded TraceAction) rather
+// than inventing a new heuristic.
+function isAutocompleteScopedTypeField(provenance, el) {
+    if (provenance !== undefined)
+        return true;
+    const label = [el.testId, el.id, el.name, el.ariaLabel, el.labelText, el.placeholder]
+        .filter((value) => typeof value === "string" && value.length > 0)
+        .join(" ")
+        .replace(/([a-z])([A-Z])/g, "$1 $2");
+    return MONEY_FIELD_TARGET.test(label);
+}
 function moneyFieldName(action) {
     if (action.kind === "set_phone_country")
         return "phone_country";
@@ -2855,6 +3127,37 @@ function moneyFieldName(action) {
         .replace(/([a-z])([A-Z])/g, "$1 $2");
     return MONEY_FIELD_TARGET.test(label) ? label || "field" : null;
 }
+// replay-per-leg-signature — the checkout leg is whatever portion of a
+// money-path trace touches money fields (address/contact/card-adjacent —
+// the exact same classifier moneyFieldName already uses for the fill
+// guard). Reusing it here means the leg boundary needs no new heuristic
+// (no URL/path pattern-matching, no platform name): the first step the
+// existing guard already treats as a money field IS where checkout starts.
+// Returns null when the trace has no money field at all (verb classified
+// money-path but nothing was actually captured, or a non-money recipe).
+function checkoutLegStartIndex(trace) {
+    const index = trace.findIndex((entry) => moneyFieldName(entry.action) !== null);
+    return index === -1 ? null : index;
+}
+// A checkout-leg-only recipe still needs a postcondition (the schema
+// requires one), but it isn't the whole task's "order placed" signal — it
+// only covers the leg it replays. Anchor it to the LAST money field in the
+// leg holding a non-empty value, mirroring the field_text/min_value_len
+// pattern already used elsewhere (e.g. the OAuth Playground token check):
+// checks a length, never a value, so it can't leak what it proves.
+// legTrace is guaranteed non-empty and to start on a money field by
+// construction (checkoutLegStartIndex found it), so a label always exists.
+function checkoutLegPostcondition(legTrace) {
+    const lastLabel = [...legTrace]
+        .reverse()
+        .map((entry) => moneyFieldName(entry.action))
+        .find((label) => label !== null);
+    return {
+        kind: "execute_capability",
+        describe: "checkout leg fields filled and re-verified",
+        success_signal: { field_text: lastLabel, min_value_len: 1 },
+    };
+}
 function findUnprovenancedMoneyField(recipe) {
     if (recipe.verb === undefined || !MONEY_REPLAY_VERBS.has(recipe.verb))
         return null;
@@ -2915,6 +3218,20 @@ function markReplayFailure(session, reason, field) {
     session.replayState.failure = { reason, field };
     audit(session.id, "replay_field_value_guard", { ok: false, reason, field });
 }
+// replay-serve-live-domainlock — checks a replay-bound goto/allow_host
+// target against the recipe's own eTLD+1. Unlike the ordinary session goto
+// gate, recipe replay has no auth-host exceptions. Checkout-shape recipes
+// cannot execute goto/allow_host actions because they have no site domain.
+function replayTargetWithinRecipeDomain(url, recipeDomain) {
+    return isSameRecipeDomain(url, recipeDomain);
+}
+function markReplayDomainLockViolation(session, host, recipeDomain) {
+    rejectRecipeRecording(session, `replay refused: "${host}" is outside the recipe's own domain "${recipeDomain}"`);
+    if (session.replayState === null)
+        return;
+    session.replayState.paymentGuard = "failed";
+    audit(session.id, "replay_domain_lock_violation", { host, recipe_domain: recipeDomain });
+}
 function verifyReplayFieldInElements(session, expected, elements, allowCommittedSelect = false) {
     if (expected.kind === "set_phone_country" || expected.target === null) {
         return { ok: false, reason: "field_missing" };
@@ -3191,7 +3508,7 @@ async function verifyReplayFieldsAfterTransition(session, action, attestedFields
  * A miss is returned to the host with a continuation index; after the host
  * repairs that one step, calling again with `fromIndex=next_index` continues.
  */
-export async function replayOperatorRecipe(sessionId, recipe, bindings, fromIndex = 0) {
+export async function replayOperatorRecipe(sessionId, recipe, bindings, fromIndex = 0, options = {}) {
     const session = sessions.get(sessionId);
     if (session === undefined)
         throw new Error(`unknown provision session ${sessionId}`);
@@ -3204,6 +3521,33 @@ export async function replayOperatorRecipe(sessionId, recipe, bindings, fromInde
     const isMoneyPath = MONEY_REPLAY_VERBS.has(recipe.verb);
     let state;
     const humanRequired = async (reason, field) => {
+        // replay-per-leg-signature — a genuine catalog/storefront prefix exists
+        // ahead of the checkout leg (legStartIndex > 0): degrade to a leg-scoped
+        // fallback instead of aborting the whole replay. A recipe with no such
+        // prefix (legStartIndex is 0 or null — a simple/single-leg money-path
+        // recipe) has nothing narrower to fall back to, so it keeps today's
+        // behavior exactly: hard-stop at human_required.
+        if (state.moneyPath && state.legStartIndex !== null && state.legStartIndex > 0) {
+            const fromStepIndex = state.legStartIndex;
+            // Same fail-closed payment gate as human_required (markReplayFailure
+            // sets paymentGuard:"failed" and rejects recipe re-recording) — only
+            // the RETURNED status differs. Deliberately does NOT null out
+            // session.replayState: activeProvisionSession's operate_pay gate
+            // reads session.replayState.paymentGuard, so clearing it would
+            // silently reopen the payment gate instead of keeping it shut.
+            // nextIndex is left unset (not stepIndex+1), so a resume_from
+            // attempt still hits "invalid replay continuation" below — this is
+            // not a resumable fallback the way fallback_required is.
+            markReplayFailure(session, reason, field);
+            audit(sessionId, "replay_leg_fallback", { reason, field, from_step_index: fromStepIndex });
+            return {
+                status: "leg_fallback_required",
+                observation: await observe(sessionId),
+                leg: "checkout",
+                from_step_index: fromStepIndex,
+                reason: `${reason}: ${field}`,
+            };
+        }
         markReplayFailure(session, reason, field);
         return { status: "human_required", observation: await observe(sessionId), reason, field };
     };
@@ -3222,6 +3566,7 @@ export async function replayOperatorRecipe(sessionId, recipe, bindings, fromInde
             expectedFields: expected.fields,
             verifiedFields: new Set(),
             paymentGuard: isMoneyPath ? "pending" : "verified",
+            legStartIndex: isMoneyPath ? checkoutLegStartIndex(recipe.trace) : null,
         };
         session.replayState = state;
         if (expected.missing !== null)
@@ -3263,9 +3608,21 @@ export async function replayOperatorRecipe(sessionId, recipe, bindings, fromInde
             reason,
         };
     };
+    const recipeDomain = recipe.domain;
+    const domainLockViolation = async (stepIndex, host) => {
+        markReplayDomainLockViolation(session, host, recipeDomain);
+        return {
+            status: "domain_lock_violation",
+            observation: await observe(sessionId),
+            step_index: stepIndex,
+            host,
+            recipe_domain: recipeDomain,
+        };
+    };
     for (let i = fromIndex; i < recipe.trace.length; i += 1) {
         const step = recipe.trace[i];
         const recorded = step.action;
+        await options.beforeStep?.({ step_index: i, action: recorded });
         let action;
         if (recorded.kind === "extract") {
             return await fallback(step, i, "credential extraction requires host planning on the live page");
@@ -3274,6 +3631,11 @@ export async function replayOperatorRecipe(sessionId, recipe, bindings, fromInde
             return await fallback(step, i, "payment requires the existing operate_pay approval flow");
         }
         if (recorded.kind === "goto") {
+            // This lock covers explicit goto/allow_host steps only. Organic redirects
+            // and OAuth popups remain governed by the existing session navigation model.
+            if (isCheckoutShapeKey(recipeDomain)) {
+                return await domainLockViolation(i, recorded.url_template ?? "<goto>");
+            }
             if (recorded.url_template === undefined) {
                 return await fallback(step, i, "goto step has no URL");
             }
@@ -3288,12 +3650,28 @@ export async function replayOperatorRecipe(sessionId, recipe, bindings, fromInde
             if (filled.missing.length > 0) {
                 return await fallback(step, i, `missing bindings: ${filled.missing.join(", ")}`);
             }
+            if (!replayTargetWithinRecipeDomain(filled.url, recipeDomain)) {
+                let host;
+                try {
+                    host = new URL(filled.url).hostname;
+                }
+                catch {
+                    host = filled.url;
+                }
+                return await domainLockViolation(i, host);
+            }
             action = { kind: "goto", url: filled.url };
         }
         else if (recorded.kind === "allow_host") {
+            if (isCheckoutShapeKey(recipeDomain)) {
+                return await domainLockViolation(i, recorded.host ?? "<allow_host>");
+            }
             if (recorded.host === undefined) {
                 return await fallback(step, i, "allow_host step has no host");
             }
+            if (!replayTargetWithinRecipeDomain(`https://${recorded.host}`, recipeDomain)) {
+                return await domainLockViolation(i, recorded.host);
+            }
             action = { kind: "allow_host", host: recorded.host };
         }
         else if (recorded.kind === "press") {
@@ -3399,6 +3777,7 @@ export async function replayOperatorRecipe(sessionId, recipe, bindings, fromInde
             if (!transitionAttestation.ok) {
                 return await humanRequired(transitionAttestation.reason, transitionAttestation.field);
             }
+            await options.beforeAction?.({ step_index: i, action });
             await act(sessionId, action, "none");
             replayed += 1;
             const expected = state.expectedFields.get(i);