@cloudgrid-io/mcp 0.21.13 → 0.21.15

package/README.md

@@ -84,7 +84,7 @@ posted). `CLOUDGRID_QA_IDLE_MS` overrides the abandoned-idle window (default
 <!-- gen:tools -->
 ## Tools
 
-38 tools registered (16 shared across both editions, 22 local-only). No deprecated aliases. MIN_CLI_VERSION: 0.15.26.
+38 tools registered (17 shared across both editions, 21 local-only). No deprecated aliases. MIN_CLI_VERSION: 0.15.26.
 
 ### Direct-API tools (both editions)
 
@@ -106,6 +106,7 @@ posted). `CLOUDGRID_QA_IDLE_MS` overrides the abandoned-idle window (default
 | `grid_get_template` | corpus | Load a specific CloudGrid workflow, template, example, rule, or doc by name — deterministic retrieval from the bundle... |
 | `grid_report` | API | Report a genuine CloudGrid failure to the CloudGrid team — ONLY with the user's explicit consent. |
 | `grid_hello` | API | Create a minimal hello page and plug it into the user's grid, returning the live URL. |
+| `grid_delete` | `grid delete entity` | Archive a CloudGrid inspiration. |
 
 The direct-API tools call the platform without the CLI, so they also work in
 the web edition. `grid_login` writes the same `~/.cloudgrid/credentials` the
@@ -129,7 +130,6 @@ CLI uses, so the two share one identity.
 | `grid_edit_existing_app` | `grid pull` | Continue/edit an EXISTING entity locally: download its source + cloudgrid.yaml and link the folder so your next `grid... |
 | `grid_rename` | `grid rename` | Rename a CloudGrid entity's display name (slug stays the same). |
 | `grid_take_offline` | `grid unplug` | Take an entity off the grid. |
-| `grid_delete` | `grid delete entity` | Archive a CloudGrid inspiration. |
 | `grid_rollback_deploy` | `grid rollback` | Rollback an entity to a previous version. |
 | `grid_list_versions` | `grid versions` | List published versions for an entity. |
 | `grid_set_env` | `grid env` | Manage environment variables for an entity. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.21.13",
+  "version": "0.21.15",
   "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": {
@@ -58,6 +58,7 @@
     "test:widgets": "node test/apps-widgets.test.mjs",
     "test:set-sharing": "node test/set-sharing.test.mjs",
     "test:check-deploy": "node test/check-deploy.test.mjs",
+    "test:console-grid-url": "node test/console-grid-url.test.mjs",
     "test:staleness": "node test/staleness.test.mjs",
     "test:proxy": "node test/proxy.test.mjs",
     "test:system-ca": "node test/system-ca.test.mjs",
@@ -73,10 +74,13 @@
     "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:oauth-observability": "node --test test/oauth-flow-observability.test.mjs",
     "test:web-capabilities-log": "node --test test/web-capabilities-log.test.mjs",
+    "test:mcp-transport-observability": "node --test test/mcp-transport-observability.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",
+    "test:delete-hosted": "node test/delete-hosted.test.mjs",
     "build:login-widget": "node scripts/build-login-widget.mjs"
   },
   "dependencies": {

package/src/oauth.js

@@ -33,6 +33,31 @@ function b64url(buf) {
   return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 
+// Observability helpers (#345). The OAuth flow was only observable on the paths
+// it did NOT take — a refused token exchange logs (denyToken), but a successful
+// one and the authorize arrival logged nothing, so "no log line" meant both
+// "never happened" and "worked fine". These emit SHAPE and PRESENCE, never
+// values: this is an auth path and a log aggregator is not private. See the
+// issue's redaction list — code, verifier, code_challenge value, JWT, secret,
+// the full client_id, and the full redirect_uri all stay out of the log.
+
+// A ~12-char prefix correlates lines without printing the signed client_id,
+// which embeds the redirect set.
+function clientIdPrefix(clientId) {
+  return clientId ? `${String(clientId).slice(0, 12)}…` : "absent";
+}
+
+// The HOST is the diagnostic value; the path can carry a per-install identifier,
+// so it is dropped.
+function hostOf(uri) {
+  if (!uri) return "absent";
+  try {
+    return new URL(String(uri)).host;
+  } catch {
+    return "invalid";
+  }
+}
+
 // --- 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,
@@ -278,6 +303,16 @@ 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;
+    // Observability (#345): the request SHAPE the client actually sent, logged
+    // before any check so a rejected request is still visible. Presence, not
+    // values — nothing here is reusable in a log aggregator.
+    console.error(
+      `[oauth] authorize request: client_id=${clientIdPrefix(client_id)} ` +
+        `response_type=${response_type ? String(response_type) : "absent"} ` +
+        `state=${state ? "present" : "absent"} ` +
+        `pkce=${code_challenge ? (code_challenge_method ? String(code_challenge_method) : "present(no-method)") : "absent"} ` +
+        `redirect_host=${hostOf(redirect_uri)}`,
+    );
     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.");
@@ -331,6 +366,10 @@ export function mountOAuth(app, publicBase, opts = {}) {
       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)}` : ""}`;
+      // Observability (#345): we handed control back to the client, and to
+      // where. The host only — the full redirect carries the code and a
+      // per-install path.
+      console.error(`[oauth] redirect handed back to client; redirect_host=${hostOf(sess.redirect_uri)}`);
       res.json({ status: "ready", redirect });
       return;
     }
@@ -386,13 +425,15 @@ export function mountOAuth(app, publicBase, opts = {}) {
       denyToken(res, "unsupported_grant_type", "grant_type must be authorization_code", `(got ${JSON.stringify(grant_type ?? null)})`);
       return;
     }
-    const rec = authCodes.get(String(code));
+    const codeKey = String(code);
+    const rec = authCodes.get(codeKey);
     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;
     }
+    authCodes.delete(codeKey); // single use — consume before validation so a failed attempt cannot be retried
     if (rec.client_id !== String(client_id)) {
       denyToken(
         res,
@@ -412,9 +453,12 @@ export function mountOAuth(app, publicBase, opts = {}) {
       denyToken(res, "invalid_grant", code_verifier === undefined ? "code_verifier is required (PKCE)" : "PKCE verification failed");
       return;
     }
-    authCodes.delete(String(code)); // single use
     const claims = decodeJwt(rec.jwt);
     const expiresIn = claims.exp ? Math.max(60, claims.exp - Math.floor(Date.now() / 1000)) : 30 * 86400;
+    // Observability (#345): the success path. Without this, a successful
+    // exchange and total silence were the same observation. The token is never
+    // logged; client_id is a prefix only.
+    console.error(`[oauth] token exchange succeeded; access token issued (client_id=${clientIdPrefix(client_id)})`);
     res.json({ access_token: rec.jwt, token_type: "Bearer", expires_in: expiresIn, scope: "cloudgrid" });
   });
 }

package/src/tools/constants.js

@@ -29,6 +29,16 @@ export const ANON_HTML_MAX_BYTES = 2_000_000;
 export const AUTHED_HTML_MAX_BYTES = 25_000_000;
 export const CONSOLE_URL = "https://console.cloudgrid.io/";
 
+// The console link handed to a user AFTER a plug. When the grid slug is known it
+// points at THAT grid (verified live: /home?grid=<slug> -> 200) instead of the
+// bare root, so a user with more than one grid lands on the one they just
+// plugged to (#355). Falls back to the root when the slug is unknown. The
+// earlier code hardcoded the root on the belief that "there is no per-grid page"
+// — that was wrong; only the /grids/<slug> form 404s, /home?grid= does not.
+export function consoleGridUrl(slug) {
+  return slug ? `${CONSOLE_URL}home?grid=${encodeURIComponent(slug)}` : CONSOLE_URL;
+}
+
 // Display labels for visibility values (two-axis model). The OPTIONS list is what
 // the post-plug ask offers; the LABELS map also keeps legacy keys (org,
 // authenticated, space) so an entity's CURRENT stored value still renders — do

package/src/tools/deploy.js

@@ -11,7 +11,7 @@ import {
   MCP_VERSION,
   ANON_HTML_MAX_BYTES,
   AUTHED_HTML_MAX_BYTES,
-  CONSOLE_URL,
+  consoleGridUrl,
   VISIBILITY_LABELS,
   VISIBILITY_OPTIONS,
   APPS_WIDGETS_ENABLED,
@@ -71,30 +71,31 @@ function isGridNotAccessibleCode(code) {
 // answer identically today, so moving now is a no-op that stops this tool
 // breaking when `/orgs` goes.
 export async function fetchUserOrgs(token) {
-  try {
-    const res = await fetch(`${API_BASE}/api/v2/grids`, {
-      headers: { Authorization: `Bearer ${token}` },
-    });
-    if (!res.ok) return [];
-    const data = await res.json();
-    // 0.8.0: read the grid-native `data.grids` (dual-emitted alongside the legacy
-    // `data.orgs`, same array/order). Fall back to `data.orgs`/bare-array during soak.
-    const grids = Array.isArray(data?.grids)
-      ? data.grids
-      : Array.isArray(data?.orgs)
-        ? data.orgs
-        : Array.isArray(data)
-          ? data
-          : [];
-    return grids.map((o) => ({
-      slug: o.slug ?? "",
-      name: o.name ?? o.slug ?? "",
-      role: o.role ?? "member",
-      render_ready: o.render_ready ?? true, // default true for older APIs
-    }));
-  } catch {
-    return [];
+  const res = await fetch(`${API_BASE}/api/v2/grids`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (res.status === 401) {
+    const err = new Error(`Grid listing failed (HTTP 401)`);
+    err.status = 401;
+    throw err;
   }
+  if (!res.ok) throw new Error(`Grid listing failed (HTTP ${res.status})`);
+  const data = await res.json();
+  // 0.8.0: read the grid-native `data.grids` (dual-emitted alongside the legacy
+  // `data.orgs`, same array/order). Fall back to `data.orgs`/bare-array during soak.
+  const grids = Array.isArray(data?.grids)
+    ? data.grids
+    : Array.isArray(data?.orgs)
+      ? data.orgs
+      : Array.isArray(data)
+        ? data
+        : [];
+  return grids.map((o) => ({
+    slug: o.slug ?? "",
+    name: o.name ?? o.slug ?? "",
+    role: o.role ?? "member",
+    render_ready: o.render_ready ?? true, // default true for older APIs
+  }));
 }
 
 // ── Shared grid disambiguation (grid_plug) ──────────────────
@@ -104,7 +105,8 @@ 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            → { picker } needs_grid_create (asks)
+//   - no orgs                              → { picker } needs_grid_create (asks)
+//   - listing failed                      → { picker } { error: true } (asks; NOT needs_grid_create)
 // 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
@@ -119,7 +121,26 @@ export async function fetchUserOrgs(token) {
 // dependence on prior-call state (ChatGPT Apps SDK reconnects every call).
 export async function resolveGridOrAsk(ctx, { token, suppliedGrid, edition }, deps = {}) {
   const listGrids = deps.fetchUserOrgs || fetchUserOrgs;
-  const grids = await listGrids(token);
+  let grids;
+  try {
+    grids = await listGrids(token);
+  } catch (err) {
+    if (err.status === 401) {
+      ctx.markTokenRevoked?.(token);
+      return {
+        picker: {
+          text: "Session expired — please log in again.",
+          structured: { error: true },
+        },
+      };
+    }
+    return {
+      picker: {
+        text: "Could not fetch your grids — please try again.",
+        structured: { error: true },
+      },
+    };
+  }
   const activeGrid = await ctx.getActiveGrid();
   const matched = suppliedGrid && grids.find((o) => o.slug === suppliedGrid);
   if (matched) {
@@ -1017,6 +1038,80 @@ export async function runCollab(ctx, { entity_id, grid } = {}) {
   };
 }
 
+// ── grid_delete (hosted edition) — archive an inspiration via the API (#343) ──
+// The handler in register.js resolves auth + grid (via resolveGridOrAsk) before
+// calling this function, so token and grid are always present.
+export async function runDelete(ctx, { name, grid, confirm } = {}) {
+  if (confirm !== true) {
+    throw new Error("`confirm` must be true to proceed with deletion.");
+  }
+  const token = await ctx.getToken();
+  if (!token) {
+    throw new Error("You are not signed in. Run grid_login first.");
+  }
+  if (!name) {
+    throw new Error("`name` (entity slug) is required.");
+  }
+  if (!grid) {
+    throw new Error("`grid` is required — the handler must resolve it before calling runDelete.");
+  }
+
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    "X-CloudGrid-Grid": grid,
+    "X-CloudGrid-Org": grid,
+  };
+
+  // Resolve the entity to get its id and kind.
+  const lookupUrl = `${API_BASE}/api/v2/inspirations/${encodeURIComponent(name)}`;
+  let lookupRes;
+  try {
+    lookupRes = await fetch(lookupUrl, { headers });
+  } catch (err) {
+    throw new Error(`Could not reach CloudGrid at ${API_BASE}: ${err.message}`);
+  }
+
+  if (!lookupRes.ok) {
+    const raw = await lookupRes.text();
+    let data = null;
+    try { data = JSON.parse(raw); } catch { /* */ }
+    const msg = data?.error?.message || data?.message || raw || `HTTP ${lookupRes.status}`;
+    if (lookupRes.status === 404) {
+      throw new Error(`No inspiration found for '${name}'. Check the slug and grid.`);
+    }
+    throw new Error(`Lookup failed (HTTP ${lookupRes.status}): ${msg}`);
+  }
+
+  const entity = await lookupRes.json();
+  // GET /api/v2/inspirations/:slug returns `id`; defensive fallback for `entity_id`.
+  const entityId = entity?.id || entity?.entity_id;
+  if (!entityId) {
+    throw new Error(`Could not resolve entity id for '${name}'.`);
+  }
+
+  // Archive the inspiration.
+  const deleteUrl = `${API_BASE}/api/v2/inspirations/${encodeURIComponent(entityId)}`;
+  let delRes;
+  try {
+    delRes = await fetch(deleteUrl, { method: "DELETE", headers });
+  } catch (err) {
+    throw new Error(`Could not reach CloudGrid at ${API_BASE}: ${err.message}`);
+  }
+
+  if (!delRes.ok) {
+    const raw = await delRes.text();
+    let data = null;
+    try { data = JSON.parse(raw); } catch { /* */ }
+    const msg = data?.error?.message || data?.message || raw || `HTTP ${delRes.status}`;
+    throw new Error(`Delete failed (HTTP ${delRes.status}): ${msg}`);
+  }
+
+  return {
+    text: `Deleted '${name}' (${entityId}) from ${grid}.`,
+    structured: { deleted: true, entity_id: entityId, slug: name, grid },
+  };
+}
+
 // Turn a policy 403 into a request: POST /:id/collab-requests and tell the user
 // what happens next (mirrors CLI collab-requests.ts requestCollabAccess). A
 // request IS a success outcome, so this returns a normal result, never throws for
@@ -1038,7 +1133,7 @@ async function requestCollabAccess(ctx, target, headers) {
     return {
       text:
         `The owner gates who can collaborate on '${target}', so I asked them for push access on your behalf. ` +
-        `They've been notified — once they approve, run grid_collab again to join, then grid_pull to get the code.`,
+        `They've been notified — once they approve, access is live immediately. Then run grid_pull to get the code.`,
       structured: { access_requested: true, request_pending: true, owner_is_you: false, can_edit: false },
     };
   }
