@cloudgrid-io/mcp 0.21.7 → 0.21.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.21.7",
+  "version": "0.21.9",
   "description": "MCP access to CloudGrid — the live runtime environment where the user's apps run WITH the infrastructure they need out of the box: managed MongoDB, Redis (cache/queues/pub-sub), a pgvector store, persistent disk, and built-in AI with no API keys, in any language or stack, no Docker or Kubernetes to manage. Brainstorm, build, plug, and improve apps, games, dashboards, and tools; instant single-page publishes and full runtime-app deploys with a live URL — for developers and non-technical users. Three editions: local stdio (full toolset), hosted web (light, CLI-free), and a public docs-search server.",
   "type": "module",
   "bin": {
@@ -36,6 +36,7 @@
     "test:mcpb-boot": "node test/mcpb-boot.test.mjs",
     "test:plug-timeout": "node test/plug-timeout.test.mjs",
     "test:manifest-confirm": "node test/manifest-confirm.test.mjs",
+    "test:inline-multifile-guard": "node test/inline-multifile-guard.test.mjs",
     "test:qa-courier": "node test/qa-courier.test.mjs",
     "test:drift-guard": "node test/drift-guard.mjs",
     "smoke:drop": "node test/smoke-drop.mjs",
@@ -71,6 +72,7 @@
     "test:web-capabilities-log": "node --test test/web-capabilities-log.test.mjs",
     "test:internal-refs": "node --test test/no-internal-refs.test.mjs",
     "test:login-app": "node test/login-app.test.mjs",
+    "test:login-poller": "node test/login-poller.test.mjs",
     "build:login-widget": "node scripts/build-login-widget.mjs"
   },
   "dependencies": {

package/src/tools/constants.js

@@ -53,7 +53,26 @@ export const VISIBILITY_LABELS = {
 // optional. Flip MCP_APPS_WIDGETS=1 in the platform manifest to re-enable once
 // the widget HTML is verified to render. The resources stay registered either
 // way (harmless when no tool references them via outputTemplate).
+//
+// 2026-08-25 (#308): the black frame was diagnosed as a MIME mismatch. ChatGPT
+// discovers an Apps-SDK widget by a tool carrying openai/outputTemplate PLUS a
+// ui:// resource whose mimeType is `text/html+skybridge` (verified against
+// OpenAI's shipped example servers — openai/openai-apps-sdk-examples
+// solar-system/shopping_cart/kitchen_sink main.py). Our two ChatGPT widgets
+// declared `text/html;profile=mcp-app` — the SEP-1865/MCP-Apps MIME that CLAUDE
+// reads (RESOURCE_MIME_TYPE in @modelcontextprotocol/ext-apps). ChatGPT saw the
+// outputTemplate pointer, opened the skybridge iframe (dark chrome), but the
+// resource was not a skybridge document, so the HTML/bridge never populated —
+// the empty dark frame covering the text. CHATGPT_WIDGET_MIME below is the
+// correct type. The flag STAYS OFF until a card is seen rendering in real
+// ChatGPT (Developer Mode custom connector against staging); this only makes the
+// machinery correct for that verification.
 export const APPS_WIDGETS_ENABLED = process.env.MCP_APPS_WIDGETS === "1";
+// The mimeType ChatGPT's Apps-SDK renderer requires for a ui:// widget resource.
+// Distinct from RESOURCE_MIME_TYPE (`text/html;profile=mcp-app`, the SEP-1865
+// key Claude reads) — the two hosts key off different MIME types, so the ChatGPT
+// widgets and the Claude sign-in card must NOT share one.
+export const CHATGPT_WIDGET_MIME = "text/html+skybridge";
 export const LIVE_RESULT_URI = "ui://cloudgrid/live-result.html";
 // URI/resource-name/filename stay `org-picker` — that's the stable contract the
 // web card is registered under; only the JS identifier moves toward grid.
@@ -72,10 +91,6 @@ export const GRID_PICKER_HTML = readFileSync(new URL("../widgets/org-picker.html
 // scripts/build-login-widget.mjs (App class + card inlined; deny-by-default CSP).
 export const GRID_LOGIN_APP_URI = "ui://grid-login/mcp-app.html";
 export const GRID_LOGIN_APP_HTML = readFileSync(new URL("../widgets/grid-login.html", import.meta.url), "utf-8");
-export const WIDGET_CSP = {
-  connectDomains: ["https://*.cloudgrid.io"],
-  resourceDomains: ["https://*.cloudgrid.io"],
-};
 
 // The lazy npx fallback always fetches the LATEST published CLI, so the MCP is
 // never left behind the platform's required CLI version (a pinned range went

package/src/tools/deploy.js

@@ -1480,6 +1480,45 @@ function plugErrorMessage(status, code, msg, ctxFlags = {}) {
   return guidance ? `${base} — ${guidance}` : base;
 }
 
+// ── Corrupt-archive FETCHSOURCE handoff (defense in depth) ───────────────────
+// Historically the hosted (web) server materialized uploaded multipart parts
+// into a source tarball SERVER-SIDE and, for a multi-file runtime app re-plugged
+// inline, could emit a non-gzip stream that died at the build container's
+// FETCHSOURCE with "gzip: stdin: not in gzip format / tar: Child returned status
+// 1" — raw, unactionable output. The server-side defect (cloudgrid#2977) is now
+// fixed and verified live, and the pre-upload gate that refused that shape has
+// been lifted (#315). This handoff stays as defense in depth: if a corrupt-archive
+// build failure ever recurs, rewrite the raw tar/gzip log to an actionable CLI
+// handoff (via archiveCorruptionSignature) instead of surfacing it verbatim.
+
+// The "continue this exact entity from a terminal" CLI commands, with the real
+// handle substituted. Prefers grid/slug (what `pull` takes, human-readable);
+// falls back to the entity id. Same entity, same URL.
+export function cliContinueHandoff({ entityId, grid, slug } = {}) {
+  const target = grid && slug ? `${grid}/${slug}` : slug || entityId || "<grid>/<app>";
+  const dir = slug || entityId || "<app>";
+  return (
+    "Continue from a terminal with the CLI — it uploads the files from disk and updates the SAME entity (same URL):\n" +
+    "  npx -y @cloudgrid-io/cli@latest login\n" +
+    `  npx -y @cloudgrid-io/cli@latest pull ${target}\n` +
+    `  cd ${dir}\n` +
+    "  npx -y @cloudgrid-io/cli@latest plug"
+  );
+}
+
+// True when a build failure is the corrupt-archive signature (a FETCHSOURCE
+// gunzip/tar failure), as opposed to a genuine app build error the developer can
+// act on (a missing dependency, a syntax error) — those keep their real log tail.
+export function archiveCorruptionSignature(text) {
+  const hay = String(text || "").toLowerCase();
+  return (
+    /not in gzip format/.test(hay) ||
+    /gzip:\s*stdin/.test(hay) ||
+    /tar:\s*child returned status/.test(hay) ||
+    /invalid gzip/.test(hay)
+  );
+}
+
 // Parse the live URL the CLI prints on a successful `plug`. The CLI prints the
 // canonical https://…cloudgrid.io URL somewhere in stdout (labelled "Outlet"
 // / "Live" / bare); take the last cloudgrid.io URL it emits — the final line is
@@ -2048,6 +2087,20 @@ export async function runPlug(ctx, input, deps = {}) {
       data.status = "live";
       data.poll_url = undefined;
     } else if (verdict.status === "failed") {
+      // Defense in depth: a corrupt-archive FETCHSOURCE failure is unactionable
+      // as raw tar output — never surface it verbatim. The server-side defect
+      // that produced it (cloudgrid#2977) is fixed and the pre-upload gate has
+      // been lifted (#315), so no corrupt-archive verdict is expected here; if the
+      // class ever recurs, name the CLI path with the real handle instead of the
+      // raw log. Genuine app build errors keep their real log tail — those the
+      // developer CAN act on.
+      if (archiveCorruptionSignature(`${verdict.error || ""}\n${verdict.logTail || ""}`)) {
+        throw new Error(
+          "The uploaded source could not be read by the build (its archive was corrupt) — the URL is NOT " +
+            "live. " +
+            cliContinueHandoff({ entityId: data.entity_id, grid: data.grid, slug: data.slug }),
+        );
+      }
       const msg = verdict.error || "The build failed.";
       throw new Error(
         `Deploy failed (trace ${data.trace_id ?? "n/a"}): ${msg} The URL is NOT live — do not give it to the user as working.` +
@@ -2675,6 +2728,24 @@ export async function runCheckDeploy(ctx, { poll_url, grid } = {}) {
     // the source zip (grid_get_app_source → source_download_url) or the
     // pull command that downloads + links the folder so the SAME entity
     // continues locally.
+    // Defense in depth: a corrupt-archive FETCHSOURCE failure is unactionable raw
+    // tar output — do NOT echo it. The server-side defect that produced it
+    // (cloudgrid#2977) is fixed and the pre-upload gate has been lifted (#315);
+    // if the class ever recurs, name the CLI continue-path with the real handle
+    // instead of the raw log.
+    if (archiveCorruptionSignature(`${verdict.error || ""}\n${verdict.logTail || ""}`)) {
+      return {
+        text: "The uploaded source could not be read by the build (its archive was corrupt) — the URL is " +
+          "not live. The project files are NOT lost — they are saved on the entity. " +
+          cliContinueHandoff({ entityId, grid: gridSlug, slug: ctx.state.lastDrop?.slug }),
+        structured: {
+          status: "failed",
+          live: false,
+          reason: "archive_corrupt",
+          ...(ctx.edition === "web" && entityId ? { source_recovery: { entity_id: entityId, via: ["grid_get_app_source", "grid pull"] } } : {}),
+        },
+      };
+    }
     const handoff = ctx.edition === "web" && entityId
       ? `\nThe project files are NOT lost — they are saved on the entity. If it can't be fixed from this chat, hand the user their work: call grid_get_app_source for the source zip (source_download_url), or give them the local continue command: npx -y @cloudgrid-io/cli@latest pull ${gridSlug ? `${gridSlug}/` : ""}${ctx.state.lastDrop?.slug || entityId} — it downloads the project and links the folder so their next plug updates this same entity.`
       : "";

package/src/tools/register.js

@@ -8,11 +8,11 @@ import { newLoginCode, buildLoginUrl, pollStatusOnce, checkApiConnectivity, deco
 import { PLAYBOOK, fetchCorpus, listWorkflows } from "../playbook.js";
 import {
   APPS_WIDGETS_ENABLED,
+  CHATGPT_WIDGET_MIME,
   LIVE_RESULT_URI,
   GRID_PICKER_URI,
   LIVE_RESULT_HTML,
   GRID_PICKER_HTML,
-  WIDGET_CSP,
   GRID_LOGIN_APP_URI,
   GRID_LOGIN_APP_HTML,
 } from "./constants.js";
@@ -124,27 +124,33 @@ export function registerTools(server, ctx) {
 
   // ── Widget resources (web edition, ChatGPT Apps SDK) ──────────────────────
   if (ctx.edition === "web") {
+    // ChatGPT Apps-SDK widgets. mimeType MUST be text/html+skybridge
+    // (CHATGPT_WIDGET_MIME) — NOT the MCP-Apps `text/html;profile=mcp-app` the
+    // Claude card uses; that mismatch was the black frame (#308). widgetAccessible
+    // lets the widget call tools back over window.openai.callTool (the visibility
+    // pills call grid_visibility). These make no direct network requests, so no
+    // openai/widgetCSP is declared — the default deny is correct.
     server.registerResource("cloudgrid-live-result", LIVE_RESULT_URI, {
       description: "Live result card after a CloudGrid drop — shows URL, grid link, and visibility controls.",
-      mimeType: "text/html;profile=mcp-app",
+      mimeType: CHATGPT_WIDGET_MIME,
     }, async () => ({
       contents: [{
         uri: LIVE_RESULT_URI,
-        mimeType: "text/html;profile=mcp-app",
+        mimeType: CHATGPT_WIDGET_MIME,
         text: LIVE_RESULT_HTML,
-        _meta: { ui: { csp: WIDGET_CSP } },
+        _meta: { "openai/widgetAccessible": true },
       }],
     }));
 
     server.registerResource("cloudgrid-org-picker", GRID_PICKER_URI, {
       description: "Grid picker card — lets the user choose which grid to plug into.",
-      mimeType: "text/html;profile=mcp-app",
+      mimeType: CHATGPT_WIDGET_MIME,
     }, async () => ({
       contents: [{
         uri: GRID_PICKER_URI,
-        mimeType: "text/html;profile=mcp-app",
+        mimeType: CHATGPT_WIDGET_MIME,
         text: GRID_PICKER_HTML,
-        _meta: { ui: { csp: WIDGET_CSP } },
+        _meta: { "openai/widgetAccessible": true },
       }],
     }));
 
@@ -512,11 +518,13 @@ export function registerTools(server, ctx) {
       // live at a public URL in place. Versions + grid rollback exist, but the
       // honest MCP annotation for overwrite-live-state is destructive.
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+      // ChatGPT-only binding: openai/outputTemplate points at the skybridge
+      // widget. Deliberately NOT the MCP-Apps `ui.resourceUri` key — that is
+      // Claude's, and the live-result resource is now text/html+skybridge, which
+      // Claude cannot render; carrying it here would regress the Claude path when
+      // this flag is flipped. The two mechanisms stay independent (#308/#303).
       ...(ctx.edition === "web" && APPS_WIDGETS_ENABLED ? {
-        _meta: {
-          ui: { resourceUri: LIVE_RESULT_URI, csp: WIDGET_CSP },
-          "openai/outputTemplate": LIVE_RESULT_URI,
-        },
+        _meta: { "openai/outputTemplate": LIVE_RESULT_URI },
       } : {}),
   };
   const plugHandler = async (input) => {
@@ -799,6 +807,11 @@ export function registerTools(server, ctx) {
         url: z.string().optional().describe("URL of the entity, if returned."),
       },
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+      // The live-result widget's visibility pills call this back over
+      // window.openai.callTool; ChatGPT only permits that when the target tool
+      // is marked openai/widgetAccessible. ChatGPT-only key, inert on Claude and
+      // when the widget is disabled. (#308)
+      ...(ctx.edition === "web" ? { _meta: { "openai/widgetAccessible": true } } : {}),
     },
     async (input) => {
       try {
@@ -930,7 +943,7 @@ export function registerTools(server, ctx) {
           .object({
             active_grid: z.string().nullable().describe("The user's active grid/org slug, or null."),
             signed_in: z.boolean().describe("Whether the current session is signed in."),
-            email: z.string().optional().describe("The signed-in user's email, when available."),
+            email: z.string().optional().describe("The signed-in user's email — the CloudGrid account this session is authenticated as. Present whenever signed_in is true and the session token carries an email claim (the normal case). Absent only if signed_in is false, or on the rare token that lacks the claim; the identity line in this tool's text content states which case applies. Use this to answer 'which account/user am I?'."),
             session_expired: z.boolean().optional().describe("True when credentials exist but the JWT has expired. Run grid_login to sign in again."),
             identity_changed: z.boolean().optional().describe("True when the session's identity changed via a different transport Bearer. Session state was reset."),
             update_available: z
@@ -994,8 +1007,22 @@ export function registerTools(server, ctx) {
       const wfLines = workflows.length
         ? workflows.map((w) => `  - ${w.name}: ${w.when || w.summary}`).join("\n")
         : "  (none available)";
+      // Identity banner — first line of the text channel, because the account
+      // this session is signed in as is only otherwise carried in
+      // structuredContent.context, which many clients/models never surface. A
+      // hosted assistant asked "which account am I?" was concluding no tool
+      // exposes it while the answer sat in structured output it had already
+      // received (#317). Stating it in the text the model actually reads makes
+      // "who am I" answerable without the CLI (whose separate session can point
+      // at a different account entirely).
+      const gridSuffix = activeGrid ? ` (active grid: ${activeGrid})` : "";
+      const identityLine = signedIn
+        ? signedInEmail
+          ? `You are signed in to CloudGrid as ${signedInEmail}${gridSuffix}. If the user asks which CloudGrid account, user, or email they are connected to, that is the answer.`
+          : `You are signed in to CloudGrid${gridSuffix}, but this session's token carries no email claim, so the account address is not available here. Do not guess it from grid memberships or the CLI (its session may be a different account).`
+        : `You are not signed in to CloudGrid. Run grid_login to sign in.`;
       let text =
-        `${PLAYBOOK}\n\nAvailable workflows:\n${wfLines}\n\n` +
+        `${identityLine}\n\n${PLAYBOOK}\n\nAvailable workflows:\n${wfLines}\n\n` +
         `Next: match the intent to a workflow and call grid_get_template({kind:"workflow", name}).` +
         (stale ? `\n\n${stale}` : "");
       if (sessionExpired) {

package/src/tools.js

@@ -31,6 +31,8 @@ export {
   errorGuidance,
   REPORT_OFFER,
   parseCliPlugUrl,
+  cliContinueHandoff,
+  archiveCorruptionSignature,
   plugViaCliFallback,
   runPlug,
   runPickup,

package/src/widgets/grid-login/mcp-app.js

@@ -22,6 +22,7 @@ import {
   applyHostFonts,
   applyHostStyleVariables,
 } from "@modelcontextprotocol/ext-apps";
+import { createPoller } from "./poller.js";
 
 const els = {
   root: document.getElementById("card"),
@@ -64,10 +65,108 @@ function showSignInReady() {
 
 function showAwaitingReturn() {
   els.status.textContent =
-    "Finish signing in on the page that opened, then come back and select Check sign-in.";
+    "Finish signing in on the page that opened — I'll notice automatically, or select Check sign-in.";
   els.check.hidden = false;
 }
 
+// ── Bounded polling ──────────────────────────────────────────────────────────
+// Once "Open sign-in" is clicked, the card polls grid_login_status until it
+// resolves. The loop and all its bounds live in poller.js (interval, wall-clock
+// ceiling, consecutive-error cap, hidden-tab skip) so they can be unit-tested
+// deterministically. Values chosen: a 3s interval keeps it to one round-trip
+// every few seconds; a 150s ceiling covers a normal sign-in with margin and
+// caps a backgrounded card at ≤50 requests total; 3 consecutive errors stops a
+// broken/blocked endpoint fast. The manual "Check sign-in" button stays the
+// escape hatch throughout.
+const POLL_INTERVAL_MS = 3000;
+const POLL_CEILING_MS = 150000;
+const MAX_CONSECUTIVE_ERRORS = 3;
+
+let settled = false; // true once we've reached signed-in (never act again)
+
+const poller = createPoller({
+  intervalMs: POLL_INTERVAL_MS,
+  ceilingMs: POLL_CEILING_MS,
+  maxConsecutiveErrors: MAX_CONSECUTIVE_ERRORS,
+  check: () => queryStatus(),
+  onSuccess: (email) => onSignedIn(email),
+  onCeiling: () => {
+    els.status.textContent =
+      "Still waiting for sign-in. Finish on the page that opened, then select Check sign-in.";
+  },
+  onGiveUp: () => {
+    els.status.textContent =
+      "Could not check sign-in automatically. Complete it in the browser, then select Check sign-in.";
+  },
+});
+
+// One grid_login_status round-trip. Returns a plain outcome; NEVER a token —
+// grid_login_status returns { status, email } and email is not a credential.
+async function queryStatus() {
+  try {
+    const result = await app.callServerTool({ name: "grid_login_status", arguments: {} });
+    const status = result?.structuredContent?.status;
+    const email = result?.structuredContent?.email;
+    return { authenticated: status === "authenticated", email, errored: false };
+  } catch (err) {
+    console.error("[grid-login card] status check failed", err);
+    return { authenticated: false, email: null, errored: true };
+  }
+}
+
+// Reached signed-in state. Update the card (email only, never a token) and tell
+// the model so the conversation continues WITHOUT the user typing anything.
+async function onSignedIn(email) {
+  settled = true;
+  poller.stop();
+  els.status.textContent = email ? `Signed in as ${email}.` : "Signed in.";
+  els.signin.hidden = true;
+  els.check.hidden = true;
+  // Once signed in there is nothing left to open — drop the manual sign-in link
+  // so the card reads as a clean terminal state, not a still-actionable prompt.
+  els.fallback.hidden = true;
+  await tellModel(email);
+}
+
+// Push the outcome to the host so the model continues on its own. Two calls,
+// because they do different things (verified against the installed
+// @modelcontextprotocol/ext-apps App class, not from memory):
+//   • updateModelContext — pushes structured signed-in state into the model's
+//     context, but by design does NOT trigger a turn (it waits for the next user
+//     message). On its own it would NOT fix the complaint.
+//   • sendMessage — adds a message to the conversation, which does trigger the
+//     model. This is the half that lets the conversation move on with no "done".
+// Both are wrapped so a host that lacks either still leaves the card signed-in
+// and the manual path intact.
+async function tellModel(email) {
+  const who = email ? ` as ${email}` : "";
+  try {
+    await app.updateModelContext({
+      content: [
+        {
+          type: "text",
+          text: `The user has finished signing in to CloudGrid${who}. Sign-in is complete — continue with what they were doing; no need to ask them to confirm.`,
+        },
+      ],
+      structuredContent: email
+        ? { status: "authenticated", email }
+        : { status: "authenticated" },
+    });
+  } catch (err) {
+    console.error("[grid-login card] updateModelContext failed", err);
+  }
+  try {
+    await app.sendMessage({
+      role: "user",
+      content: [
+        { type: "text", text: `I've signed in to CloudGrid${who}. Please continue.` },
+      ],
+    });
+  } catch (err) {
+    console.error("[grid-login card] sendMessage failed", err);
+  }
+}
+
 const app = new App({ name: "CloudGrid sign-in", version: "1.0.0" });
 
 app.onerror = (err) => console.error("[grid-login card]", err);
@@ -96,31 +195,32 @@ els.signin.addEventListener("click", async () => {
     // manually. Never dead-end.
     showAwaitingReturn();
   }
+  // Only NOW — after Open sign-in — do we begin polling. An untouched card is
+  // silent.
+  poller.start();
 });
 
-// Check sign-in: ask the server to finish the flow (grid_login_status). It
-// returns { status, email } and NEVER a token, so the card stays token-free.
+// Check sign-in: the manual escape hatch. It shares queryStatus/onSignedIn with
+// the poller, so it stays available even if polling is throttled, the tab was
+// backgrounded past the ceiling, or the model-context push is unavailable.
 els.check.addEventListener("click", async () => {
+  if (settled) return;
   els.check.disabled = true;
   els.status.textContent = "Checking sign-in.";
-  try {
-    const result = await app.callServerTool({ name: "grid_login_status", arguments: {} });
-    const status = result?.structuredContent?.status;
-    const email = result?.structuredContent?.email;
-    if (status === "authenticated") {
-      els.status.textContent = email ? `Signed in as ${email}.` : "Signed in.";
-      els.signin.hidden = true;
-      els.check.hidden = true;
-    } else {
-      els.status.textContent =
-        "Still waiting for sign-in. Finish on the page that opened, then check again.";
-      els.check.disabled = false;
-    }
-  } catch (err) {
-    console.error("[grid-login card] status check failed", err);
+  const outcome = await queryStatus();
+  if (settled) return;
+  if (outcome.authenticated) {
+    await onSignedIn(outcome.email);
+  } else if (outcome.errored) {
+    els.status.textContent =
+      "Could not check sign-in from here. Complete it in the browser and select Check sign-in.";
+    els.check.disabled = false;
+  } else {
     els.status.textContent =
-      "Could not check sign-in from here. Complete it in the browser and I will continue.";
+      "Still waiting for sign-in. Finish on the page that opened, then check again.";
     els.check.disabled = false;
+    // Keep automatic polling going if it stopped (e.g. after the ceiling).
+    poller.start();
   }
 });
 

package/src/widgets/grid-login/poller.js

@@ -0,0 +1,110 @@
+/**
+ * @file Bounded sign-in poller for the grid_login MCP App (issue #306).
+ *
+ * After the user clicks "Open sign-in", the browser (not the card) performs the
+ * auth, and the card has no way to be told when it finishes — so it polls
+ * grid_login_status. Every poll is a real round-trip to our API, so this loop is
+ * bounded three independent ways and NEVER runs before it is started:
+ *
+ *   • interval  — at most one check every `intervalMs` (never a tight loop)
+ *   • ceiling   — gives up after `ceilingMs` of wall-clock, whatever happens
+ *   • errors    — stops after `maxConsecutiveErrors` failed round-trips in a row
+ *
+ * While the tab is hidden it skips the round-trip (the wall-clock ceiling still
+ * applies, so it always terminates). A card left open in a background tab can
+ * therefore issue at most ceiling/interval requests and then stops for good.
+ *
+ * Every timing/environment dependency is injected so the loop is testable with
+ * fake timers and a fake clock, with no DOM and no ext-apps import. mcp-app.js
+ * wires the real `setTimeout`, `performance.now`, `document.hidden`, and the
+ * grid_login_status round-trip into it. This whole module is bundled inline into
+ * src/widgets/grid-login.html by scripts/build-login-widget.mjs.
+ */
+
+/**
+ * @param {object} deps
+ * @param {number} deps.intervalMs            delay between polls
+ * @param {number} deps.ceilingMs             wall-clock budget before giving up
+ * @param {number} deps.maxConsecutiveErrors  errors in a row before giving up
+ * @param {() => Promise<{authenticated: boolean, email?: string|null, errored: boolean}>} deps.check
+ *        one grid_login_status round-trip, reduced to a plain outcome
+ * @param {(email: string|null|undefined) => (void|Promise<void>)} deps.onSuccess
+ *        called once when authenticated; the poller stops permanently first
+ * @param {() => void} deps.onCeiling         called when the wall-clock ceiling is hit
+ * @param {() => void} deps.onGiveUp          called when consecutive errors hit the cap
+ * @param {() => number} [deps.now]           monotonic clock (defaults to performance.now)
+ * @param {(fn: Function, ms: number) => any} [deps.schedule]  defaults to setTimeout
+ * @param {(handle: any) => void} [deps.cancel]                defaults to clearTimeout
+ * @param {() => boolean} [deps.isHidden]     whether to skip a round-trip this tick
+ */
+export function createPoller({
+  intervalMs,
+  ceilingMs,
+  maxConsecutiveErrors,
+  check,
+  onSuccess,
+  onCeiling,
+  onGiveUp,
+  now = () => performance.now(),
+  schedule = (fn, ms) => setTimeout(fn, ms),
+  cancel = (handle) => clearTimeout(handle),
+  isHidden = () => typeof document !== "undefined" && document.hidden,
+}) {
+  let timer = null;
+  let deadline = 0;
+  let consecutiveErrors = 0;
+  let stopped = false; // permanent once we succeed; blocks any further work
+
+  function armNext() {
+    timer = schedule(tick, intervalMs);
+  }
+
+  function start() {
+    // Idempotent: a manual re-check that resumes polling won't stack loops, and
+    // it cannot restart once we've succeeded.
+    if (stopped || timer !== null) return;
+    deadline = now() + ceilingMs;
+    consecutiveErrors = 0;
+    armNext();
+  }
+
+  function stop() {
+    stopped = true;
+    if (timer !== null) {
+      cancel(timer);
+      timer = null;
+    }
+  }
+
+  async function tick() {
+    timer = null;
+    if (stopped) return;
+    if (now() >= deadline) {
+      onCeiling(); // ceiling: stop; caller keeps the manual fallback on screen
+      return;
+    }
+    if (isHidden()) {
+      armNext(); // don't spend a round-trip while hidden; ceiling still applies
+      return;
+    }
+    const outcome = await check();
+    if (stopped) return;
+    if (outcome.authenticated) {
+      stopped = true;
+      await onSuccess(outcome.email);
+      return;
+    }
+    if (outcome.errored) {
+      consecutiveErrors += 1;
+      if (consecutiveErrors >= maxConsecutiveErrors) {
+        onGiveUp(); // terminal failure: stop, keep the manual path
+        return;
+      }
+    } else {
+      consecutiveErrors = 0;
+    }
+    armNext();
+  }
+
+  return { start, stop, isStopped: () => stopped };
+}