@trusty-squire/mcp 0.9.19-rc.2 → 0.9.19-rc.21

package/dist/bot/provision-session.js

@@ -15,9 +15,11 @@
 //    not navigation the agent chose, so they are never blocked.
 //  - no credential is ever read back to the agent except via the explicit
 //    `finish`/extract path; the vault stays write-only.
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { BrowserController } from "./browser.js";
 import { extractApiKeyFromText, isTruncatedCapture, pickVerificationLink } from "./agent.js";
+import { detectActiveProviderSessions, ensureOAuthSession, } from "./google-login.js";
+import { loginSessionGuidance } from "./skill-hint.js";
 import { initialExtractionState, accumulateCandidate, hasFullHit, resolveExtraction, } from "./extraction.js";
 // Identity-provider + auth-handler hosts a signup legitimately bounces
 // through. Used to widen domain-scope so an OAuth `goto` (rare) isn't blocked.
@@ -28,6 +30,20 @@ const DEFAULT_AUTH_HOSTS = [
     "login.microsoftonline.com",
     "appleid.apple.com",
 ];
+// Plain host list for the pieces that only need the names (goto gate, audit,
+// observed-hosts). The source metadata stays on the Session.
+function hostStrings(session) {
+    return session.allowedHosts.map((e) => e.host);
+}
+// Hosts that may seed credential EGRESS (where a stored key is later sent by
+// the proxy): start + auto_widen, never mid_session task scope — a wide operate
+// scope must not silently over-grant a key's egress allow-list (Codex). The
+// vault unions these with the service-default + any agent-declared egress_hosts.
+function egressSeedHosts(session) {
+    return session.allowedHosts
+        .filter((e) => e.source !== "mid_session")
+        .map((e) => e.host);
+}
 const sessions = new Map();
 const settle = (ms) => new Promise((r) => setTimeout(r, ms));
 // Audit trail (security posture): every session action emits one structured
@@ -35,10 +51,12 @@ const settle = (ms) => new Promise((r) => setTimeout(r, ms));
 // the trail greppable. No credential VALUES are ever logged — only the action
 // shape + url.
 function audit(sessionId, event, detail = {}) {
-    process.stderr.write(`${JSON.stringify({ marker: "provision-audit", session_id: sessionId, event, ...detail })}\n`);
+    process.stderr.write(`${JSON.stringify({ marker: "provision-audit", surface: "operate", session_id: sessionId, event, ...detail })}\n`);
 }
 // ── pure helpers (exported for unit tests) ──
 const norm = (s) => (s ?? "").replace(/\s+/g, " ").trim().toLowerCase();
