@cloudgrid-io/mcp 0.20.53 → 0.20.55

package/src/corpus/templates/project-management/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-project-board
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/property-listings/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: property-listings
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/quiz-platform/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: quiz-platform
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/report/cloudgrid.yaml

@@ -25,7 +25,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: report
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/restaurant-reservations/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: restaurant-reservations
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/revenue-dashboard/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: revenue-dashboard
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/saas-marketing/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: saas-marketing
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/semantic-search/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: semantic-search
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/simple-semantic-search/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: simple-semantic-search
 description: Semantic search over a bundled document, backed by pgvector.
 icon: "🔎"

package/src/corpus/templates/status-page/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: status-page
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/subscription-management/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: subscription-management
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/task-manager/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-tasks
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/ticket-system/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-tickets
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/time-tracking/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: time-tracking
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/travel-booking/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: travel-booking
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/waitlist/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: waitlist
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/web-app/cloudgrid.yaml

@@ -25,7 +25,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: web-app
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/session-logger.js

@@ -122,7 +122,10 @@ export class SessionLogger {
     this.startedMs = now();
     this.calls = [];
     this.header = null;
-    this.userRequest = userRequest ? scrubText(userRequest) : null;
+    // Scrub FIRST, then cap — same rationale as setUserRequest (:252-253): an
+    // uncapped value (the CLOUDGRID_USER_REQUEST path) would push the whole trail
+    // past the Slack 38KB clip. Both entry points now agree on the 2000 cap.
+    this.userRequest = userRequest ? scrubText(userRequest).slice(0, 2000) : null;
     this.narrative = null;
     this.flushed = false;
     this.idleTimer = null;

package/src/tools/deploy.js

@@ -160,12 +160,33 @@ export async function runCreateGrid(ctx, { slug, name } = {}) {
     };
   }
   const finalSlug = data.slug ?? s;
+  // A brand-new grid provisions its infrastructure in the background: the API
+  // returns 202 with { status: "provisioning", poll_url } while the org's infra
+  // (bucket/GSA/WI/K8s) is still being set up. Until it is ready, an
+  // infra-dependent write (grid_plug) is refused with 409 ORG_PROVISIONING.
+  // There is no read endpoint that reports this readiness (render_ready and
+  // /orgs/:slug/status.ready are hardwired true under the flat-arch decision),
+  // so we do NOT instruct an immediate re-call that would fail: instead we say
+  // the grid is finishing setup and that grid_plug itself waits for readiness
+  // (it retries ORG_PROVISIONING for a bounded budget) before it deploys. Issue #235.
+  const provisioning = res.status === 202 || data.status === "provisioning" || Boolean(data.poll_url);
   const lines = [`Created grid ${finalSlug} — the user is its admin.`];
-  if (data.poll_url) lines.push("Its TLS certificate is still provisioning, so the first page may take a minute to serve.");
-  lines.push(`Now re-call grid_plug with grid: ${finalSlug}.`);
+  if (provisioning) {
+    lines.push(
+      "It's finishing setup in the background — a brand-new grid provisions its infrastructure, usually within ~30s. " +
+        `Go ahead and call grid_plug with grid: ${finalSlug}: it waits for the grid to be ready, then deploys. ` +
+        "You do NOT need to poll a status or insert a manual delay, and calling it right away will not fail — it holds until the grid is ready.",
+    );
+  } else {
+    lines.push(`The grid is ready — call grid_plug with grid: ${finalSlug} to deploy.`);
+  }
   return {
     text: lines.join("\n"),
-    structured: { created: true, grid: { slug: finalSlug, name: data.name ?? String(name || s) } },
+    structured: {
+      created: true,
+      ...(provisioning ? { provisioning: true } : {}),
+      grid: { slug: finalSlug, name: data.name ?? String(name || s) },
+    },
   };
 }
 
