@cloudgrid-io/mcp 0.21.9 → 0.21.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.21.9",
+  "version": "0.21.11",
   "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": {
@@ -31,6 +31,7 @@
     "test:plug-output-schema": "node test/plug-output-schema.test.mjs",
     "test:zip-deploy": "node test/zip-deploy.test.mjs",
     "test:create-gates": "node test/create-gates.test.mjs",
+    "test:plug-create-grid-choice": "node test/plug-create-grid-choice.test.mjs",
     "test:grid-provisioning": "node test/grid-provisioning.test.mjs",
     "test:create-project-args": "node test/create-project-args.test.mjs",
     "test:mcpb-boot": "node test/mcpb-boot.test.mjs",
@@ -69,6 +70,8 @@
     "test:web-identity": "node --test test/web-identity.test.mjs",
     "test:web-auth-integration": "node --test test/web-auth-integration.test.mjs",
     "test:web-restart-recovery": "node --test test/web-restart-recovery.test.mjs",
+    "test:oauth-client-persistence": "node --test test/oauth-client-persistence.test.mjs",
+    "test:oauth-token-exchange": "node --test test/oauth-token-exchange.test.mjs",
     "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",

package/src/oauth.js

@@ -8,15 +8,19 @@
 // then redirect back to the client with an authorization code. /oauth/token
 // exchanges it (PKCE-verified) for the CloudGrid JWT as the access token.
 //
-// No new identity provider. State is in-memory (single replica, like sessions).
+// No new identity provider. Client REGISTRATIONS are stateless (a signed,
+// self-describing client_id — durable across restarts and replicas, see #3060);
+// only the short-lived authorize sessions and auth codes are in-memory.
 
-import { randomUUID, createHash } from "node:crypto";
+import { randomUUID, createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { newLoginCode, buildLoginUrl, pollStatusOnce, decodeJwt } from "./auth.js";
 
 const CODE_TTL_MS = 5 * 60 * 1000; // authorize sessions + auth codes live 5 minutes
 
-// In-memory stores. { [id]: record } with created timestamps for TTL sweeps.
-const clients = new Map(); // client_id -> { redirect_uris }
+// In-memory stores for the SHORT-LIVED, single-flight halves of the flow. These
+// are 5-minute, retry-on-failure sessions: losing them to a restart just means
+// the user clicks "sign in" again, never that they must re-add the connector.
+// Client REGISTRATIONS are NOT here — they are stateless (see below, #3060).
 const authSessions = new Map(); // sid -> { cgCode, client_id, redirect_uri, state, code_challenge, created }
 const authCodes = new Map(); // code -> { jwt, client_id, redirect_uri, code_challenge, created }
 
@@ -29,6 +33,95 @@ function b64url(buf) {
   return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 
+// --- Stateless client registration (#3060) -----------------------------------
+// A `client_id` is a signed token that CARRIES its own redirect-URI set, not a
+// random handle into a process-local Map. Registration signs the (sorted,
+// deduped) set under a server secret; /oauth/authorize verifies by recomputing
+// the HMAC and checking `redirect_uri` against the signed set. This makes
+// registration durable across restarts, deploys, and ANY replica count with no
+// datastore, and removes the old unbounded-growth `clients` Map entirely.
+//
+// PKCE and redirect validation are untouched — if anything stricter: the
+// redirect set is now cryptographically bound into the client_id, so a tampered
+// client_id fails the HMAC and is rejected.
+//
+// SECRET: MCP_OAUTH_HMAC_SECRET, read from env, sourced from a Kubernetes Secret
+// (NEVER a ConfigMap), never logged. It is a whitespace/comma-separated list:
+// the FIRST entry signs, ALL entries verify.
+//
+// ROTATION (rolling-update safe — order matters). Do NOT simply prepend the new
+// secret: during a rollout, new pods would sign under a key the not-yet-updated
+// old pods cannot verify, so authorize returns transient 400s. Instead:
+//   1. APPEND the new secret (last position = verify-only) and deploy. Every pod
+//      now VERIFIES both keys; all pods still SIGN under the old first entry.
+//   2. Once the rollout is complete, PROMOTE the new secret to first position
+//      (the signing slot) and deploy. New client_ids are signed under it; the
+//      old key still verifies outstanding ones.
+//   3. Later, DROP the old key. client_ids minted under it stop verifying and
+//      those users re-add the connector ONCE — the deliberate-rotation cost,
+//      versus today's every-deploy breakage.
+// An attacker who obtains the secret can forge a client_id for an arbitrary
+// redirect set — but /oauth/register already mints one for any redirect set
+// unauthenticated, so the secret gates INTEGRITY, not registration; PKCE +
+// CloudGrid sign-in still gate getting a token.
+const CLIENT_ID_PREFIX = "cg1"; // versioned so the scheme can evolve
+
+// A client_id CARRIES its redirect set and travels in a query string, so the set
+// must stay bounded or the token grows without limit. Caps chosen well above any
+// real client (ChatGPT/Claude register one or two URIs).
+const MAX_REDIRECT_URIS = 10;
+const MAX_REDIRECT_URIS_BYTES = 4096;
+// A configured signing key shorter than this is weak for an HMAC secret; we warn
+// but still accept it — any configured key beats the ephemeral fallback (#3060).
+const MIN_SECRET_LENGTH = 32;
+
+function resolveClientSecrets(env = process.env) {
+  const configured = (env.MCP_OAUTH_HMAC_SECRET || "").split(/[\s,]+/).filter(Boolean);
+  if (configured.length > 0) return { secrets: configured, ephemeral: false };
+  // No configured secret: a per-process ephemeral one. The flow works within a
+  // single process, but registrations do NOT survive a restart — i.e. #3060 is
+  // unfixed. Production MUST set the secret; the boot log states which mode is
+  // active so a deploy can be verified.
+  return { secrets: [randomBytes(32).toString("hex")], ephemeral: true };
+}
+
+// Canonical form the signature covers: sorted + deduped, as JSON.
+function canonicalRedirectUris(uris) {
+  return JSON.stringify([...new Set(uris.map((u) => String(u)))].sort());
+}
+
+function signClientId(canonical, secret) {
+  const payload = b64url(Buffer.from(canonical, "utf8"));
+  const signingInput = `${CLIENT_ID_PREFIX}.${payload}`;
+  const sig = b64url(createHmac("sha256", secret).update(signingInput).digest());
+  return `${signingInput}.${sig}`;
+}
+
+// Verify a client_id against any accepted secret; returns { redirect_uris } or null.
+function verifyClientId(clientId, secrets) {
+  const parts = String(clientId).split(".");
+  if (parts.length !== 3 || parts[0] !== CLIENT_ID_PREFIX) return null;
+  const [, payload, sig] = parts;
+  const signingInput = `${CLIENT_ID_PREFIX}.${payload}`;
+  const given = Buffer.from(sig);
+  let ok = false;
+  for (const secret of secrets) {
+    const expected = Buffer.from(b64url(createHmac("sha256", secret).update(signingInput).digest()));
+    if (expected.length === given.length && timingSafeEqual(expected, given)) {
+      ok = true;
+      break;
+    }
+  }
+  if (!ok) return null;
+  try {
+    const json = Buffer.from(payload.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8");
+    const uris = JSON.parse(json);
+    return Array.isArray(uris) ? { redirect_uris: uris } : null;
+  } catch {
+    return null;
+  }
+}
+
 function corsOk(res) {
   res.setHeader("Access-Control-Allow-Origin", "*");
   res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
@@ -81,6 +174,33 @@ export function mountOAuth(app, publicBase, opts = {}) {
   if (!opts.requireAuth) return;
   const base = publicBase.replace(/\/+$/, "");
 
+  // Resolve the client-registration signing secret(s) once at mount. Log which
+  // mode is active — durable vs. ephemeral — so a production deploy can be
+  // verified from the boot log without ever printing the secret itself.
+  const clientSecrets = resolveClientSecrets();
+  if (clientSecrets.ephemeral) {
+    console.warn(
+      "[oauth] MCP_OAUTH_HMAC_SECRET is NOT set — OAuth client registrations use a per-process " +
+        "ephemeral secret (see #3060). This is NOT just a survives-restart issue: with more than " +
+        "one replica, each process mints under its own key, so a client_id registered on one " +
+        "replica fails on another — authorize breaks intermittently, per request, with no restart " +
+        "involved, which diagnoses as an unrelated bug. Set the secret in production.",
+    );
+  } else {
+    const weak = clientSecrets.secrets.filter((s) => s.length < MIN_SECRET_LENGTH).length;
+    if (weak > 0) {
+      console.warn(
+        `[oauth] MCP_OAUTH_HMAC_SECRET has ${weak} key(s) shorter than ${MIN_SECRET_LENGTH} chars — ` +
+          "weak for an HMAC signing key; use a long random value (e.g. `openssl rand -hex 32`). " +
+          "Accepted anyway (still better than the ephemeral fallback).",
+      );
+    }
+    console.log(
+      `[oauth] client-registration secret configured (${clientSecrets.secrets.length} key(s)); ` +
+        "registrations are durable across restarts and replicas.",
+    );
+  }
+
   const asMetadata = {
     issuer: base,
     authorization_endpoint: `${base}/oauth/authorize`,
@@ -108,11 +228,18 @@ export function mountOAuth(app, publicBase, opts = {}) {
     res.json({ resource: `${base}/mcp`, authorization_servers: [base], scopes_supported: ["cloudgrid"] });
   });
 
-  // RFC 8414.
-  app.get("/.well-known/oauth-authorization-server", (_req, res) => {
+  // RFC 8414. Both the root form and the path-inserted form: the MCP
+  // authorization spec has clients derive the metadata URL from the RESOURCE
+  // url (…/mcp), so a client that tries `/.well-known/oauth-authorization-server/mcp`
+  // first must not get a 404 HTML page. The protected-resource document above
+  // already served both forms; this one served only the root, and the asymmetry
+  // was an oversight rather than a decision.
+  const serveAsMetadata = (_req, res) => {
     corsOk(res);
     res.json(asMetadata);
-  });
+  };
+  app.get("/.well-known/oauth-authorization-server", serveAsMetadata);
+  app.get("/.well-known/oauth-authorization-server/mcp", serveAsMetadata);
 
   // RFC 7591 — dynamic client registration. Public clients, PKCE-only.
   app.post("/oauth/register", (req, res) => {
@@ -122,14 +249,28 @@ export function mountOAuth(app, publicBase, opts = {}) {
       res.status(400).json({ error: "invalid_client_metadata", error_description: "redirect_uris is required." });
       return;
     }
-    const clientId = randomUUID();
-    clients.set(clientId, { redirect_uris: redirectUris, created: Date.now() });
+    if (redirectUris.length > MAX_REDIRECT_URIS) {
+      res.status(400).json({
+        error: "invalid_client_metadata",
+        error_description: `At most ${MAX_REDIRECT_URIS} redirect_uris are allowed.`,
+      });
+      return;
+    }
+    const canonical = canonicalRedirectUris(redirectUris);
+    if (Buffer.byteLength(canonical, "utf8") > MAX_REDIRECT_URIS_BYTES) {
+      res.status(400).json({
+        error: "invalid_client_metadata",
+        error_description: `redirect_uris exceed the ${MAX_REDIRECT_URIS_BYTES}-byte limit.`,
+      });
+      return;
+    }
+    const clientId = signClientId(canonical, clientSecrets.secrets[0]);
     res.status(201).json({
       client_id: clientId,
       token_endpoint_auth_method: "none",
       grant_types: ["authorization_code"],
       response_types: ["code"],
-      redirect_uris: redirectUris,
+      redirect_uris: JSON.parse(canonical),
     });
   });
 
@@ -137,7 +278,7 @@ export function mountOAuth(app, publicBase, opts = {}) {
   app.get("/oauth/authorize", (req, res) => {
     sweep(authSessions);
     const { client_id, redirect_uri, state, code_challenge, code_challenge_method, response_type } = req.query;
-    const client = clients.get(String(client_id));
+    const client = verifyClientId(client_id, clientSecrets.secrets);
     if (!client || !client.redirect_uris.includes(String(redirect_uri))) {
       res.status(400).send("Unknown client or redirect_uri. Re-add the connector and try again.");
       return;
@@ -185,6 +326,9 @@ export function mountOAuth(app, publicBase, opts = {}) {
         created: Date.now(),
       });
       authSessions.delete(String(req.query.sid));
+      // The sign-in half succeeded. Without this line a connector failure gives
+      // no way to tell whether the user ever got through sign-in at all.
+      console.error("[oauth] authorization code issued after sign-in; awaiting token exchange");
       const sep = sess.redirect_uri.includes("?") ? "&" : "?";
       const redirect = `${sess.redirect_uri}${sep}code=${encodeURIComponent(code)}${sess.state ? `&state=${encodeURIComponent(sess.state)}` : ""}`;
       res.json({ status: "ready", redirect });
@@ -198,22 +342,74 @@ export function mountOAuth(app, publicBase, opts = {}) {
   });
 
   // Token endpoint — PKCE-verified exchange; the CloudGrid JWT is the access token.
+  //
+  // WHY THIS BRANCHES INSTEAD OF ONE COMBINED `if`
+  //
+  // Reported 2026-08-30: ChatGPT web fails with "Something went wrong with
+  // setting up the connection" AFTER the user signs in, which puts the failure
+  // in this handler. It could not be diagnosed from either side, because five
+  // unrelated causes all produced a byte-identical `{"error":"invalid_grant"}`:
+  //
+  //   unknown/expired code · code already exchanged · client_id absent
+  //   · client_id mismatched · redirect_uri mismatched (a trailing slash does it)
+  //
+  // All five were reproduced against this handler (test/oauth-token-exchange).
+  // Nothing was logged, so the server could not say which happened either — the
+  // failure was invisible from both ends at once. That is the actual defect
+  // being fixed here: not the rejection, which is correct in every one of those
+  // cases, but that a rejection carried no information.
+  //
+  // The reason is logged server-side and returned as `error_description`. The
+  // caller already holds the code, the client_id and the redirect_uri it sent,
+  // so naming which of ITS OWN values did not match tells it nothing it did not
+  // already know. The token, the verifier and the code are never logged.
+  //
+  // THE TRADE, NAMED (so nobody extends this pattern by accident): branching
+  // these messages does hand a holder of an EXFILTRATED code a small oracle —
+  // they can confirm the code is live and probe client_id / redirect_uri
+  // without spending a PKCE guess. Accepted here because the code is
+  // single-use, dies in 5 minutes, and PKCE still gates the token, so the
+  // oracle reveals only values the attacker would have to have already; and
+  // RFC 6749 §5.2 explicitly provides error_description for this purpose. That
+  // reasoning is specific to this endpoint. Do NOT copy the pattern somewhere
+  // a failed attempt is cheap to repeat or the compared value is a secret.
+  const denyToken = (res, error, reason, detail = "") => {
+    console.error(`[oauth] token exchange refused: ${reason}${detail ? ` ${detail}` : ""}`);
+    res.status(400).json({ error, error_description: reason });
+  };
+
   app.post("/oauth/token", (req, res) => {
     corsOk(res);
     sweep(authCodes);
     const { grant_type, code, code_verifier, redirect_uri, client_id } = req.body ?? {};
     if (grant_type !== "authorization_code") {
-      res.status(400).json({ error: "unsupported_grant_type" });
+      denyToken(res, "unsupported_grant_type", "grant_type must be authorization_code", `(got ${JSON.stringify(grant_type ?? null)})`);
       return;
     }
     const rec = authCodes.get(String(code));
-    if (!rec || rec.client_id !== String(client_id) || rec.redirect_uri !== String(redirect_uri)) {
-      res.status(400).json({ error: "invalid_grant" });
+    if (!rec) {
+      // Also the retry case: codes are single-use, so a second exchange of a
+      // code that already succeeded lands here.
+      denyToken(res, "invalid_grant", "authorization code is unknown, expired or already exchanged");
+      return;
+    }
+    if (rec.client_id !== String(client_id)) {
+      denyToken(
+        res,
+        "invalid_grant",
+        client_id === undefined ? "client_id is required at the token endpoint" : "client_id does not match the one the code was issued to",
+      );
+      return;
+    }
+    if (rec.redirect_uri !== String(redirect_uri)) {
+      // The exact strings, because the difference is usually invisible —
+      // a trailing slash, a case change, an added query parameter.
+      denyToken(res, "invalid_grant", "redirect_uri does not match the authorize request", `(sent ${JSON.stringify(redirect_uri ?? null)}, expected ${JSON.stringify(rec.redirect_uri)})`);
       return;
     }
     const challenge = b64url(createHash("sha256").update(String(code_verifier ?? "")).digest());
     if (challenge !== rec.code_challenge) {
-      res.status(400).json({ error: "invalid_grant", error_description: "PKCE verification failed." });
+      denyToken(res, "invalid_grant", code_verifier === undefined ? "code_verifier is required (PKCE)" : "PKCE verification failed");
       return;
     }
     authCodes.delete(String(code)); // single use

package/src/tools/deploy.js

@@ -104,7 +104,15 @@ export async function fetchUserOrgs(token) {
 //   - >1 grid and none supplied           → { picker } (a ready-to-return result)
 //   - exactly one grid                    → { single: annotatedOrg } — the caller
 //         decides how to treat a not-ready single grid (drop blocks; plug warns)
-//   - no orgs / listing failed            → { proceed: true } (fall through)
+//   - no orgs / listing failed            → { picker } needs_grid_create (asks)
+// Every return shape either ASKS (a picker) or names an explicit grid — none is a
+// silent proceed. That is load-bearing: register.js returns the picker or sets
+// input.grid from `grid`/`single` before runPlug, so the create path never
+// reaches runPlug's headerless fallback (#327). Do NOT reintroduce a
+// `{ proceed: true }` "fall through" shape here — a proceed with NO grid slips
+// past register.js without setting input.grid, into an ungated runPlug where
+// orgSlug is null and the SERVER picks the grid silently: exactly the wrong-grid
+// create this PR removed. A listing failure must ASK, never fall through.
 // User-facing text says "grid" (Gilad's org→grid rename); the structured payload
 // carries `needs_grid` AND the `needs_org`/`orgs`/`org`-slug fields the existing
 // org-picker web widget reads, so the web card keeps working. Stateless — no
@@ -1838,13 +1846,42 @@ export async function runPlug(ctx, input, deps = {}) {
     //      through — never a silent redirect.
     //   4. the target entity itself      — a pickup round-trip, only if 1–3 all
     //      came up empty. Reuse a pickup already done above to resolve the id.
-    orgSlug = grid || (await ctx.getActiveGrid());
-    if (!orgSlug) orgSlug = gridFromCloudgridUrl(targetUrl);
-    if (!orgSlug && isEdit) {
-      if (!pickupData && targetEntityId) {
-        pickupData = await resolveEntityViaPickup(ctx, { target: targetEntityId });
+    if (isEdit) {
+      // EDIT: the destination is NOT ambiguous — the entity already lives in
+      // exactly one grid, so derive it (never ask). explicit `grid` → active
+      // grid → URL host → entity lookup (#296/#301/#316). This chain must stay
+      // intact: re-asking on every re-plug is noise and would undo those fixes.
+      orgSlug = grid || (await ctx.getActiveGrid());
+      if (!orgSlug) orgSlug = gridFromCloudgridUrl(targetUrl);
+      if (!orgSlug) {
+        if (!pickupData && targetEntityId) {
+          pickupData = await resolveEntityViaPickup(ctx, { target: targetEntityId });
+        }
+        if (pickupData?.grid) orgSlug = pickupData.grid;
       }
-      if (pickupData?.grid) orgSlug = pickupData.grid;
+    } else {
+      // CREATE (#327): the destination grid is the USER'S CHOICE and must be
+      // EXPLICIT — never silently reuse the persisted active grid. A stale
+      // active grid (weeks old, not surfaced to the user) silently lands a NEW
+      // entity in the wrong grid, and the grid decides the URL, who can open it
+      // (grid-scoped visibility), the datastore tier it inherits, and the
+      // namespace it runs in.
+      //
+      // What makes this safe is the grid-picker gate — resolveGridOrAsk (defined
+      // above; called from register.js): it either ASKS (returns a picker) or
+      // sets input.grid to an explicit slug (the single grid, or the user's
+      // choice) BEFORE runPlug runs. So on the real create path `grid` is always
+      // populated here.
+      //
+      // `null` is NOT a backstop — it is the DEFECT value. A headerless authed
+      // create does not refuse; it delegates the choice to the server, which
+      // resolves a default and picks a grid silently (the hosted half of this
+      // bug). The only reason a null is ever safe is that the gate above never
+      // lets an unresolved authed create reach here. Refusing on null (returning
+      // needs_grid instead of proceeding) is the stronger fix, tracked as a #327
+      // follow-up — do NOT rely on `orgSlug = grid || null` alone to prevent a
+      // wrong-grid create.
+      orgSlug = grid || null;
     }
     // Grid-native header + X-CloudGrid-Org alias (same slug) during the soak.
     if (orgSlug) {
@@ -2230,16 +2267,32 @@ export async function runPlug(ctx, input, deps = {}) {
     lines.push("The owner_token was re-minted for the reset expiry — replace the stored one.");
   }
 
+  // Point the user at their grid (the console) after a deploy that is LIVE — new
+  // or re-plug (#321). The app URL says where the app lives; the console line says
+  // where the grid lives, so the common follow-up interaction (an edit) does not
+  // end with a bare URL and no way back. The console root self-routes per account
+  // state (sign-in wall → their grid → onboarding); there is no per-grid page to
+  // link, so keep the root — a `/grids/<slug>` path 404s today.
+  //
+  // NOT on the building branch: the line says "view it live", and a still-building
+  // app is not live — emitting it two lines under "Do NOT tell the user it is live"
+  // would hand a model the word "live" next to a pending app. For an async runtime
+  // build the console line arrives when liveness is confirmed, in runCheckDeploy's
+  // success branch.
+  if (data.entity_id && !isBuilding) {
+    structured.console_url = CONSOLE_URL;
+    lines.push(`You can view it live in your grid along with all the apps you build here: ${CONSOLE_URL}`);
+  }
+
   // Visibility is the user's choice — never set silently. On a NEW deploy,
   // surface the current visibility + the full option set and have the agent ASK
   // the user, then apply their answer via grid_visibility. On an edit, leave the
-  // entity's existing visibility untouched (don't re-ask on every re-plug).
+  // entity's existing visibility untouched (don't re-ask on every re-plug) — this
+  // stays `!isEdit` deliberately, decoupled from the console line above.
   if (!isEdit && data.entity_id) {
     const current = typeof data.visibility === "string" ? data.visibility : null;
-    structured.console_url = CONSOLE_URL;
     if (current) structured.current_visibility = current;
     structured.visibility_options = VISIBILITY_OPTIONS.map((v) => ({ value: v, label: VISIBILITY_LABELS[v] }));
-    lines.push(`Manage all your apps in your grid: ${CONSOLE_URL}`);
     lines.push(
       `Now ASK the user who should be able to open this${current ? ` (currently ${VISIBILITY_LABELS[current] ?? current})` : ""}, then set their choice with grid_visibility — do not decide it for them. Options: ${
         VISIBILITY_OPTIONS
@@ -2717,8 +2770,12 @@ export async function runCheckDeploy(ctx, { poll_url, grid } = {}) {
   const url = ctx.state.lastDrop?.url;
   if (verdict.status === "success") {
     return {
-      text: `Live${url ? `: ${url}` : ""} — the build finished. Give the user the URL.`,
-      structured: { status: "success", live: true, ...(url ? { url } : {}) },
+      // The "now live" moment for an async runtime build lands here, not in
+      // runPlug (which returned "building"). Point the user at their grid too
+      // (#321) — this is where liveness is confirmed, so "view it live" is true.
+      text: `Live${url ? `: ${url}` : ""} — the build finished. Give the user the URL.\n` +
+        `You can view it live in your grid along with all the apps you build here: ${CONSOLE_URL}`,
+      structured: { status: "success", live: true, ...(url ? { url } : {}), console_url: CONSOLE_URL },
     };
   }
   if (verdict.status === "failed") {

package/src/tools/register.js

@@ -396,9 +396,15 @@ export function registerTools(server, ctx) {
       "Re-plugging an anonymously-created drop needs its owner_token instead of sign-in.",
     ),
     grid: z.string().optional().describe(
-      "On create: the grid slug to plug into (omit to use the caller's active grid). On re-plug the entity " +
-      "never moves grids, but pass its home grid here when it differs from your active grid (the API " +
-      "checks your membership in the entity's grid). Anonymous → always the Guest grid.",
+      "On create: the grid slug to plug into. The destination grid is the USER'S CHOICE — treat it like " +
+      "visibility: NEVER infer one silently, and never reuse a previous or active grid without the user. If " +
+      "the user has more than one grid, CONFIRM which grid before plugging (omit this and grid_plug returns " +
+      "needs_grid with the grid list to choose from); a single-grid user is not asked. State the destination " +
+      "in the user's own terms (\"plugging into <grid>\") BEFORE the entity is created — a new entity in the " +
+      "wrong grid gets the wrong URL, is exposed to the wrong grid's members, and inherits the wrong datastore " +
+      "tier and namespace, and that is expensive to catch after the fact. On re-plug the entity never moves " +
+      "grids, but pass its home grid here when it differs from your active grid (the API checks your " +
+      "membership in the entity's grid). Anonymous → always the Guest grid.",
     ),
     slug: z.string().optional().describe(
       "Alternative RE-PLUG handle: paired with `grid`, resolves to an existing entity (the pickup " +
@@ -453,6 +459,10 @@ export function registerTools(server, ctx) {
         "Without target_entity_id: CREATE a new entity with a new URL. " +
         "With target_entity_id (or grid+slug): UPDATE the existing deployment IN PLACE, keeping the same URL — " +
         "this is the only deploy/publish tool, so do not look for a separate 'update' or 'redeploy' tool. " +
+        "GRID CHOICE (new plug): the destination grid is the user's choice, like visibility — do NOT infer or " +
+        "reuse a grid silently. For a user with more than one grid, CONFIRM which grid before plugging (omit " +
+        "`grid` and grid_plug returns needs_grid to ask); a single-grid user is not asked. State the " +
+        "destination before the entity is created. On re-plug the grid is fixed by the entity — never re-asked. " +
         "Sources (pass exactly one): `html` — a single self-contained HTML page (instant, any edition)" +
         (ctx.edition === "web"
           ? " or `artifact_files` — a multi-file app inline. "
@@ -845,6 +855,7 @@ export function registerTools(server, ctx) {
         status: z.string().describe("The build status: success | failed | building | queued | unknown."),
         live: z.boolean().describe("True only when the build finished successfully and the URL serves."),
         url: z.string().optional().describe("The live URL, when known."),
+        console_url: z.string().optional().describe("On success: URL to view the app live in the grid alongside all the user's apps."),
         error: z.string().optional().describe("User-language failure reason, when the build failed."),
         build_log_tail: z.string().optional().describe("Sanitized tail of the Cloud Build log (the real error), when the build failed."),
         suggested_fix: z.string().optional().describe("A suggested fix for the failure, when the platform provides one."),