@@ -1483,6 +1578,9 @@ function plugErrorMessage(status, code, msg, ctxFlags = {}) {
   if (status === 400 && isGridHeaderError(code, msg)) {
     return `Plug failed (HTTP 400): ${rewriteGridHeaderError(msg)}`;
   }
+  if (status === 400 && /cloudgrid\.yaml.*required/i.test(msg)) {
+    return `Plug failed (HTTP 400): no cloudgrid.yaml found — provide it via the \`cloudgrid_yaml\` parameter or include a \`cloudgrid.yaml\` entry in \`artifact_files\`. Server: ${msg}`;
+  }
   const base = `Plug failed (HTTP ${status}${code ? ` ${code}` : ""}): ${msg}`;
   const guidance = errorGuidance({ status, code, ...ctxFlags });
   return guidance ? `${base} — ${guidance}` : base;
@@ -1895,20 +1993,24 @@ export async function runPlug(ctx, input, deps = {}) {
   }
   if (useAnonWire && ctx.state.anonCookie) headers["Cookie"] = ctx.state.anonCookie;
 
+  // ── Resolve manifest from all sources ────────────────────────────────────────
+  // The explicit `cloudgrid_yaml` param takes precedence; fall back to a
+  // `cloudgrid.yaml` entry in `artifact_files`. This resolves the asymmetry
+  // where create honoured artifact_files but re-plug ignored it (#314).
+  const resolvedManifestYaml = cloudgrid_yaml
+    || (hasArtifacts && artifact_files.find((f) => f?.path === "cloudgrid.yaml")?.content)
+    || null;
+
   // ── CREATE manifest injection (issue #48) ───────────────────────────────────
-  // On a folder-walk create, a `cloudgrid.yaml` on disk is walked into the tree
-  // and — because directory reads surface it before the nested `services/…`
-  // files — rides the multipart body as the FIRST `artifact` part, with the
-  // walk's uniform `application/octet-stream` content-type. The runtime build
-  // orchestrator relies on the manifest leading the bundle (it drives the
-  // service graph + the entity name). The inline `artifact_files` create used to
-  // APPEND the `cloudgrid_yaml` manifest LAST and as `text/plain`, so a
+  // The runtime build orchestrator relies on the manifest leading the bundle
+  // (it drives the service graph + the entity name). The inline `artifact_files`
+  // create used to APPEND the manifest LAST and as `text/plain`, so a
   // multi-service runtime rolled out with no service graph (0 replicas /
   // rollout_failed) and an auto `drop-XXXX` name. Fold the manifest into the
   // artifact list as the first entry (deduping any `cloudgrid.yaml` the caller
   // already inlined) so both create paths emit a byte-equivalent bundle.
-  if (!isEdit && cloudgrid_yaml) {
-    const manifest = { path: "cloudgrid.yaml", buffer: Buffer.from(cloudgrid_yaml, "utf8") };
+  if (!isEdit && resolvedManifestYaml) {
+    const manifest = { path: "cloudgrid.yaml", buffer: Buffer.from(resolvedManifestYaml, "utf8") };
     const rest = artifacts.filter((a) => a.path !== "cloudgrid.yaml");
     artifacts = [manifest, ...rest];
   }
@@ -1933,7 +2035,7 @@ export async function runPlug(ctx, input, deps = {}) {
       // (materializePlugTarball); an inspiration edit ignores its content.
       form.append(
         "cloudgrid.yaml",
-        new Blob([cloudgrid_yaml || ""], { type: "text/plain" }),
+        new Blob([resolvedManifestYaml || ""], { type: "text/plain" }),
         "cloudgrid.yaml",
       );
     }
@@ -1943,7 +2045,7 @@ export async function runPlug(ctx, input, deps = {}) {
   // auto `drop-XXXX` slug. Harmless if the server owns slug generation; on a
   // re-plug the entity's name is authoritative, so only send on create.
   if (!isEdit) {
-    const manifestName = parseManifestName(cloudgrid_yaml);
+    const manifestName = parseManifestName(resolvedManifestYaml);
     if (manifestName) {
       form.append("name", manifestName);
       form.append("slug", manifestName);
@@ -2057,6 +2159,9 @@ export async function runPlug(ctx, input, deps = {}) {
     ) {
       return plugViaCliFallback(ctx, artifacts, deps);
     }
+    if (res.status === 401 && authToken && !useAnonWire) {
+      ctx.markTokenRevoked?.(authToken);
+    }
     throw new Error(plugErrorMessage(res.status, code, msg, flags));
   }
 
@@ -2271,8 +2376,11 @@ export async function runPlug(ctx, input, deps = {}) {
   // 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.
+  // state (sign-in wall → their grid → onboarding). Point at the SPECIFIC grid
+  // when we know its slug — /home?grid=<slug> renders (verified), so a user with
+  // several grids lands on the one they just plugged to (#355). Only the
+  // /grids/<slug> form 404s; /home?grid= does not. Falls back to the root when
+  // the slug is unknown.
   //
   // 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"
@@ -2280,8 +2388,9 @@ export async function runPlug(ctx, input, deps = {}) {
   // 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}`);
+    const consoleUrl = consoleGridUrl(data.grid ?? grid ?? null);
+    structured.console_url = consoleUrl;
+    lines.push(`You can view it live in your grid along with all the apps you build here: ${consoleUrl}`);
   }
 
   // Visibility is the user's choice — never set silently. On a NEW deploy,
@@ -2774,8 +2883,8 @@ export async function runCheckDeploy(ctx, { poll_url, grid } = {}) {
       // 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 },
+        `You can view it live in your grid along with all the apps you build here: ${consoleGridUrl(gridSlug)}`,
+      structured: { status: "success", live: true, ...(url ? { url } : {}), console_url: consoleGridUrl(gridSlug) },
     };
   }
   if (verdict.status === "failed") {

package/src/tools/register.js

@@ -25,6 +25,7 @@ import {
   runReport,
   runPull,
   runCollab,
+  runDelete,
   runPlug,
   runPickup,
   runCreateGrid,
@@ -273,7 +274,7 @@ export function registerTools(server, ctx) {
     "grid_collab",
     {
       title: "Get push access to an app you don't own",
-      description: "Collab: GET PUSH ACCESS to the SAME live entity that someone else owns — you become a collaborator on THAT entity, not a copy. This grants PERMISSION ONLY and fetches nothing: after it succeeds, run grid_pull to get the code, then grid_plug (with its target_entity_id) updates the SHARED entity in place (the team sees the new version and can roll it back). This is NOT a fork — it never mints a new entity and never carries forked_from lineage; if you want your OWN separate copy instead, that is grid_pickup. If the owner GATES who may join, this does NOT dead-end: it sends the owner a request for access on your behalf, and once they approve you run grid_collab again to join. Use this — not grid_pickup — whenever the user asks to \"collab\" on, \"join\", or \"get push/write access to\" an app they don't own. Requires sign-in. Calls the API directly (both editions).",
+      description: "Collab: GET PUSH ACCESS to the SAME live entity that someone else owns — you become a collaborator on THAT entity, not a copy. This grants PERMISSION ONLY and fetches nothing: after it succeeds, run grid_pull to get the code, then grid_plug (with its target_entity_id) updates the SHARED entity in place (the team sees the new version and can roll it back). This is NOT a fork — it never mints a new entity and never carries forked_from lineage; if you want your OWN separate copy instead, that is grid_pickup. If the owner GATES who may join, this does NOT dead-end: it sends the owner a request for access on your behalf, and once they approve, access is live immediately — no need to re-run grid_collab. Use this — not grid_pickup — whenever the user asks to \"collab\" on, \"join\", or \"get push/write access to\" an app they don't own. Requires sign-in. Calls the API directly (both editions).",
       inputSchema: {
         entity_id: z.string().describe("The app to get push access to: a canonical UUID or <grid-slug>/<entity-slug>."),
         grid: z.string().optional().describe("Grid to resolve a bare slug in. Required only when a bare slug is ambiguous across grids you belong to."),
@@ -286,7 +287,7 @@ export function registerTools(server, ctx) {
         owner_is_you: z.boolean().optional().describe("True if you already own it (nothing to grant)."),
         can_edit: z.boolean().optional().describe("True once you have push access (owner or collaborator). False = still view-only."),
         access_requested: z.boolean().optional().describe("True when the owner gates access and a request was sent on your behalf."),
-        request_pending: z.boolean().optional().describe("True when a request is awaiting the owner's decision — join with grid_collab again once approved."),
+        request_pending: z.boolean().optional().describe("True when a request is awaiting the owner's decision — access is live as soon as they approve (no re-run needed)."),
       },
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     },
@@ -501,7 +502,7 @@ export function registerTools(server, ctx) {
         claim_url: z.string().optional().describe("Anon create only: sign-in link to claim ownership."),
         claim_message: z.string().optional().describe("Anon create only: the claim nudge to relay."),
         owner_token: z.string().optional().describe("Anonymous drops: the bearer owner token (re-plug + claim). Re-minted on every anonymous edit — persist the newest."),
-        console_url: z.string().optional().describe("Web authed inspiration create: URL to manage all apps in the grid."),
+        console_url: z.string().optional().describe("Emitted on every non-building plug (both editions): a link to the grid in the console."),
         current_visibility: z.string().optional().describe("Web authed inspiration create: the visibility set after publish (link)."),
         visibility_options: z.array(z.object({
           value: z.string().describe("Visibility value to pass to grid_visibility."),
@@ -531,6 +532,7 @@ export function registerTools(server, ctx) {
         })).optional().describe("Alias of grids (legacy picker alias)."),
         via: z.string().optional().describe("Recovery marker: 'cli-fallback' when a signed-in create was published through the bundled CloudGrid CLI."),
         needs_grid_create: z.boolean().optional().describe("Zero-grid ask: the account has no grid yet — suggest a slug, confirm with the user, call grid_create_grid, then re-call grid_plug with grid: <slug>."),
+        error: z.boolean().optional().describe("True when the grid listing failed (network/auth error). The text carries a human-readable message. Do NOT treat this as needs_grid_create."),
       },
       // destructiveHint (M3): a re-plug with target_entity_id REPLACES what is
       // live at a public URL in place. Versions + grid rollback exist, but the
@@ -903,7 +905,12 @@ export function registerTools(server, ctx) {
       if (!token) {
         return fail("You are not signed in. Run grid_login first.");
       }
-      const grids = await fetchUserOrgs(token);
+      let grids;
+      try {
+        grids = await fetchUserOrgs(token);
+      } catch {
+        return fail("Could not list your grids — please check your connection and try again.");
+      }
       if (grids.length === 0) {
         // Structured output stays `orgs` (its declared schema); user text says grid.
         return okResult({ text: "No grids found.", structured: { orgs: [] } });
@@ -1184,6 +1191,7 @@ export function registerTools(server, ctx) {
         entity_id: z.string().optional().describe("Re-plug handle."),
         needs_auth: z.boolean().optional().describe("True when the user must sign in first."),
         needs_grid: z.boolean().optional().describe("True when the user must choose a grid."),
+        error: z.boolean().optional().describe("True when the grid listing failed (network/auth error). The text carries a human-readable message. Do NOT treat this as needs_grid_create."),
       },
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     },
@@ -1238,6 +1246,66 @@ export function registerTools(server, ctx) {
     },
   );
 
+  // grid_delete (hosted edition) — archive an inspiration via the direct API
+  // (#343). The local edition has a CLI-wrapping version below the edition gate;
+  // this direct-API version runs on web (hosted) where the CLI is unavailable.
+  if (ctx.edition !== "local") {
+    reg(
+      "grid_delete",
+      {
+        title: "Delete an inspiration",
+        description:
+          "Archive a CloudGrid inspiration by slug. Destructive — requires `confirm: true`. " +
+          "If the user has more than one grid and `grid` is not given, this returns needs_grid with " +
+          "the list — ASK the user which grid, then call again with `grid` set. Never guess the grid. " +
+          "Only works for inspirations (static pages); runtime apps and agents must be removed " +
+          "with `grid unplug --hard` from the CLI. Requires sign-in. Calls the API directly.",
+        inputSchema: {
+          name: z.string().describe("Entity slug to delete (required)."),
+          grid: z.string().optional().describe("Grid slug to delete from. Omit on the first call to be asked."),
+          confirm: z.literal(true).describe("Must be true to proceed."),
+        },
+        outputSchema: {
+          deleted: z.boolean().describe("True when the entity was archived."),
+          entity_id: z.string().optional().describe("The archived entity's id."),
+          slug: z.string().optional().describe("The archived entity's slug."),
+          grid: z.string().optional().describe("The grid the entity was deleted from."),
+          needs_auth: z.boolean().optional().describe("True when the user must sign in first."),
+          needs_grid: z.boolean().optional().describe("True when the user must choose a grid."),
+          error: z.boolean().optional().describe("True when the grid listing failed (network/auth error)."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+      },
+      async (input) => {
+        try {
+          // 1. AUTH
+          const token = await ctx.getToken();
+          if (!token) {
+            return okResult({
+              text: "Deleting an inspiration needs an account. Call grid_login to sign in, then re-call grid_delete.",
+              structured: { needs_auth: true },
+            });
+          }
+
+          // 2. GRID — never fall back to the active grid on a destructive op (#343).
+          const decision = await resolveGridOrAsk(ctx, {
+            token,
+            suppliedGrid: input?.grid,
+            edition: ctx.edition,
+          });
+          if (decision.picker) return okResult(decision.picker);
+          const grid = decision.grid || decision.single?.slug;
+          if (!grid) return fail("Could not resolve a grid. Pass `grid` explicitly.");
+
+          // 3. DELETE
+          return okResult(await runDelete(ctx, { ...input, grid }));
+        } catch (err) {
+          return fail(err.message);
+        }
+      },
+    );
+  }
+
   if (ctx.edition !== "local") return; // web edition stops here — no CLI tools
 
   // ── CLI-wrapping tools (local edition only) ───────────────────────────────

package/src/web-identity.js

@@ -25,14 +25,20 @@ export function createWebIdentity({
   let transportToken = initialTransportToken;
   let explicitToken = null;
   let hasExplicitLogin = false;
+  const revokedTokens = new Set();
 
   // An explicit login wins over transport-token refreshes for the same subject.
   // A genuine transport subject change ends that override so credentials from
   // the previous person cannot persist on a connection now owned by another.
-  function effectiveToken() {
+  function rawEffectiveToken() {
     return hasExplicitLogin ? explicitToken : transportToken;
   }
 
+  function effectiveToken() {
+    const tok = rawEffectiveToken();
+    return revokedTokens.has(tok) ? null : tok;
+  }
+
   return {
     captureTransportToken(jwt) {
       const previousSub = decodeJwt(transportToken).sub;
@@ -62,7 +68,11 @@ export function createWebIdentity({
 
     async getCredentialsStatus() {
       const jwt = effectiveToken();
-      if (!jwt) return { creds: null, expired: false };
+      if (!jwt) {
+        // A revoked token is surfaced as expired so the client triggers re-auth.
+        const revoked = revokedTokens.has(rawEffectiveToken());
+        return { creds: null, expired: revoked || isTokenExpired(rawEffectiveToken(), now) };
+      }
       if (isTokenExpired(jwt, now)) return { creds: null, expired: true };
       return { creds: { jwt }, expired: false };
     },
@@ -72,5 +82,9 @@ export function createWebIdentity({
       hasExplicitLogin = true;
       return decodeJwt(jwt);
     },
+
+    markRevoked(jwt) {
+      if (jwt) revokedTokens.add(jwt);
+    },
   };
 }

package/src/web-observability.js

@@ -0,0 +1,120 @@
+// Observability for POST /mcp on the hosted edge (#353). Makes the four transport
+// exits visible in the log — the 401 auth challenge, both 400 branches, and a
+// successful session — so a client that completes OAuth and then fails to
+// establish a session (#329) can be diagnosed instead of vanishing silently.
+//
+// Redaction — same standard as #347. Never log a bearer token, any fragment of
+// it, or its length in a way that narrows it: log PRESENCE and PARSE RESULT only
+// (see authHeaderState). Client-supplied text (clientInfo.name, the presented
+// mcp-session-id) is untrusted — logSafe bounds its length and flattens control
+// characters so a client cannot forge a log line or break log-line parsing.
+//
+// Scope note (mirroring #347's explicit statement): these helpers never emit the
+// bearer or the mcp-session-id header value except as a bounded, flattened
+// echo of the client-presented id on the rehydrate-failed path — an
+// already-public session identifier, not a credential.
+
+function defaultEmit(msg) {
+  // eslint-disable-next-line no-console
+  console.error(msg);
+}
+
+// Bound and flatten client-supplied text so it cannot forge a log line (strip
+// CR/LF and other control chars) or flood one (cap length). Presence/shape only.
+export function logSafe(value, max = 64) {
+  const s = String(value ?? "");
+  const flat = s.replace(/[\u0000-\u001f\u007f]/g, " ");
+  return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+
+// Classify the Authorization header WITHOUT revealing the token. Distinguishing
+// absent / not-bearer / empty-token is the entire diagnostic value of the 401
+// (#353): it says why no usable Bearer was found, never what it was. The four
+// categories:
+//   absent      — no Authorization header at all
+//   not-bearer  — a header of some OTHER scheme (e.g. "Basic …")
+//   empty-token — the Bearer scheme but no token ("Bearer", "Bearer ")
+//   bearer      — the Bearer scheme with a token (never reaches the 401)
+// Note (#353): an HTTP parser strips a header value's trailing whitespace, so a
+// client's "Bearer " arrives as "Bearer" — the empty-token case. This mirrors
+// bearerOf() in web.js, which yields a token only for "Bearer <non-space…>".
+export function authHeaderState(req) {
+  const raw = req?.headers?.authorization;
+  const h = Array.isArray(raw) ? raw[0] : raw;
+  if (h == null || h === "") return "absent";
+  if (!/^Bearer\b/i.test(h)) return "not-bearer";
+  return /^Bearer\s+\S/i.test(h) ? "bearer" : "empty-token";
+}
+
+// Reduce an object to its KEY SHAPE — key names mapped to the TYPE of each value,
+// recursively — never the values themselves. Used to log the client's advertised
+// MCP capabilities at initialize (#297) while guaranteeing BY CONSTRUCTION that
+// no value ever leaves the process: only key names and JS type names are emitted,
+// so no token, header, tool argument, or user content can appear even if the
+// object carried one. Depth- and breadth-capped so a malformed or huge object
+// cannot blow the stack or flood the log.
+export function keyShape(value, depth = 0) {
+  if (value === null || typeof value !== "object" || depth >= 6) return typeof value;
+  if (Array.isArray(value)) return `array[${value.length}]`;
+  const out = {};
+  for (const k of Object.keys(value).slice(0, 64)) out[k] = keyShape(value[k], depth + 1);
+  return out;
+}
+
+// The 401 auth challenge on /mcp (REQUIRE_AUTH && no usable Bearer).
+export function logAuthChallenge(req, emit = defaultEmit) {
+  emit(`cloudgrid-mcp: /mcp 401 auth-challenge authorization=${authHeaderState(req)}`);
+}
+
+// The first 400 branch: a request with no session id that is not an initialize.
+export function logNoSession(emit = defaultEmit) {
+  emit("cloudgrid-mcp: /mcp 400 no-session reason=missing-session-id-and-not-initialize");
+}
+
+// The second 400 branch: a stale-id rehydrate that failed to prime and fell back
+// to the 400. session-id is the client-presented header — echoed, bounded, never
+// a credential.
+export function logRehydrateFailed(sessionId, emit = defaultEmit) {
+  emit(`cloudgrid-mcp: /mcp 400 rehydrate-failed session-id=${logSafe(sessionId)}`);
+}
+
+// The successful-session exit, emitted from the SDK's `oninitialized`. TWO lines
+// with a DELIBERATE separation:
+//
+//   1. session-established — UNCONDITIONAL, emitted FIRST, outside any swallowing
+//      try/catch. The record that a session exists must never depend on the
+//      best-effort probe below. This is the fix for the #329 trap: the #297
+//      capability line is observation-only and could silently NOT fire on a good
+//      session, and its absence was mis-read as "no session existed". A separate
+//      always-emitted line removes that ambiguity.
+//   2. client-capabilities — best-effort observation only (#297). A failure here
+//      is swallowed and MUST NOT suppress line 1 or affect the session. The
+//      synthetic rehydrate initialize is skipped so the capability signal stays
+//      clean (line 1 still fires for it — a rehydrate is a real session).
+//
+// `protocolVersion` is passed in (the SDK exposes no getter for the negotiated
+// version post-init); web.js negotiates it with the same rule the SDK uses.
+export function logInitialize(server, sessionId, protocolVersion, emit = defaultEmit) {
+  let clientName = "unknown";
+  try {
+    clientName = server?.getClientVersion?.()?.name ?? "unknown";
+  } catch {
+    /* name only — the session-established line below still fires */
+  }
+  emit(
+    `cloudgrid-mcp: session established session-id=${logSafe(sessionId)} ` +
+      `protocol=${logSafe(protocolVersion, 32)} client=${logSafe(clientName)}`,
+  );
+
+  try {
+    if (clientName !== "cloudgrid-mcp-rehydrate") {
+      const caps = server?.getClientCapabilities?.();
+      const shape = caps && typeof caps === "object" ? keyShape(caps) : null;
+      emit(
+        `cloudgrid-mcp: client-capabilities client=${logSafe(clientName)} capabilities=${JSON.stringify(shape)}`,
+      );
+    }
+  } catch {
+    /* observation-only — never affects the session or the line above */
+  }
+}

package/src/web.js

@@ -34,6 +34,12 @@ import { createSessionLogger } from "./session-logger.js";
 import { createSink } from "./log-sink.js";
 import { INSTRUCTIONS_WEB } from "./playbook.js";
 import { createWebIdentity } from "./web-identity.js";
+import {
+  logAuthChallenge,
+  logNoSession,
+  logRehydrateFailed,
+  logInitialize,
+} from "./web-observability.js";
 
 const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url)));
 
@@ -57,19 +63,14 @@ function bearerOf(req) {
   return h && /^Bearer\s+\S+/i.test(h) ? h.replace(/^Bearer\s+/i, "") : null;
 }
 
-// Reduce an object to its KEY SHAPE — key names mapped to the TYPE of each value,
-// recursively — never the values themselves. Used to log the client's advertised
-// MCP capabilities at initialize (#297) while guaranteeing BY CONSTRUCTION that
-// no value ever leaves the process: only key names and JS type names are emitted,
-// so no token, header, tool argument, or user content can appear even if the
-// object carried one. Depth- and breadth-capped so a malformed or huge object
-// cannot blow the stack or flood the log.
-function keyShape(value, depth = 0) {
-  if (value === null || typeof value !== "object" || depth >= 6) return typeof value;
-  if (Array.isArray(value)) return `array[${value.length}]`;
-  const out = {};
-  for (const k of Object.keys(value).slice(0, 64)) out[k] = keyShape(value[k], depth + 1);
-  return out;
+// Negotiate the MCP protocol version with the same rule the SDK's _oninitialize
+// uses (a supported requested version wins, else LATEST). Used only to report the
+// negotiated version on the session-established log line (#353) — the SDK exposes
+// no getter for it post-init — and to build the synthetic rehydrate initialize.
+function negotiateProtocol(requested) {
+  return typeof requested === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+    ? requested
+    : LATEST_PROTOCOL_VERSION;
 }
 
 // A web session: identity lives in memory for the session's lifetime only. The
@@ -86,6 +87,7 @@ function makeWebContext(sessionId, identity) {
     getCredentialsStatus: identity.getCredentialsStatus,
     getActiveGrid: async () => null,
     saveToken: identity.saveToken,
+    markTokenRevoked(jwt) { identity.markRevoked(jwt); },
     savedLocationNote: () => "You are signed in for this session.",
     trustedServer: TRUSTED_SERVER_SECRET
       ? { secret: TRUSTED_SERVER_SECRET, endUserId: sessionId }
@@ -139,7 +141,7 @@ function captureRequestIdentity(sessionId, jwt) {
 // for a rehydrated (restart-evicted) session, the id the client keeps presenting.
 // Identity derives ONLY from the credential passed here (`jwt`), never from
 // anything remembered about the id: a session id is not proof of identity.
-async function buildSession(sessionId, jwt) {
+async function buildSession(sessionId, jwt, protocolVersion) {
   const identity = createWebIdentity({ initialTransportToken: jwt });
   const transport = new StreamableHTTPServerTransport({
     sessionIdGenerator: () => sessionId,
@@ -181,28 +183,12 @@ async function buildSession(sessionId, jwt) {
     } catch {
       webCtx.state.client = null;
     }
-    // #297: record the client's advertised MCP capabilities once per session, so
-    // we can settle whether Claude web ever advertises a UI extension (e.g.
-    // io.modelcontextprotocol/ui) — the plumbing a rendered login card would
-    // need — instead of guessing while the directory submission sits unanswered.
-    // Observation-only: only the capability KEY SHAPE (names + value types, never
-    // values — see keyShape) is logged, so no credential or user content can
-    // appear. Skip the synthetic rehydrate initialize so the signal stays clean.
-    // Wrapped so a logging failure can never affect the session (zero behaviour
-    // change if capabilities is absent or malformed).
-    try {
-      const client = server.server.getClientVersion() ?? null;
-      if (client?.name !== "cloudgrid-mcp-rehydrate") {
-        const caps = server.server.getClientCapabilities();
-        const shape = caps && typeof caps === "object" ? keyShape(caps) : null;
-        // eslint-disable-next-line no-console
-        console.error(
-          `cloudgrid-mcp: client-capabilities client=${client?.name ?? "unknown"} capabilities=${JSON.stringify(shape)}`,
-        );
-      }
-    } catch {
-      /* observation-only — never affects the session */
-    }
+    // #353/#297: emit the session-established line UNCONDITIONALLY (id, protocol,
+    // client) and then the best-effort #297 capability key-shape line. The two
+    // are deliberately separate — see logInitialize: the fact that a session was
+    // created must not depend on the swallow-everything capability probe, whose
+    // silent non-firing on a good session sent the #329 diagnosis sideways.
+    logInitialize(server.server, sessionId, protocolVersion);
   };
   await server.connect(transport);
   return { transport, identity };
@@ -224,11 +210,7 @@ async function primeSession(transport, req) {
   if (!wst || typeof wst.handleRequest !== "function") {
     throw new Error("cannot rehydrate session: transport internals unavailable");
   }
-  const proposed = req.headers["mcp-protocol-version"];
-  const protocolVersion =
-    typeof proposed === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(proposed)
-      ? proposed
-      : LATEST_PROTOCOL_VERSION;
+  const protocolVersion = negotiateProtocol(req.headers["mcp-protocol-version"]);
   const initBody = {
     jsonrpc: "2.0",
     id: "cg-rehydrate-init",
@@ -256,6 +238,9 @@ app.post("/mcp", async (req, res) => {
   const jwt = bearerOf(req);
 
   if (REQUIRE_AUTH && !jwt) {
+    // #353: name WHY no usable Bearer was found — absent / not-bearer / empty-token
+    // — without revealing the token. This is the whole diagnostic value of the 401.
+    logAuthChallenge(req);
     sendAuthChallenge(res);
     return;
   }
@@ -282,6 +267,8 @@ app.post("/mcp", async (req, res) => {
   // A brand-new connection with no session id that is NOT an initialize is a real
   // protocol error — there is nothing to recover.
   if (!sessionId && !isInit) {
+    // #353: 400 branch 1 — a brand-new connection that is not an initialize.
+    logNoSession();
     res.status(400).json({
       jsonrpc: "2.0",
       error: { code: -32000, message: "No valid session. Send an initialize request first." },
@@ -297,7 +284,7 @@ app.post("/mcp", async (req, res) => {
     // above), so an expired-but-present Bearer proceeds to the tool layer where
     // the in-band needs_auth ask lives, rather than being challenged.
     const newSessionId = randomUUID();
-    ({ transport } = await buildSession(newSessionId, jwt));
+    ({ transport } = await buildSession(newSessionId, jwt, negotiateProtocol(req.body?.params?.protocolVersion)));
     await transport.handleRequest(req, res, req.body);
     return;
   }
@@ -317,7 +304,7 @@ app.post("/mcp", async (req, res) => {
   // stuck behind the same 401 (the #286 brick, on the rebuild path). Gating on
   // expiry (hasUsableCredential) here is exactly what #288 got wrong and was pulled
   // from production for.
-  ({ transport } = await buildSession(sessionId, jwt));
+  ({ transport } = await buildSession(sessionId, jwt, negotiateProtocol(req.headers["mcp-protocol-version"])));
   // Rehydrate the evicted session. If priming fails (e.g. an SDK internal moved
   // out from under us), tear the half-built session down and fall back to the
   // original 400 rather than leaking a broken session or hanging the request —
@@ -325,6 +312,8 @@ app.post("/mcp", async (req, res) => {
   try {
     await primeSession(transport, req);
   } catch {
+    // #353: 400 branch 2 — a stale-id rehydrate that could not be primed.
+    logRehydrateFailed(sessionId);
     try { await transport.close(); } catch { /* best effort */ }
     delete transports[sessionId];
     delete sessionContexts[sessionId];