@@ -186,6 +207,7 @@ const SECRET_PATTERNS = [
   [/github_pat_[A-Za-z0-9_]{30,}/, "a GitHub fine-grained token"],
   [/AKIA[0-9A-Z]{16}/, "an AWS access key id"],
   [/xox[baprs]-[A-Za-z0-9-]{10,}/, "a Slack token"],
+  [/\bsk_(?:live|test)_[0-9A-Za-z]{16,}\b/, "a Stripe secret key"],
 ];
 
 export function scanInlineSecrets(text) {
@@ -312,13 +334,17 @@ const GUEST_ORG_SLUG = "guest";
 // path (create + edit, anon + authed) — flat-arch-aware per grid, matching the
 // host that actually serves. ALWAYS prefer `data.url` (see resolvePlugUrl);
 // this client-side derivation exists only for the rare response where `url`
-// came back empty (the server composes it best-effort). It mirrors the legacy
-// `entityUrl()` rules and is WRONG on flat-arch grids (which serve
-// `<slug>--<grid>.cloudgrid.io`), so it must never be the primary source:
+// came back empty (the server composes it best-effort). It mirrors the canonical
+// `entityUrl()` rules (the flat-only platform host), but only the server knows
+// the per-entity nuances (custom domains, guest-org placement), so it must never
+// be the primary source:
 //   - inspiration (HTML drops): path-based at the org apex
 //       https://<grid>.cloudgrid.io/<slug>
-//   - runtime (app/agent):      subdomain
-//       https://<slug>.<grid>.cloudgrid.io
+//   - runtime (app/agent):      flat platform host
+//       https://<slug>--<grid>.cloudgrid.io
+// The old nested `<slug>.<grid>.cloudgrid.io` host is retired — it falls outside
+// the single `*.cloudgrid.io` platform wildcard, so it has no cert and no ingress
+// (matches `composeFlatEntityHost`).
 // Anonymous drops are grid-less in the response (`grid: null`); they live under
 // the Guest Org, so the apex slug is the constant `guest`.
 function composePlugUrl(data) {
@@ -327,7 +353,7 @@ function composePlugUrl(data) {
   const grid = data?.grid || GUEST_ORG_SLUG;
   const kind = data?.detection?.kind;
   if (kind === "app" || kind === "agent") {
-    return `https://${slug}.${grid}.cloudgrid.io`;
+    return `https://${slug}--${grid}.cloudgrid.io`;
   }
   // inspiration (and any unknown/static kind) — path-based at the org apex.
   return `https://${grid}.cloudgrid.io/${slug}`;
@@ -433,7 +459,8 @@ const REPORT_SECRET_KEY_PATTERNS = [
 
 // Light client-side scrub of obviously secret-looking values in the report
 // context. Redacts values under secret-looking KEYS; leaves everything else
-// intact (the server does the authoritative redaction). Bounded depth so a
+// intact (the server applies the same key-name filter, not a value-based one —
+// a secret embedded in a value transits unredacted). Bounded depth so a
 // pathological object can't loop.
 export function scrubReportContext(obj, depth = 0) {
   if (depth > 5 || obj === null || typeof obj !== "object") return obj;
@@ -459,8 +486,8 @@ export function scrubReportContext(obj, depth = 0) {
 // source (mcp-stdio | mcp-hosted), client (the calling agent from MCP clientInfo),
 // platform, mcp_version. Sent BOTH as top-level fields AND mirrored in
 // `context.origin`. The POST /errors handler only persists known top-level keys
-// (it drops unknown ones), and `context` is stored + secret-stripped server-side,
-// so `context.origin` is the durable carrier — belt-and-suspenders.
+// (it drops unknown ones), and `context` is stored after the server's key-name
+// scrub, so `context.origin` is the durable carrier — belt-and-suspenders.
 //
 // Auth: signed-in → Bearer; anon+web → the trusted-server headers (works once the
 // endpoint accepts the credential; until then a 401 degrades to "sign in to
@@ -607,8 +634,9 @@ export async function runReport(
 // grid_pull — continue/edit an existing entity IN PLACE (POST /entities/:id/pickup).
 // Like `git clone` of the SAME entity: your next grid_plug (target_entity_id)
 // updates it. Needs push access — you must OWN it or be a COLLABORATOR. A
-// view-only caller is told they can't edit/plug it (make a copy with grid_pickup,
-// or request collaborator access with the CLI `grid collab`). A claim_token also
+// view-only caller is told they can't edit/plug it (fork a copy with grid_pickup,
+// or GET collaborator push access with the CLI `grid collab` — grants permission
+// only, pull again once granted). A claim_token also
 // claims an anonymous drop into your account (ownership transfer).
 export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
   const token = await ctx.getToken();
@@ -701,8 +729,9 @@ export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
       return {
         text:
           `You don't have push access to this entity, so you can't edit or plug it. Two options: ` +
-          `make your own separate copy with grid_pickup, or ask the owner for collaborator access with the CLI ` +
-          `\`grid collab <entity>\` (rolling out soon) and pull again once granted.`,
+          `make your own separate copy (a fork) with grid_pickup, or GET collaborator push access to the SAME ` +
+          `entity with the CLI \`grid collab <entity>\` — that grants permission only and fetches nothing, so ` +
+          `pull again once it is granted (if the owner gates access, \`grid collab\` becomes a request they approve).`,
         structured: { can_edit: false, owner_is_you: false, access: "view_only" },
       };
     }
@@ -729,7 +758,7 @@ export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
     head = `You have collaborator push access to ${slug}${where} — your next grid_plug (target_entity_id) updates the SHARED entity; the team sees the new version and can roll it back.`;
     canEdit = true;
   } else {
-    head = `You can view ${slug}${where} but do NOT have push access — you can't edit or plug it. Make your own copy with grid_pickup, or request collaborator access with the CLI \`grid collab ${slug}\` (rolling out soon), then pull again.`;
+    head = `You can view ${slug}${where} but do NOT have push access — you can't edit or plug it. Make your own separate copy (a fork) with grid_pickup, or GET collaborator push access to the SAME entity with the CLI \`grid collab ${slug}\` (it grants permission only and fetches nothing — pull again once granted).`;
     canEdit = false;
   }
   const lines = [head];
@@ -1086,6 +1115,16 @@ export function errorGuidance({ status, code, edition, isEdit, isAnon, signedIn
       "If the user is signed in, use the signed-in path instead of anonymous."
     );
   }
+  // 409 ORG_PROVISIONING — the target grid's infrastructure is still being set
+  // up (async org provisioning), so an infra-dependent write (plug) is refused
+  // for now. This is DISTINCT from EDIT_REJECTED below and must be checked first:
+  // it is time-bounded and retryable, not a rejected re-plug. runPlug retries it
+  // internally with a bounded budget; this guidance is the budget-exhausted tail,
+  // so the wording tells the agent to wait and re-call rather than surface a raw
+  // code. (Issue #235.)
+  if (status === 409 && code === "ORG_PROVISIONING") {
+    return "The grid is still finishing setup — a brand-new grid provisions its infrastructure in the background (usually within ~30s). Wait ~15s and call grid_plug again with the SAME parameters; it deploys once the grid is ready. Do not switch to anonymous and do not send the user to the console.";
+  }
   // 409 EDIT_REJECTED — an in-place re-plug the server won't take.
   if (status === 409) {
     return "The entity cannot be updated right now (a plug is in progress, or it is archived/expired/claimed). An explicit re-plug never silently creates; retry later, or omit target_entity_id to create a new entity.";
@@ -1464,6 +1503,9 @@ export async function runPlug(ctx, input, deps = {}) {
   }
 
   // ── Wire assembly ───────────────────────────────────────────────────────────
+  // Built fresh per attempt: the ORG_PROVISIONING retry loop below re-POSTs, and
+  // a FormData body is consumed by a send, so each attempt needs its own.
+  const buildForm = () => {
   const form = new FormData();
   for (const a of artifacts) {
     // Folder-walk / artifact_files parts ride as octet-stream (server sniffs by
@@ -1504,32 +1546,84 @@ export async function runPlug(ctx, input, deps = {}) {
     form.append("hints_kind", hints.kind);
   }
   if (hints?.yaml) form.append("hints_yaml", hints.yaml);
+  return form;
+  };
 
-  let res;
-  try {
-    res = await fetchImpl(`${API_BASE}/api/v2/plug`, {
-      method: "POST",
-      headers,
-      body: form,
-      signal: AbortSignal.timeout(uploadTimeoutMs),
-    });
-  } catch (err) {
-    if (err?.name === "AbortError" || err?.name === "TimeoutError") {
-      throw new Error(
-        `The plug request timed out after ${Math.round(uploadTimeoutMs / 1000)}s. ` +
-          `The build may still be running on CloudGrid — check the build status ` +
-          `(poll_url / grid_status, or your grid) before plugging again, so you don't create a duplicate.`,
+  // One POST attempt: assemble a fresh body, send, read + parse. Kept as a
+  // closure so the ORG_PROVISIONING retry loop can re-run it (issue #235).
+  const sendPlug = async () => {
+    let res;
+    try {
+      res = await fetchImpl(`${API_BASE}/api/v2/plug`, {
+        method: "POST",
+        headers,
+        body: buildForm(),
+        signal: AbortSignal.timeout(uploadTimeoutMs),
+      });
+    } catch (err) {
+      if (err?.name === "AbortError" || err?.name === "TimeoutError") {
+        throw new Error(
+          `The plug request timed out after ${Math.round(uploadTimeoutMs / 1000)}s. ` +
+            `The build may still be running on CloudGrid — check the build status ` +
+            `(poll_url / grid_status, or your grid) before plugging again, so you don't create a duplicate.`,
+        );
+      }
+      throw new Error(`Could not reach CloudGrid at ${API_BASE}: ${err.message}`);
+    }
+    const raw = await res.text();
+    let data = null;
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      /* handled below */
+    }
+    return { res, raw, data };
+  };
+
+  // ── ORG_PROVISIONING retry (issue #235) ─────────────────────────────────────
+  // A plug into a brand-new grid whose infra is still provisioning is refused
+  // with 409 ORG_PROVISIONING. That write 409 is the ONLY signal that the grid
+  // is not yet ready (no read endpoint reports it), so the plug IS the readiness
+  // probe: retry the POST with a light backoff until it clears or the budget
+  // runs out. A terminal 'failed' provisioning (hint says setup did not
+  // complete) is NOT retried — it won't recover on its own. The wait is a
+  // bounded server-side block matching the deploy-poll liveness pattern already
+  // used after a create; the caller sees one honest result, never a raw code.
+  const sleep = deps.sleep || sleepMs;
+  const provisionBudgetMs = ctx.plugProvisionBudgetMs ?? PLUG_PROVISION_RETRY_BUDGET_MS;
+  const provisionBaseMs = ctx.plugProvisionIntervalMs ?? PLUG_PROVISION_RETRY_BASE_MS;
+  const provisionMaxMs = ctx.plugProvisionMaxMs ?? PLUG_PROVISION_RETRY_MAX_MS;
+  const provisionStart = Date.now();
+  let attempt = 0;
+  let res, raw, data;
+  for (;;) {
+    ({ res, raw, data } = await sendPlug());
+    if (res.ok) break;
+    if (res.status === 409 && data?.error?.code === "ORG_PROVISIONING") {
+      const hint = data?.error?.details?.[0]?.hint || "";
+      // Terminal failure — provisioning did not complete; retrying is futile.
+      if (/did not (complete|finish)/i.test(hint)) {
+        throw new Error(
+          `The grid "${orgSlug || grid || "your grid"}" did not finish provisioning, so it can't accept a deploy. ${hint} ` +
+            "This won't recover on its own from here — the grid likely needs to be recreated (grid_create_grid with a new slug), or an admin must retry provisioning.",
+        );
+      }
+      const delay = Math.min(
+        provisionMaxMs,
+        Math.round(provisionBaseMs * Math.pow(1.5, attempt)),
       );
+      if (Date.now() - provisionStart + delay <= provisionBudgetMs) {
+        attempt += 1;
+        await sleep(delay);
+        continue;
+      }
+      // Budget exhausted — fall through to the error handler, which appends the
+      // ORG_PROVISIONING guidance (errorGuidance): honest "still setting up,
+      // wait and re-call", never the raw code or the EDIT_REJECTED wording.
     }
-    throw new Error(`Could not reach CloudGrid at ${API_BASE}: ${err.message}`);
-  }
-  const raw = await res.text();
-  let data = null;
-  try {
-    data = JSON.parse(raw);
-  } catch {
-    /* handled below */
+    break;
   }
+
   if (!res.ok) {
     const code = data?.error?.code;
     const msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
@@ -1890,6 +1984,13 @@ export async function runVisibility(ctx, { target, visibility, inside, outside,
     if (!inside || !outside) {
       throw new Error("Both axes are required: inside (private|spaces|grid) and outside (none|link|public).");
     }
+    if (indexed === true) {
+      // Search-indexing is the axis value `outside: public`, not a separate
+      // flag. Accepting `indexed` here and building the body without it would
+      // silently drop it (the exact accept-and-ignore class #2326 closes).
+      // Mirror the CLI (visibility.ts:375-379): reject, point at the axis value.
+      throw new Error("indexed does not apply with inside/outside. Use outside: public for a search-indexed link.");
+    }
     if (inside === "spaces" && normSpaces.length === 0) {
       throw new Error("inside: spaces needs at least one space slug in `spaces`.");
     }
@@ -1914,20 +2015,65 @@ export async function runVisibility(ctx, { target, visibility, inside, outside,
     }
     if (mode === "public") mode = "link"; // alias; `indexed: true` governs search-indexing
     if (mode === "authenticated") {
-      // Retired as a first-class mode — the axis body it equals.
+      // Retired as a first-class mode — the axis body it equals
+      // (private + link + require_signin). Its param guards MUST match that
+      // combo (below): a sign-in-gated link can be neither search-indexed nor
+      // space-scoped, so `indexed`/`spaces` here must throw, not be dropped.
+      if (indexed === true) {
+        throw new Error("require_signin cannot combine with indexed: a sign-in-gated link cannot be search-indexed.");
+      }
+      if (normSpaces.length > 0) {
+        throw new Error("`spaces` only applies with visibility: grid (or inside: spaces).");
+      }
       body = { share_scope: "private", external_access: "link", require_signin: true };
       requested = "link with sign-in required (the retired 'authenticated')";
     } else if (mode === "space") {
+      // `space` is a pure internal audience (share_scope: spaces, external_access:
+      // none). require_signin/indexed are external-link concerns — they have no
+      // cell here, so reject rather than silently ignore (same defect class).
+      if (require_signin === true) {
+        throw new Error("require_signin only applies with visibility: link (or outside: link).");
+      }
+      if (indexed === true) {
+        throw new Error("`indexed` only applies with visibility: link.");
+      }
       if (normSpaces.length === 0) {
         throw new Error("'space' visibility needs the `spaces` list (which space slugs can see it) — or use inside: spaces with outside: none.");
       }
       body = { share_scope: "spaces", external_access: "none", visibility_spaces: normSpaces };
       requested = `selected spaces (${normSpaces.join(", ")})`;
     } else if (mode === "private" || mode === "grid" || mode === "link") {
-      body = { visibility: mode };
-      if (mode === "grid" && normSpaces.length > 0) body.visibility_spaces = normSpaces;
-      if (mode === "link") body.link_indexed = indexed === true;
-      requested = mode + (mode === "link" && indexed === true ? " (search-indexed)" : "");
+      if (require_signin === true && mode !== "link") {
+        throw new Error("require_signin only applies with visibility: link (or outside: link).");
+      }
+      if (indexed === true && mode !== "link") {
+        throw new Error("`indexed` only applies with visibility: link.");
+      }
+      if (normSpaces.length > 0 && mode !== "grid") {
+        throw new Error("`spaces` only applies with visibility: grid (or inside: spaces).");
+      }
+      if (mode === "link" && require_signin === true) {
+        // A sign-in-gated link is the axis cell (private, link, require_signin);
+        // search-indexing is the (·, public) cell. The two are mutually
+        // exclusive: the server's axis body has NO representable state for both.
+        // `link_indexed` on an axis body is silently DISCARDED —
+        // validateAxisBody (packages/shared/src/visibility-write.ts:113) never
+        // reads it and AxisBody (:23) has no such field, and
+        // axesToLegacyVisibility (:78) for (private, link, require_signin)
+        // returns { visibility: 'authenticated' } with no link_indexed. So the
+        // server resolves link_indexed to null and drops `indexed`. Reject the
+        // combination rather than forward a key the server throws away.
+        if (indexed === true) {
+          throw new Error("require_signin cannot combine with indexed: a sign-in-gated link cannot be search-indexed.");
+        }
+        body = { share_scope: "private", external_access: "link", require_signin: true };
+        requested = "link with sign-in required";
+      } else {
+        body = { visibility: mode };
+        if (mode === "grid" && normSpaces.length > 0) body.visibility_spaces = normSpaces;
+        if (mode === "link") body.link_indexed = indexed === true;
+        requested = mode + (mode === "link" && indexed === true ? " (search-indexed)" : "");
+      }
     } else {
       throw new Error(`Unknown visibility '${visibility}'. Use private | grid | link (public = link alias), or the inside/outside axes.`);
     }
@@ -2028,6 +2174,21 @@ const DEPLOY_POLL_BUDGET_MS = 45_000;
 const DEPLOY_POLL_INTERVAL_MS = 3_000;
 const sleepMs = (ms) => new Promise((r) => setTimeout(r, ms));
 
+// ── Provisioning retry budget (issue #235) ──────────────────────────────────
+// A plug into a brand-new grid is refused with 409 ORG_PROVISIONING until the
+// grid's infra finishes provisioning (field estimate ~15-30s; the platform's
+// own default remaining-time estimate is 30s). Since the ONLY signal that the
+// grid can accept a plug is this write 409 (no read endpoint reports it), the
+// plug retries the write with a light backoff until it clears or the budget
+// runs out. Budget = 45s, matching DEPLOY_POLL_BUDGET_MS — a value the MCP
+// client already tolerates within a single plug call (that post-create deploy
+// poll blocks up to 45s today), and comfortably inside PLUG_UPLOAD_TIMEOUT_MS
+// (120s). The guard rejects BEFORE parsing the upload body (plug.ts), so a
+// retry is cheap server-side.
+const PLUG_PROVISION_RETRY_BUDGET_MS = 45_000;
+const PLUG_PROVISION_RETRY_BASE_MS = 2_000;
+const PLUG_PROVISION_RETRY_MAX_MS = 8_000;
+
 // GET one deploy-trace snapshot. Returns { status, error } — status is the
 // server's word ("queued"/"building"/"success"/"failed"), error is the
 // user-language message when failed. Throws only on a non-OK HTTP response.