+const PROVISION_REF_RE = /^@?g(\d+):([a-z0-9_-]+)$/i;
+const PROVISION_REF_ID_RE = /^(.+)_(\d+)$/;
 // The label a host sees + targets by. Prefer the most human, stable signal.
 export function elementRef(el) {
     const cand = el.visibleText ??
@@ -52,31 +70,131 @@ export function elementRef(el) {
     const label = (cand ?? "").replace(/\s+/g, " ").trim();
     return label.length > 0 ? label.slice(0, 80) : `${el.tag}#${el.index}`;
 }
+function shortHash(s) {
+    return createHash("sha256").update(s).digest("base64url").slice(0, 12);
+}
+export function stableElementId(el) {
+    return shortHash([
+        el.screenPath ?? "",
+        el.testId ?? "",
+        el.container ?? "",
+        el.role ?? "",
+        el.tag,
+        elementRef(el),
+        el.href ?? "",
+        el.type ?? "",
+    ].join("\u001f"));
+}
+export function provisionElementRef(el, generation, ordinal = 1) {
+    return `@g${generation}:${stableElementId(el)}_${ordinal}`;
+}
+function parseProvisionRef(target) {
+    const m = target.trim().match(PROVISION_REF_RE);
+    if (m === null)
+        return null;
+    const rawId = m[2];
+    const idMatch = rawId.match(PROVISION_REF_ID_RE);
+    return {
+        generation: Number.parseInt(m[1], 10),
+        id: idMatch !== null ? idMatch[1] : rawId,
+        ordinal: idMatch !== null ? Number.parseInt(idMatch[2], 10) : null,
+    };
+}
+export function provisionElementRefs(elements, generation) {
+    const seen = new Map();
+    const refs = new Map();
+    for (const el of elements) {
+        const id = stableElementId(el);
+        const ordinal = (seen.get(id) ?? 0) + 1;
+        seen.set(id, ordinal);
+        refs.set(el, provisionElementRef(el, generation, ordinal));
+    }
+    return refs;
+}
+export class StaleProvisionRefError extends Error {
+    refGeneration;
+    currentGeneration;
+    code = "stale_ref";
+    constructor(refGeneration, currentGeneration) {
+        super(`stale_ref: target is from observation generation ${refGeneration}, ` +
+            `but current generation is ${currentGeneration}. Call operate_observe and retry with a fresh ref.`);
+        this.refGeneration = refGeneration;
+        this.currentGeneration = currentGeneration;
+    }
+}
+export class AmbiguousProvisionTargetError extends Error {
+    target;
+    candidates;
+    code = "ambiguous_target";
+    constructor(target, candidates) {
+        super(`ambiguous_target: "${target}" matched ${candidates.length} elements. ` +
+            `Retry with one exact ref/path: ${candidates.slice(0, 8).join(", ")}`);
+        this.target = target;
+        this.candidates = candidates;
+    }
+}
+function elementTargetKeys(el) {
+    return [el.screenPath ?? null, el.testId ?? null, elementRef(el)].flatMap((s) => {
+        const v = (s ?? "").replace(/\s+/g, " ").trim();
+        return v.length > 0 ? [v] : [];
+    });
+}
 // Resolve a host-supplied target string to one live element. Matching is by
-// label text (+ role tiebreak), scored exact > startsWith > contains. Returns
-// null when nothing matches — the caller surfaces that rather than guessing.
-export function resolveTarget(elements, target) {
+// structured path, test id, or label text, scored exact > startsWith > contains.
+// Returns null when nothing matches — the caller surfaces that rather than
+// guessing.
+export function resolveTarget(elements, target, currentGeneration) {
+    const parsedRef = parseProvisionRef(target);
+    if (parsedRef !== null) {
+        if (currentGeneration !== undefined && parsedRef.generation !== currentGeneration) {
+            throw new StaleProvisionRefError(parsedRef.generation, currentGeneration);
+        }
+        const matches = elements.filter((el) => stableElementId(el) === parsedRef.id);
+        if (parsedRef.ordinal !== null) {
+            const match = matches[parsedRef.ordinal - 1];
+            return match ?? null;
+        }
+        if (matches.length === 1)
+            return matches[0];
+        if (matches.length > 1) {
+            throw new AmbiguousProvisionTargetError(target, matches.map((el) => `${el.screenPath ?? elementRef(el)} (${elementRef(el)})`));
+        }
+        return null;
+    }
     const want = norm(target);
     if (want.length === 0)
         return null;
     let best = null;
+    let tied = [];
     for (const el of elements) {
-        const label = norm(elementRef(el));
-        let score = 0;
-        if (label === want)
-            score = 100;
-        else if (label.startsWith(want))
-            score = 70;
-        else if (label.includes(want))
-            score = 50;
-        else if (want.includes(label) && label.length >= 2)
-            score = 30;
-        if (score === 0)
-            continue;
-        // Prefer shorter labels at equal score (a more specific match).
-        const adjusted = score - label.length * 0.01;
-        if (best === null || adjusted > best.score)
-            best = { el, score: adjusted };
+        for (const [i, raw] of elementTargetKeys(el).entries()) {
+            const label = norm(raw);
+            let score = 0;
+            const exact = i === 0 ? 120 : i === 1 ? 110 : 100;
+            if (label === want)
+                score = exact;
+            else if (label.startsWith(want))
+                score = 70;
+            else if (label.includes(want))
+                score = 50;
+            else if (want.includes(label) && label.length >= 2)
+                score = 30;
+            if (score === 0)
+                continue;
+            // Prefer shorter labels at equal score (a more specific match).
+            const adjusted = score - label.length * 0.01;
+            if (best === null || adjusted > best.score) {
+                best = { el, score: adjusted };
+                tied = [el];
+            }
+            else if (Math.abs(adjusted - best.score) < 0.000001) {
+                if (!tied.includes(el))
+                    tied.push(el);
+            }
+        }
+    }
+    if (best !== null && tied.length > 1) {
+        throw new AmbiguousProvisionTargetError(target, tied.map((el) => `${el.screenPath ?? elementRef(el)} (${elementRef(el)})`));
     }
     return best?.el ?? null;
 }
@@ -100,6 +218,290 @@ export function hostAllowed(url, allowedHosts) {
         return true;
     return false;
 }
+// A two-label public suffix we must never let a single allow_host widen to —
+// adding "co.uk" would green-light every *.co.uk. Small curated set (the ones
+// the operator surface realistically touches); not a full PSL.
+const TWO_LABEL_PUBLIC_SUFFIXES = new Set([
+    "co.uk", "org.uk", "gov.uk", "ac.uk", "com.au", "net.au", "org.au",
+    "co.jp", "co.nz", "co.in", "com.br", "co.za", "com.cn",
+    "github.io", "web.app", "firebaseapp.com", "pages.dev", "workers.dev",
+    "vercel.app", "netlify.app", "herokuapp.com",
+]);
+// Validate an agent-declared allow_host host. Returns the normalized bare
+// hostname or an error string. Hardened (Codex): reject wildcards, ports,
+// schemes/paths, IDNA/punycode + non-ASCII (lookalike-spoof defense), IPv4/IPv6
+// literals, localhost/private hosts, bare TLDs, and two-label public suffixes.
+// This matters more now that type_secret can enter a secret on these hosts.
+export function validateAllowHost(raw) {
+    const v = raw.trim().toLowerCase();
+    if (v.length === 0 || v.length > 253)
+        return { error: "host empty or too long" };
+    if (/[/:@?#*\s]/.test(v))
+        return { error: "host must be a bare hostname (no scheme, port, path, wildcard, or whitespace)" };
+    if (/[^a-z0-9.-]/.test(v))
+        return { error: "host has non-ASCII or invalid characters (punycode/unicode spoofing rejected)" };
+    if (v.includes("xn--"))
+        return { error: "punycode (xn--) hosts rejected — homograph-spoof risk" };
+    if (v.startsWith(".") || v.endsWith(".") || v.includes(".."))
+        return { error: "malformed host (leading/trailing/double dot)" };
+    if (v === "localhost" || v.endsWith(".localhost"))
+        return { error: "localhost is not an allowable cross-host" };
+    // IPv4 literal / dotted-quad — reject (egress + transfer must be by name).
+    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(v))
+        return { error: "IP-address hosts are not allowed (declare a hostname)" };
+    // IPv6 would contain ':' — already rejected by the ':' check above.
+    const labels = v.split(".");
+    if (labels.length < 2)
+        return { error: "bare TLD / single-label host not allowed" };
+    if (labels.some((l) => l.length === 0 || l.length > 63))
+        return { error: "invalid host label length" };
+    if (TWO_LABEL_PUBLIC_SUFFIXES.has(v))
+        return { error: `"${v}" is a public suffix — widening to it would allow every subdomain` };
+    return { host: v };
+}
+function visibleModeMarkers(pageText) {
+    const text = pageText.replace(/\s+/g, " ").trim();
+    const markers = [];
+    if (/\b(?:test|sandbox)\s+(?:mode|usage|environment|workspace)\b/i.test(text) ||
+        /\b(?:mode|environment|workspace)\s*[:=-]?\s*(?:test|sandbox)\b/i.test(text)) {
+        markers.push("test/sandbox mode");
+    }
+    if (/\b(?:live|production)\s+mode\b/i.test(text) ||
+        /\b(?:mode|environment|workspace)\s*[:=-]?\s*(?:live|production)\b/i.test(text)) {
+        markers.push("live/production mode");
+    }
+    return markers;
+}
+function appSurfaceMarkers(pageText) {
+    const text = pageText.replace(/\s+/g, " ").trim();
+    const markers = [];
+    const defs = [
+        ["dashboard", /\bdashboard\b/i],
+        ["products", /\bproducts?\b/i],
+        ["customers", /\bcustomers?\b/i],
+        ["payments", /\bpayments?\b/i],
+        ["developers", /\bdevelopers?\b/i],
+        ["api keys", /\bapi\s+keys?\b/i],
+        ["settings", /\bsettings\b/i],
+        ["workspace", /\bworkspace\b/i],
+        ["project", /\bproject\b/i],
+        ["billing", /\bbilling\b/i],
+        ["usage", /\busage\b/i],
+        ["team", /\bteam\b/i],
+    ];
+    for (const [name, re] of defs) {
+        if (re.test(text))
+            markers.push(name);
+    }
+    for (const mode of visibleModeMarkers(text))
+        markers.push(mode);
+    return [...new Set(markers)].slice(0, 8);
+}
+function authenticatedAppSurfaceMarkers(pageText) {
+    const markers = appSurfaceMarkers(pageText);
+    const modeMarkers = visibleModeMarkers(pageText);
+    if (modeMarkers.length > 0)
+        return markers;
+    return markers.length >= 2 ? markers : [];
+}
+function hasAccountSetupOverlay(pageText) {
+    const text = pageText.replace(/\s+/g, " ").trim();
+    return (/\b(?:finish|complete|set up|setup)\s+(?:creating\s+|setting\s+up\s+)?(?:your\s+)?(?:account|profile|organization|workspace|business)\b/i.test(text) ||
+        /\bcreate\s+(?:your\s+)?account\b/i.test(text) ||
+        /\btell us about (?:yourself|your business|your organization|your company)\b/i.test(text));
+}
+// An onboarding / org-or-workspace creation form that GATES the keys page. These
+// are NOT walls — the agent should fill the required fields with sensible
+// inferred values and submit to proceed. Broader than hasAccountSetupOverlay
+// (it also catches "create organization / you aren't part of an org yet").
+export function isOnboardingOrOrgForm(pageText) {
+    const text = pageText.replace(/\s+/g, " ").trim();
+    if (hasAccountSetupOverlay(text))
+        return true;
+    return (/\byou\s+(?:aren'?t|are not|do not|don'?t)\s+(?:part of|belong to|have)\b.*\borgani[sz]ation\b/i.test(text) ||
+        /\bcreate\s+(?:a\s+|your\s+|an\s+|new\s+)?(?:organi[sz]ation|org|workspace|team|project|company)\b/i.test(text) ||
+        /\bname\s+(?:your\s+)?(?:organi[sz]ation|workspace|team|project|company)\b/i.test(text) ||
+        /\b(?:what'?s|what is)\s+your\s+name\b/i.test(text) ||
+        /\bget\s+started\b.*\b(?:name|organi[sz]ation|workspace|team)\b/i.test(text));
+}
+// A "copy your key NOW — it won't be shown again" one-time reveal (Luma, many
+// console secrets). The value is on screen but vanishes on dismiss/navigate, so
+// the agent must extract it immediately (and name it with secret_label), not
+// click away first.
+export function hasOneTimeSecretModal(pageText) {
+    const text = pageText.replace(/\s+/g, " ").trim();
+    return (/\b(?:won'?t|will not|can'?t|cannot|never)\b[\s\w]{0,30}?\b(?:shown|displayed|see|view|retriev\w*|access\w*)\b[\s\w]{0,20}?\bagain\b/i.test(text) ||
+        /\b(?:only|last)\s+time\b.*\b(?:see|view|copy|shown)\b/i.test(text) ||
+        /\b(?:copy|save|store)\s+(?:and\s+save\s+)?(?:your\s+|this\s+|the\s+)?(?:secret|api\s*key|key|token|credential)\b.*\b(?:now|securely|somewhere|before)\b/i.test(text) ||
+        /\bmake\s+sure\s+to\s+(?:copy|save|store)\b/i.test(text));
+}
+function isAccountSetupActionTarget(target) {
+    return /\b(?:create|finish|complete|set up|setup)\s+(?:your\s+)?(?:account|profile|organization|workspace|business)\b/i.test(target);
+}
+function isBillingObjectActionTarget(target) {
+    return (/\b(create|save|add|finish)\b/i.test(target) &&
+        /\b(product|price|pricing|subscription|billing|payment|invoice|checkout)\b/i.test(target));
+}
+export function provisionPerceptionGuidance(pageText) {
+    const appMarkers = authenticatedAppSurfaceMarkers(pageText);
+    const modeMarkers = visibleModeMarkers(pageText);
+    const setupOverlay = hasAccountSetupOverlay(pageText);
+    const parts = [];
+    // One-time secret reveal — extract NOW; it vanishes if you navigate away.
+    if (hasOneTimeSecretModal(pageText)) {
+        parts.push("One-time secret: the key/secret is shown HERE and will NOT be shown again. " +
+            "Extract it immediately with operate_extract (use secret_label to pick the " +
+            "right field if several values are shown, and into_slot/store to capture it) " +
+            "BEFORE clicking anything that could dismiss this modal or navigate away.");
+    }
+    // Onboarding / org-creation form — fill it, don't treat it as a wall.
+    if (isOnboardingOrOrgForm(pageText)) {
+        parts.push("Onboarding/setup form: this is NOT a wall and NOT a failure. It gates the " +
+            "keys/dashboard behind a setup step. Fill the required fields with sensible " +
+            "inferred values (your name; an organization/workspace/team name such as your " +
+            "name or 'Personal'; pick the smallest/free plan) and submit to continue. Do " +
+            "not stop or report a wall — drive through it to reach the keys page.");
+    }
+    if (modeMarkers.length > 0) {
+        parts.push(`Mode marker visible: ${modeMarkers.join(", ")}.`);
+    }
+    else if (appMarkers.length > 0 || setupOverlay) {
+        parts.push("No test/sandbox/live mode marker is visible. For mode-sensitive tasks, do not create or save objects until the required mode is visible.");
+    }
+    if (setupOverlay && appMarkers.length > 0) {
+        parts.push(`Screen perception: account/setup overlay text is present while authenticated app markers are also visible (${appMarkers.join(", ")}). This often means a foreground onboarding modal is blocking an already-authenticated app, not that OAuth failed. Do not restart OAuth or navigate to login solely because the overlay says create/finish account; either satisfy the minimal required setup once, or use same-origin app navigation/direct dashboard URLs toward the user's goal.`);
+    }
+    else if (appMarkers.length > 0) {
+        parts.push(`Screen perception: authenticated app markers are visible (${appMarkers.join(", ")}). Prefer app navigation over restarting OAuth unless the current URL is clearly an identity-provider login page.`);
+    }
+    return parts.length > 0 ? parts.join(" ") : undefined;
+}
+export function shouldBlockUnsafeProvisionAction(pageText, action) {
+    if (!("target" in action))
+        return null;
+    const appMarkers = authenticatedAppSurfaceMarkers(pageText);
+    if (appMarkers.length > 0 &&
+        isAccountSetupActionTarget(action.target) &&
+        hasAccountSetupOverlay(pageText)) {
+        return (`Perception guard: "${action.target}" looks like an account/setup overlay action, ` +
+            `but authenticated app markers are already visible (${appMarkers.join(", ")}). ` +
+            `Do not retry OAuth or repeatedly press this overlay; use app navigation/direct ` +
+            `same-origin URLs or complete only the minimal required setup.`);
+    }
+    if (isBillingObjectActionTarget(action.target) &&
+        /\b(?:live|production)\s+mode\b/i.test(pageText)) {
+        return (`Mode safety guard: "${action.target}" can create or save billing objects, ` +
+            `but live/production mode is visible. Switch to the required test/sandbox mode before acting.`);
+    }
+    return null;
+}
+export function buildScreenOutline(elements, pageText) {
+    if (elements.length === 0)
+        return undefined;
+    const byRegion = new Map();
+    for (const el of elements) {
+        const id = el.container ?? "body:root";
+        const role = id.split(":")[0] ?? "region";
+        const existing = byRegion.get(id);
+        const region = existing ?? {
+            id,
+            role,
+            topmost: false,
+            occluded_by: null,
+            children: [],
+        };
+        if (el.topmost === true) {
+            region.topmost = true;
+            region.occluded_by = null;
+        }
+        else if (region.occluded_by === null &&
+            el.occludedBy !== null &&
+            el.occludedBy !== undefined) {
+            region.occluded_by = el.occludedBy;
+        }
+        if (region.children.length < 10) {
+            region.children.push({
+                ref: el.screenPath ?? elementRef(el),
+                role: el.role,
+                text: elementRef(el),
+                href: el.href ?? null,
+                topmost: el.topmost ?? null,
+                occluded_by: el.occludedBy ?? null,
+            });
+        }
+        byRegion.set(id, region);
+    }
+    const regions = [...byRegion.values()].slice(0, 12);
+    const foreground = regions.find((r) => r.topmost && r.role === "dialog")?.id ??
+        regions.find((r) => r.topmost)?.id ??
+        null;
+    return {
+        foreground,
+        mode_markers: visibleModeMarkers(pageText),
+        regions,
+    };
+}
+function roleForAccessibility(el) {
+    if (el.role !== null && el.role.length > 0)
+        return el.role;
+    if (el.tag === "a")
+        return "link";
+    if (el.tag === "input")
+        return el.type ?? "textbox";
+    return el.tag;
+}
+export function buildAccessibilitySnapshot(elements, generation, limit = 12000) {
+    if (elements.length === 0)
+        return undefined;
+    const refs = provisionElementRefs(elements, generation);
+    const byRegion = new Map();
+    for (const el of elements) {
+        const region = el.container ?? "body:root";
+        const group = byRegion.get(region) ?? [];
+        group.push(el);
+        byRegion.set(region, group);
+    }
+    const entries = [...byRegion.entries()];
+    const structurallyTruncated = entries.length > 24 || entries.some(([, group]) => group.length > 16);
+    const lines = ["RootWebArea"];
+    for (const [region, group] of entries.slice(0, 24)) {
+        lines.push(`  region "${region}"`);
+        for (const el of group.slice(0, 16)) {
+            const label = elementRef(el).replace(/"/g, '\\"');
+            const role = roleForAccessibility(el);
+            const flags = [
+                el.value !== undefined && el.value !== null ? `value="${el.value.slice(0, 60)}"` : null,
+                el.checked !== undefined && el.checked !== null ? `checked=${el.checked}` : null,
+                el.href !== undefined && el.href !== null ? `href="${el.href.slice(0, 120)}"` : null,
+                el.topmost === false ? `occluded_by="${el.occludedBy ?? "unknown"}"` : null,
+            ].filter((v) => v !== null);
+            lines.push(`    ${role} "${label}" ref=${refs.get(el) ?? provisionElementRef(el, generation)}` +
+                (flags.length > 0 ? ` ${flags.join(" ")}` : ""));
+        }
+    }
+    if (structurallyTruncated) {
+        lines.push("  ... (truncated, more interactive elements omitted)");
+    }
+    const tree = lines.join("\n");
+    if (tree.length <= limit) {
+        return {
+            tree,
+            refs: elements.length,
+            truncated: structurallyTruncated,
+            total_chars: tree.length,
+            source: "interactive_dom",
+        };
+    }
+    const cut = tree.lastIndexOf("\n", limit);
+    const text = tree.slice(0, cut > 0 ? cut : limit);
+    return {
+        tree: text,
+        refs: elements.length,
+        truncated: true,
+        total_chars: tree.length,
+        source: "interactive_dom",
+    };
+}
 function registrableHost(url) {
     try {
         return new URL(url).hostname.toLowerCase();
@@ -108,23 +510,107 @@ function registrableHost(url) {
         return null;
     }
 }
+function baseDomain(host) {
+    const parts = host.toLowerCase().split(".").filter(Boolean);
+    if (parts.length <= 2)
+        return parts.join(".");
+    return parts.slice(-2).join(".");
+}
+function widenAllowedHostsFromCurrentUrl(session) {
+    const host = registrableHost(session.browser.currentUrl());
+    if (host === null || session.allowedHosts.some((e) => e.host === host))
+        return;
+    const currentBase = baseDomain(host);
+    // Chain ONLY off START-sourced hosts: an organic redirect that shares a base
+    // domain with a host the user declared at start is trusted. We do NOT chain
+    // off mid_session or prior auto_widen hosts — that would let a single
+    // agent-declared host silently pull in a whole sibling tree (scope creep).
+    if (session.allowedHosts.some((e) => e.source === "start" && baseDomain(e.host) === currentBase)) {
+        session.allowedHosts.push({ host, source: "auto_widen" });
+        audit(session.id, "scope_widen", { host, source: "auto_widen", allowed_hosts: hostStrings(session) });
+    }
+}
+export function googleSessionGate(liveProviders) {
+    if (liveProviders.includes("google"))
+        return { ok: true };
+    return {
+        ok: false,
+        needs_user: {
+            wall: "google_session",
+            message: "No live Google session in the bot profile, so the operator cannot act " +
+                "as you yet. Run `npx @trusty-squire/mcp connect` (or refresh the Google " +
+                "login) and retry — the task has NOT started and nothing was changed.",
+            resume: "connect",
+        },
+    };
+}
+async function ensureProvisionPrimaryProviderSession(profileDir) {
+    const initial = await detectActiveProviderSessions(profileDir).catch(() => []);
+    if (initial.includes("google"))
+        return initial;
+    const result = await ensureOAuthSession({
+        provider: "google",
+        ...(profileDir !== undefined ? { profileDir } : {}),
+    });
+    if (result.status !== "already_valid" && result.status !== "logged_in") {
+        return initial;
+    }
+    const after = await detectActiveProviderSessions(profileDir).catch(() => []);
+    return after.includes("google") ? after : ["google", ...after];
+}
 export async function startProvisionSession(opts) {
     const id = randomUUID();
+    const liveProviders = await ensureProvisionPrimaryProviderSession(opts.profileDir);
+    // Change 5 — fail-closed identity gate BEFORE driving. If an operate task
+    // needs to act as the user and there's no live Google session, hand back now;
+    // do not start the browser or the task. No autonomous login is attempted.
+    if (opts.requireLiveIdentity === true) {
+        const gate = googleSessionGate(liveProviders);
+        if (!gate.ok) {
+            audit(id, "connect_gate", { ok: false, wall: "google_session" });
+            return { session_id: id, url: "", text: "", elements: [], needs_user: gate.needs_user };
+        }
+    }
     const browser = new BrowserController({
         ...(opts.profileDir !== undefined ? { profileDir: opts.profileDir } : {}),
         ...(opts.proxyUrl !== undefined ? { proxyUrl: opts.proxyUrl } : {}),
     });
     await browser.start();
     const targetHost = registrableHost(opts.serviceUrl);
-    const allowedHosts = [
+    const seedHosts = [
         ...(targetHost !== null ? [targetHost] : []),
         ...(opts.extraAllowedHosts ?? []),
     ];
-    const session = { id, browser, allowedHosts, lastElements: [] };
+    // All start-declared hosts are sourced "start" — auto-widen chains off these,
+    // and credential egress may seed from these (but never from mid_session).
+    const allowedHosts = [...new Set(seedHosts)].map((host) => ({
+        host,
+        source: "start",
+    }));
+    const session = {
+        id,
+        browser,
+        allowedHosts,
+        generation: 0,
+        secretSlots: new Map(),
+        lastElements: [],
+    };
     sessions.set(id, session);
-    audit(id, "start", { service_url: opts.serviceUrl, allowed_hosts: allowedHosts });
+    audit(id, "start", {
+        service_url: opts.serviceUrl,
+        allowed_hosts: hostStrings(session),
+        has_hint: opts.hint !== undefined,
+    });
     await browser.goto(opts.serviceUrl);
-    return await observeSession(session);
+    const observation = await observeSession(session);
+    // Tell the agent which provider the user actually has a live session for
+    // (Google-preferred) — the bot knows from the profile cookies, so the agent
+    // doesn't have to guess. Composed with the skill route hint (if any).
+    const hintParts = [
+        loginSessionGuidance(liveProviders),
+        ...(opts.hint !== undefined ? [opts.hint] : []),
+    ];
+    return { ...observation, hint: hintParts.join("\n") };
 }
 export async function observe(sessionId) {
     const session = sessions.get(sessionId);
@@ -132,16 +618,61 @@ export async function observe(sessionId) {
         throw new Error(`unknown provision session ${sessionId}`);
     return await observeSession(session);
 }
+// Hosts to seed credential EGRESS from when storing a key extracted in this
+// session: start + auto_widen, NEVER mid_session task scope (a wide multi-app
+// operate scope must not silently over-grant a key's egress allow-list).
+export function observedHostsForSession(sessionId) {
+    const session = sessions.get(sessionId);
+    if (session === undefined)
+        throw new Error(`unknown provision session ${sessionId}`);
+    widenAllowedHostsFromCurrentUrl(session);
+    return [...new Set(egressSeedHosts(session))];
+}
+// Mask a secret for a host-facing preview: keep a short prefix + last few
+// chars, redact the middle. Never reveals enough to reconstruct the value.
+export function maskSecretValue(value) {
+    const v = value.trim();
+    if (v.length <= 8)
+        return "••••";
+    const head = v.slice(0, Math.min(6, v.length - 4));
+    const tail = v.slice(-3);
+    return `${head}••••${tail}`;
+}
+// Stash a secret into a session-local slot and return ONLY a handle + masked
+// preview. The raw value stays in the Session and is never returned to the
+// host — a later type_secret enters it into another site's form. Extends the
+// write-only-vault moat to in-session credential transfer.
+export function stashSecretSlot(sessionId, slot, value) {
+    const session = sessions.get(sessionId);
+    if (session === undefined)
+        throw new Error(`unknown provision session ${sessionId}`);
+    session.secretSlots.set(slot, value);
+    audit(sessionId, "secret_slot_set", { slot, length: value.length });
+    return { slot, preview: maskSecretValue(value), length: value.length };
+}
 async function observeSession(session) {
+    session.browser.recoverActivePage();
+    widenAllowedHostsFromCurrentUrl(session);
+    session.generation += 1;
+    const generation = session.generation;
     const elements = await session.browser.extractInteractiveElements();
     session.lastElements = elements;
     const text = await session.browser.extractVisibleText();
+    const normalizedText = text.replace(/\s+/g, " ").trim().slice(0, 4000);
+    const guidance = provisionPerceptionGuidance(normalizedText);
+    const screen = buildScreenOutline(elements, normalizedText);
+    const accessibility = buildAccessibilitySnapshot(elements, generation);
+    const refs = provisionElementRefs(elements, generation);
     return {
         session_id: session.id,
         url: session.browser.currentUrl(),
-        text: text.replace(/\s+/g, " ").trim().slice(0, 4000),
+        text: normalizedText,
+        ...(guidance !== undefined ? { guidance } : {}),
+        ...(screen !== undefined ? { screen } : {}),
+        ...(accessibility !== undefined ? { accessibility } : {}),
         elements: elements.map((el) => ({
-            ref: elementRef(el),
+            ref: refs.get(el) ?? provisionElementRef(el, generation),
+            label: elementRef(el),
             tag: el.tag,
             role: el.role,
             type: el.type,
@@ -149,6 +680,10 @@ async function observeSession(session) {
             checked: el.checked ?? null,
             href: el.href ?? null,
             testId: el.testId ?? null,
+            path: el.screenPath ?? null,
+            container: el.container ?? null,
+            topmost: el.topmost ?? null,
+            occluded_by: el.occludedBy ?? null,
         })),
     };
 }
@@ -164,13 +699,25 @@ export async function act(sessionId, action) {
     });
     switch (action.kind) {
         case "goto": {
-            if (!hostAllowed(action.url, session.allowedHosts)) {
+            if (!hostAllowed(action.url, hostStrings(session))) {
                 throw new Error(`goto blocked by domain-scope: ${action.url} is outside the allowed hosts ` +
-                    `[${session.allowedHosts.join(", ")}] + auth providers`);
+                    `[${hostStrings(session).join(", ")}] + auth providers. ` +
+                    `Declare it first with an allow_host action if this task spans it.`);
             }
             await browser.goto(action.url);
             break;
         }
+        case "allow_host": {
+            const checked = validateAllowHost(action.host);
+            if ("error" in checked) {
+                throw new Error(`allow_host rejected "${action.host}": ${checked.error}`);
+            }
+            if (!session.allowedHosts.some((e) => e.host === checked.host)) {
+                session.allowedHosts.push({ host: checked.host, source: "mid_session" });
+                audit(sessionId, "allow_host", { host: checked.host, allowed_hosts: hostStrings(session) });
+            }
+            break;
+        }
         case "press": {
             await browser.pressKey(action.key);
             break;
@@ -179,17 +726,46 @@ export async function act(sessionId, action) {
             await browser.settleAfterOAuth();
             break;
         }
+        case "scroll": {
+            await browser.scrollViewport(action.direction ?? "down");
+            break;
+        }
+        case "type_secret": {
+            const value = session.secretSlots.get(action.slot);
+            if (value === undefined) {
+                throw new Error(`type_secret: no sealed slot named "${action.slot}". Capture it first with ` +
+                    `operate_extract { into_slot: "${action.slot}" }. Known slots: ` +
+                    `[${[...session.secretSlots.keys()].join(", ")}]`);
+            }
+            const fresh = await browser.extractInteractiveElements();
+            session.lastElements = fresh;
+            const el = resolveTarget(fresh, action.target, session.generation);
+            if (el === null) {
+                throw new Error(`type_secret: no element matched target "${action.target}".`);
+            }
+            // Type the REAL value into the page. It crosses only browser↔page; the
+            // value is never returned to the host and never logged.
+            await browser.type(el.selector, value);
+            audit(sessionId, "type_secret", { slot: action.slot, target: action.target, host: registrableHost(browser.currentUrl()) });
+            break;
+        }
         case "click":
         case "js_click":
         case "type":
         case "oauth_click": {
+            const blockReason = shouldBlockUnsafeProvisionAction(await browser.extractVisibleText(), action);
+            if (blockReason !== null)
+                throw new Error(blockReason);
             // Re-resolve against FRESH elements every act — never trust a stale index.
             const fresh = await browser.extractInteractiveElements();
             session.lastElements = fresh;
-            const el = resolveTarget(fresh, action.target);
+            const el = resolveTarget(fresh, action.target, session.generation);
             if (el === null) {
                 throw new Error(`no element matched target "${action.target}". Visible: ` +
-                    fresh.map((e) => `"${elementRef(e)}"`).slice(0, 20).join(", "));
+                    fresh
+                        .map((e) => `"${e.screenPath ?? elementRef(e)}"`)
+                        .slice(0, 20)
+                        .join(", "));
             }
             if (action.kind === "click")
                 await browser.click(el.selector);
@@ -199,21 +775,207 @@ export async function act(sessionId, action) {
                 await browser.type(el.selector, action.text);
             else
                 await browser.startOAuth(el.selector);
-            // Brief settle so a React state update (a card selection, a form-state
-            // commit) lands before the next observe — the radio-card "needed a
-            // re-observe" symptom from the live run.
             if (action.kind !== "type")
-                await settle(450);
+                await settleAfterStateChange(browser);
             break;
         }
     }
     return await observeSession(session);
 }
+async function settleAfterStateChange(browser) {
+    await settle(450);
+    await browser.waitForInteractiveDom(1, 2_000).catch(() => undefined);
+    for (let i = 0; i < 4; i += 1) {
+        const text = await browser.extractVisibleText().catch(() => "");
+        if (text.replace(/\s+/g, " ").trim().length > 0)
+            return;
+        await settle(300);
+    }
+}
 const normLabelKey = (label) => label
     .replace(/\s+/g, "_")
     .replace(/[^a-z0-9_]/gi, "")
     .toLowerCase()
     .slice(0, 40);
+// A real credential never looks like a code identifier. X's anti-bot tombstone
+// ("JavaScript is not available…") leaked `loader.tweetUnavailableTombstoneHandler`
+// (a JS function name) into the extractor, which wrote it to the vault as a key
+// — a false-green. Reject any dotted member-access token (JWTs are the one
+// legitimate dotted credential, guarded by their `eyJ` prefix).
+export function looksLikeCodeIdentifier(s) {
+    const t = s.trim();
+    if (t.startsWith("eyJ"))
+        return false;
+    return /[A-Za-z]\.[A-Za-z]/.test(t);
+}
+function looksLikeCredentialValue(value) {
+    const v = value.trim();
+    if (v.length < 12)
+        return false;
+    if (looksLikeCodeIdentifier(v))
+        return false;
+    if (isCredentialNoise(v))
+        return false;
+    return (findCredentialTokens(v).includes(v) ||
+        /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(v) ||
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v));
+}
+function isCredentialNoise(value) {
+    const v = value.trim();
+    if (v.length === 0)
+        return true;
+    // Whitespace anywhere → page prose, not a key (a greeting like "Hi X, what do
+    // you want to make?", a sentence, "Owner: foo"). Real keys never contain spaces.
+    if (/\s/.test(v))
+        return true;
+    if (/^\d{1,2}\/\d{1,2}\/\d{4}$/.test(v))
+        return true;
+    if (/^\d{4}-\d{2}-\d{2}([T ].*)?$/.test(v))
+        return true; // ISO date/timestamp (2026-06-23)
+    if (/^[^@\s]+@[^@\s]+\.[a-z]{2,}$/i.test(v))
+        return true; // email address
+    if (v.endsWith(":"))
+        return true; // a UI label fragment ("Owner:")
+    if (/^v?\d+\.\d+\.\d+(?:[-+.][A-Za-z0-9.-]+)?$/.test(v))
+        return true;
+    if (/^https?:\/\//i.test(v))
+        return true;
+    if (/^trusty-squire-dogfood-\d{8}$/i.test(v))
+        return true;
+    if (/^[A-Z][A-Z0-9_]{2,}=?$/.test(v))
+        return true;
+    if (/^key_[A-Za-z0-9]{16,}$/i.test(v))
+        return true;
+    if (v.includes("…") || v.includes("..."))
+        return true;
+    return false;
+}
+// A credentials page that is actually a login wall / anti-bot interstitial has
+// no key to give — every token on it (CSRF cookie, asset hash, guest id) is
+// junk. Grok is the standing case: x.ai routes signup through X (Twitter) OAuth,
+// and X serves headless Chromium its "JavaScript is not available" tombstone, so
+// the extractor would otherwise scrape session tokens and hand one back as a
+// false-green key. Detect that state and fail CLOSED — return no credential plus
+// an explicit reason the host agent can act on (drive an interactive login),
+// rather than surfacing a bogus value. The phrases below are the load-bearing
+// markers of X's tombstone + the four anti-bot vendors waitForFormReady knows.
+const LOGIN_WALL_MARKERS = [
+    /javascript is not available/i,
+    /enable javascript/i,
+    /verifying you are human/i,
+    /checking your browser/i,
+    /just a moment/i,
+    /review the security of your connection/i,
+    /unusual (traffic|activity) (from|on)/i,
+];
+export function detectExtractionBlock(pageText) {
+    // Require a SHORT page — a real keys page that merely mentions "enable
+    // JavaScript" in a footer is not a wall. A tombstone/interstitial is sparse.
+    if (pageText.trim().length > 600)
+        return null;
+    for (const re of LOGIN_WALL_MARKERS) {
+        if (re.test(pageText)) {
+            return "login_wall: the page is an anti-bot/login interstitial (no credential present) — drive an interactive login or hand back to the user";
+        }
+    }
+    return null;
+}
+// Collect every distinct credential-SHAPED token in a blob of page text:
+// a short prefix + separator + a long body that carries at least one digit
+// (vsk_sandbox_write_…, xai-…, sk-lw-…, re_…). Used to surface the SECOND key a
+// multi-credential service shows (e.g. VouchFlow's sandbox read alongside write)
+// that the single-key extraction.ts policy stops short of. The `[_-]` and
+// has-digit requirements exclude the dotted-function-name false positive.
+const CRED_TOKEN_RE = /\b[A-Za-z][A-Za-z0-9]{1,9}[_-][A-Za-z0-9][A-Za-z0-9_-]{12,}\b/g;
+export function findCredentialTokens(text) {
+    const out = [];
+    const seen = new Set();
+    for (const m of text.matchAll(CRED_TOKEN_RE)) {
+        const t = m[0];
+        if (seen.has(t))
+            continue;
+        if (t.length < 16)
+            continue;
+        if (!/[0-9]/.test(t))
+            continue; // real keys carry digits; dictionary words don't
+        if (/^[A-Z][A-Z0-9_]*$/.test(t))
+            continue; // env-var name
+        if (!looksLikeCredentialToken(t))
+            continue;
+        seen.add(t);
+        out.push(t);
+    }
+    return out;
+}
+function looksLikeCredentialToken(token) {
+    if (token.includes("_"))
+        return true;
+    if (/^(?:api|key|pk|re|rk|sk|xai|ghp|pat|vsk|tly)-/i.test(token))
+        return true;
+    // <short alpha vendor prefix>-<single long alphanumeric run>. We don't
+    // enumerate every vendor prefix; any "prefix-<random run>" is a key. The body
+    // must be ONE alphanumeric run (no further separators) so a word-word-word-date
+    // slug (trusty-squire-dogfood-20260625) is excluded — that has multiple hyphens.
+    return /^[A-Za-z][A-Za-z0-9]{0,7}-[A-Za-z0-9]{12,}$/.test(token);
+}
+function firstTokenMatching(haystack, re) {
+    const match = haystack.match(re);
+    return match?.[0] ?? null;
+}
+export function sanitizeExtractedCredentials(credentials, url, haystack = Object.values(credentials).join("\n")) {
+    const host = registrableHost(url) ?? "";
+    const normalized = {};
+    if (host === "cloud.langfuse.com") {
+        const secret = firstTokenMatching(haystack, /\bsk-lf-[0-9a-f-]{20,}\b/i);
+        const pub = firstTokenMatching(haystack, /\bpk-lf-[0-9a-f-]{20,}\b/i);
+        if (secret !== null) {
+            normalized.langfuse_secret_key = secret;
+            normalized.api_key = secret;
+        }
+        if (pub !== null)
+            normalized.langfuse_public_key = pub;
+        return normalized;
+    }
+    if (host.endsWith(".neon.tech")) {
+        const token = firstTokenMatching(haystack, /\bnapi_[A-Za-z0-9_-]{24,}\b/);
+        if (token !== null) {
+            normalized.api_token = token;
+            normalized.api_key = token;
+        }
+        return normalized;
+    }
+    for (const [key, value] of Object.entries(credentials)) {
+        const k = normLabelKey(key);
+        if (k === "refcode" || k === "referral_code")
+            continue;
+        if (isCredentialNoise(value))
+            continue;
+        if ((k === "key" || k === "api_key") && !looksLikeCredentialValue(value))
+            continue;
+        if (host === "api.together.ai" && /^key_[A-Za-z0-9]{16,}$/i.test(value.trim()))
+            continue;
+        normalized[key] = value;
+    }
+    return normalized;
+}
+export function classifyVouchflowCredentials(text) {
+    const out = {};
+    for (const tok of findCredentialTokens(text)) {
+        if (/^vsk_sandbox_read_/i.test(tok) && out.sandbox_read_key === undefined) {
+            out.sandbox_read_key = tok;
+        }
+        else if (/^vsk_sandbox_/i.test(tok) && out.sandbox_write_key === undefined) {
+            out.sandbox_write_key = tok;
+        }
+        else if (/^vsk_live_read_/i.test(tok) && out.live_read_key === undefined) {
+            out.live_read_key = tok;
+        }
+        else if (/^vsk_live_/i.test(tok) && out.live_write_key === undefined) {
+            out.live_write_key = tok;
+        }
+    }
+    return out;
+}
 // Reveal masked keys, then classify every on-page string source through the
 // SAME exported regex policy the bot uses (extractApiKeyFromText +
 // isTruncatedCapture + extraction.ts accumulation). Reuses the substrate —
@@ -229,6 +991,20 @@ export async function extractCredentials(sessionId) {
     const inputs = await browser.extractAllInputValues();
     const nearCopy = await browser.extractCredentialsNearCopyButtons();
     const text = await browser.extractVisibleText();
+    // Fail CLOSED on a login wall / anti-bot interstitial: scraping it yields only
+    // session/CSRF/asset tokens, and handing one back is a false-green. Refuse,
+    // and tell the host why so it can drive an interactive login instead.
+    const blocked = detectExtractionBlock(text);
+    if (blocked !== null) {
+        audit(sessionId, "extract", { found: false, blocked_reason: blocked });
+        return {
+            session_id: sessionId,
+            url: browser.currentUrl(),
+            credentials: {},
+            candidate_count: 0,
+            blocked_reason: blocked,
+        };
+    }
     // Copy-only key surfaces (e.g. LangWatch's /settings/api-keys) never render
     // the value into the DOM — it goes to the clipboard on a "Copy" click. Read
     // it (clipboard-read is granted at context creation).
@@ -236,6 +1012,7 @@ export async function extractCredentials(sessionId) {
     // Primary api_key: first FULL hit wins; a truncated/masked hit is the fallback.
     let state = initialExtractionState();
     const sources = [...labeled.map((c) => c.value), ...inputs, ...nearCopy, clip, text];
+    const haystack = sources.join("\n");
     for (const src of sources) {
         if (hasFullHit(state))
             break;
@@ -248,10 +1025,15 @@ export async function extractCredentials(sessionId) {
         // reaches the actual secret further down the source list.
         if (/^[A-Z][A-Z0-9_]{2,}=?$/.test(key.trim()))
             continue;
+        if (isCredentialNoise(key))
+            continue;
         // Reject too-short non-secrets (UI noise like "Ctrl+K"). Real API keys are
         // long; a sub-12-char "key" is a false positive, never a credential.
         if (key.trim().length < 12)
             continue;
+        // Reject a code identifier scraped off a page (the X-tombstone false-green).
+        if (looksLikeCodeIdentifier(key))
+            continue;
         const cls = isTruncatedCapture(src, key)
             ? { kind: "truncated", value: key }
             : { kind: "full", value: key };
@@ -264,7 +1046,9 @@ export async function extractCredentials(sessionId) {
     for (const c of labeled) {
         if (c.label === null || c.isMasked)
             continue;
-        if (/^[A-Z][A-Z0-9_]{2,}=?$/.test(c.value.trim()))
+        if (isCredentialNoise(c.value))
+            continue;
+        if (looksLikeCodeIdentifier(c.value))
             continue;
         const k = normLabelKey(c.label);
         if (k.length > 0 && !(k in named))
@@ -273,21 +1057,55 @@ export async function extractCredentials(sessionId) {
     // resolveExtraction (the regex-found primary key) wins over a same-named
     // labeled candidate, so a "API Key" label carrying the env-var snippet can
     // never clobber the real `api_key`.
-    const credentials = { ...named, ...resolveExtraction(state) };
+    const credentials = {
+        ...named,
+        ...classifyVouchflowCredentials(haystack),
+        ...resolveExtraction(state),
+    };
+    // Multi-credential: a service may present several keys of the same shape
+    // (VouchFlow shows sandbox write AND read). The single-key extraction.ts
+    // policy stops at the first; collect every distinct credential-shaped token
+    // and surface the ones the primary missed as api_key_2, api_key_3, …
+    const have = new Set(Object.values(credentials));
+    let n = 1;
+    for (const tok of findCredentialTokens(haystack)) {
+        if (have.has(tok))
+            continue;
+        if (n >= 8)
+            break; // cap extras so page noise can't flood the result
+        have.add(tok);
+        n += 1;
+        credentials[`api_key_${n}`] = tok;
+    }
+    const sanitized = sanitizeExtractedCredentials(credentials, browser.currentUrl(), haystack);
+    const found = Object.keys(sanitized).length > 0;
+    // Report-back so the agent keeps going instead of treating an empty result as
+    // done: if the page HAD labeled candidates but none survived as a real
+    // credential, they were page noise (a date/email/greeting) or a still-masked
+    // display — i.e. this isn't the keys page or the key needs revealing. Tell the
+    // agent that so it navigates/reveals and extracts again, rather than storing junk.
+    const notLegit = !found && labeled.length > 0
+        ? "no_legit_credential: the page had candidate values but none looked like a " +
+            "real key (they were page text — a date/email/label — or a still-masked " +
+            "display). You are likely NOT on the API-keys page, or the key is masked. " +
+            "Navigate to the keys/settings page (or click reveal/show/copy), then extract again."
+        : null;
     audit(sessionId, "extract", {
-        found: Object.keys(credentials).length > 0,
+        found,
         candidate_count: labeled.length,
+        not_legit: notLegit !== null,
     });
     return {
         session_id: sessionId,
         url: browser.currentUrl(),
-        credentials,
+        credentials: sanitized,
         candidate_count: labeled.length,
+        ...(notLegit !== null ? { blocked_reason: notLegit } : {}),
     };
 }
 // Detect a captcha and wait for it to clear. Behavior-sim (humanized clicks +
 // typing) during the drive already scores invisible Turnstile/reCAPTCHA-v3; for
-// a visible checkbox the host clicks it via provision_act, then calls this to
+// a visible checkbox the host clicks it via operate_act, then calls this to
 // wait for the token. Reuses the substrate's detector + settle poll.
 export async function captchaGate(sessionId) {
     const session = sessions.get(sessionId);
@@ -323,6 +1141,24 @@ export function parseVerification(text, links) {
     }
     return { code, link };
 }
+// Pure: assemble the verification result. When neither a code nor a link was
+// found, the thick session is still live, so this is a RESUMABLE hand-back
+// (Flow A) — the host asks the user for the code and types it — not a give-up.
+// Exported for unit tests.
+export function buildVerificationResult(sessionId, code, link) {
+    const found = code !== null || link !== null;
+    if (found)
+        return { session_id: sessionId, found, code, link };
+    const needs_user = {
+        wall: "verification_code",
+        message: "No verification code found in the inbox automatically. The service may " +
+            "have sent it by SMS or an authenticator app, or it hasn't arrived yet. " +
+            "Ask the user for the code, then type it into the verification field with " +
+            "operate_act and continue — the session is still live.",
+        resume: "code",
+    };
+    return { session_id: sessionId, found, code, link, needs_user };
+}
 export async function awaitVerification(sessionId, opts = {}) {
     const session = sessions.get(sessionId);
     if (session === undefined)
@@ -354,8 +1190,16 @@ export async function awaitVerification(sessionId, opts = {}) {
         sender: opts.sender ?? null,
         has_code: code !== null,
         has_link: link !== null,
+        sealed: opts.intoSlot !== undefined && code !== null,
+        needs_user: !found,
     });
-    return { session_id: sessionId, found, code, link };
+    // Seal the OTP into a slot when asked: the host gets a masked handle, not the
+    // code, and enters it with type_secret. The link (not secret) is still returned.
+    if (opts.intoSlot !== undefined && code !== null) {
+        const handle = stashSecretSlot(sessionId, opts.intoSlot, code);
+        return { session_id: sessionId, found: true, code: null, link, sealed: true, slot: handle };
+    }
+    return buildVerificationResult(sessionId, code, link);
 }
 export async function finishProvisionSession(sessionId) {
     const session = sessions.get(sessionId);