@1agh/maude 0.53.2 → 0.55.0

package/apps/studio/http.ts

@@ -5,7 +5,7 @@
 // top-level fall-through for paths Bun's `routes` field doesn't cover.
 
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync, unlinkSync, watch } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, unlinkSync, watch } from 'node:fs';
 import { dirname, join, posix, relative, resolve, sep } from 'node:path';
 
 import {
@@ -22,7 +22,7 @@ import { type Api, ASSET_MAX_BYTES, ASSET_MAX_VIDEO_BYTES } from './api.ts';
 import { ImportAssetError, importSvg, SVG_MAX_BYTES } from './bin/_import-asset.mjs';
 import { ImportBrandError, importBrand } from './bin/_import-brand.mjs';
 import { buildCanvasModule } from './canvas-build.ts';
-import { buildCanvasSandboxed } from './canvas-build-sandbox.ts';
+import { buildCanvasSandboxed, buildStats } from './canvas-build-sandbox.ts';
 import { canvasLibPath } from './canvas-lib-resolver.ts';
 import { TranspileError } from './canvas-pipeline.ts';
 import { createCloudEndpoints } from './cloud/endpoints.ts';
@@ -81,12 +81,13 @@ import {
 import { createGitEndpoints } from './git/endpoints.ts';
 import { gitShowFile } from './git/service.ts';
 import { createGitHubEndpoints } from './github/endpoints.ts';
-import type { Inspect } from './inspect.ts';
+import type { InspectRegistry } from './inspect.ts';
 import { canvasSlug, writeLocator } from './locator.ts';
 import { BIN_DIR, DEV_SERVER_ROOT, MEDIA_DIR, STICKERS_DIR } from './paths.ts';
 import { createPhotoStore, PHOTO_EDIT_MAX_BYTES } from './photo-store.ts';
 import { probeReadiness } from './readiness.ts';
 import { getRuntimeBundle, packageForSlug } from './runtime-bundle.ts';
+import { currentSession } from './session-scope.ts';
 import { linkHub } from './sync/hub-link.ts';
 import { isHubReadOnly } from './sync/hubs-config.ts';
 import { signInToWorkspace, workspaceDisclosure } from './sync/workspace-signin.ts';
@@ -180,6 +181,25 @@ function ext(p: string): string {
  * do not read it as precedent for adding further hosts without the same
  * scrutiny (exact hostname, no wildcard subdomain, a DDR record).
  */
+/**
+ * A stable, non-revealing name for the tree this process is serving.
+ *
+ * `realpath` first, so a bind-mount and a symlink to the same checkout are the
+ * same identity rather than two — the supervisor computes it from its own
+ * configured path and the two must agree. Falls back to the path as given when
+ * it cannot be resolved: an unresolvable root is a difference worth reporting,
+ * not one worth hiding behind a throw.
+ */
+export function rootIdentity(root: string): string {
+  let resolved = root;
+  try {
+    resolved = realpathSync(root);
+  } catch {
+    /* not on disk (yet) — hash what we were told */
+  }
+  return createHash('sha256').update(resolved, 'utf8').digest('hex').slice(0, 12);
+}
+
 export function cspForCanvasShell(html: string, mainOrigin?: string): string {
   const hashes: string[] = [];
   // Match inline <script> blocks only (no src=). `[^>]*` excludes any with src.
@@ -333,9 +353,20 @@ export const READ_ONLY_ALLOWED_WRITES = new Set([
   '/_api/cloud/signin/start', // account session, not project state
   '/_api/cloud/signin/poll',
   '/_api/cloud/signout',
-  '/_api/git/fetch', // syncing the project DOWN is a read of the project
-  '/_api/git/pull',
-  '/_api/git/checkout', // viewing another branch, not changing one
+  // Fetch moves remote-tracking refs and nothing else — no working tree, no
+  // index. It stays a read.
+  '/_api/git/fetch',
+  // `pull` and `checkout` USED TO BE HERE, on the reasoning that "viewing
+  // another branch is not changing one". Cloud Phase 27 D2 retired that: both
+  // rewrite the working tree, and the tree is SHARED — in a cell by every
+  // member, and on a hub-linked desktop by whoever else has that project open.
+  // A viewer switching branches replaces the files under someone mid-edit.
+  //
+  // The proxy's manifest already refuses them, but this gate is the one the
+  // hub-linked desktop and self-host path consult (`isHubReadOnly`), where no
+  // manifest runs at all — so leaving them here would have left the hole open
+  // exactly where the proxy cannot reach. Two gates, and neither is trusted to
+  // be the last word.
 ]);
 
 /**
@@ -747,6 +778,25 @@ function etagFor(file: { size: number; lastModified: number }): string {
   return `W/"${file.size.toString(16)}-${Math.trunc(file.lastModified).toString(16)}"`;
 }
 
+/**
+ * An SVG is a DOCUMENT, and a document runs script.
+ *
+ * `image/svg+xml` is inert as an `<img>`, a CSS `url()` or a `<use>` target —
+ * none of those are browsing contexts. Navigate to one directly and it is a
+ * page, with `<script>` in it, executing on whatever origin served it. On the
+ * canvas origin that is a stored-XSS primitive: canvases carry the tenant's own
+ * SVGs, only the shell HTML gets a CSP, and every other static response here
+ * has carried `nosniff` and nothing else.
+ *
+ * `default-src 'none'; sandbox` costs the legitimate uses nothing (an image is
+ * not a document, so the policy never applies to them) and makes the
+ * navigate-to-it case a blank page instead of a foothold. Found by an
+ * adversarial pass as step one of a three-link cross-tenant chain; the other
+ * two links are closed in the same change, and this is the cheapest of the
+ * three to break.
+ */
+const INERT_DOCUMENT_CSP = "default-src 'none'; sandbox";
+
 async function serveFile(absPath: string, headers: Record<string, string> = {}): Promise<Response> {
   const file = Bun.file(absPath);
   if (!(await file.exists())) return new Response('Not found', { status: 404 });
@@ -757,6 +807,7 @@ async function serveFile(absPath: string, headers: Record<string, string> = {}):
       'Content-Type': MIME[e] || 'application/octet-stream',
       'Cache-Control': policy.cacheControl,
       ...(policy.addEtag ? { ETag: etagFor(file) } : {}),
+      ...(e === '.svg' ? { 'Content-Security-Policy': INERT_DOCUMENT_CSP } : {}),
       ...headers,
     },
   });
@@ -839,11 +890,18 @@ export interface Http {
 export function createHttp(
   ctx: Context,
   api: Api,
-  inspect: Inspect,
+  /** D3 — one inspector per member. `inspect()` resolves the ambient session's
+   *  instance, which on a desktop is the single one this used to be. */
+  inspects: InspectRegistry,
   ai: AiActivity,
   exportJobs: ExportJobQueue,
   generateJobs: GenerationJobQueue
 ): Http {
+  /** The current request's inspector state (Cloud Phase 27 D3). Resolved per
+   *  call rather than captured, because "whose" changes per request and a
+   *  captured instance would hand one member another's open canvas. */
+  const inspect = () => inspects.for(currentSession());
+
   // Task 2.7 (approach A) — in-flight whisper-model download state (one at a
   // time), polled by the Settings "Download model" card via GET
   // /_api/generate/whisper-model. Closure-scoped: one server, one download.
@@ -1006,7 +1064,7 @@ export function createHttp(
     req: Request,
     body: { format: Format; scope: Scope; options?: Record<string, unknown> }
   ) {
-    const activeJson = inspect.state as unknown as ActiveJsonShape;
+    const activeJson = inspect().state as unknown as ActiveJsonShape;
     return {
       format: body.format,
       scope: body.scope,
@@ -1036,10 +1094,36 @@ export function createHttp(
         ok: true,
         app: 'design',
         project: ctx.cfg.name,
+        // WHICH TREE THIS PROCESS IS ACTUALLY SERVING — Cloud Phase 27 D5.
+        //
+        // A supervisor that only asks "did something answer" cannot tell a
+        // studio serving the tenant's checkout from one serving whatever was
+        // left in the working directory, and "boots, looks fine, serves the
+        // wrong root" is exactly the mistake `studioLaunch` warns about one
+        // process up. A tag is not an identity; a hash is.
+        //
+        // The HASH and not the path: this route is on the canvas origin's
+        // allowlist, so the tenant's own untrusted code can read it, and a
+        // server filesystem path is not something it should learn. The
+        // supervisor hashes its own expected root and compares.
+        rootId: rootIdentity(ctx.paths.repoRoot),
         pid: process.pid,
+        // Cloud Phase 26 Stage 4 — the build sandbox's own counters, so the
+        // €3/cell model finally has figures instead of a prediction. Counts and
+        // durations ONLY: never a canvas name, never a path, and never the text
+        // of a rejected import specifier (that specifier is tenant-authored
+        // content — the operational fact is that a rejection happened, not what
+        // it said).
+        //
+        // On `/_health`, which the untrusted canvas origin may read, and that
+        // is deliberate: every figure here is about the reader's OWN cell, so
+        // it discloses nothing across a tenant boundary. Inventing a privileged
+        // route would have meant inventing an auth path for the supervisor's
+        // loopback probe, for data the tenant already has.
+        render: buildStats(),
       }),
 
-    '/_active': () => Response.json(inspect.state),
+    '/_active': () => Response.json(inspect().state),
 
     // Phase 31 (DDR-123) — ACP chat readiness. Cheap, side-effect-free probe
     // (is the adapter present + is `claude` on PATH); no subprocess spawned.
@@ -1342,6 +1426,19 @@ export function createHttp(
               cloud: {
                 dashboardUrl: process.env.HUB_DASHBOARD_URL ?? 'https://cloud.maude.sh',
                 projectName: process.env.MAUDE_PROJECT_NAME ?? ctx.cfg.name ?? null,
+                // WHO the tab is signed in as, and WHAT that makes them —
+                // per REQUEST, from the proxy's injected headers, never from
+                // this process's environment (one cell serves an owner and a
+                // viewer at the same time).
+                //
+                // The owner who could not edit his own project could not see
+                // why: the stamp said VIEW ONLY and nothing on screen said
+                // which account that verdict was about. Naming the account and
+                // the role turns "this is broken" into "I am signed in as the
+                // wrong person", which is a thing someone can act on — and the
+                // sign-out beside it is how they act on it.
+                user: req.headers.get('x-maude-user') || null,
+                role: req.headers.get('x-maude-role') || null,
               },
             }
           : {}),
@@ -1366,7 +1463,7 @@ export function createHttp(
         buildDebugBundle({
           maudeVersion: resolveMaudeVersion(),
           projectName: ctx.cfg.name ?? null,
-          activeCanvas: (inspect.state as { active?: string | null }).active ?? null,
+          activeCanvas: (inspect().state as { active?: string | null }).active ?? null,
           repoRoot: ctx.paths.repoRoot,
         }),
         { headers: { 'Cache-Control': 'no-store' } }
@@ -1708,6 +1805,17 @@ export function createHttp(
       // identity. Color-hash derives from this; falls back to anonymous-<pid>
       // client-side when empty.
       if (req.method !== 'GET') return new Response('Method not allowed', { status: 405 });
+      // Cloud Phase 27 — IN A CELL, `git config user.name` IS THE MACHINE.
+      //
+      // It is "Maude Workspace", the committer the autosave agent signs with
+      // (sync/autocommit.ts), and it is the right answer for a commit and the
+      // wrong one for a person: a member opened their project and the presence
+      // chip introduced them as the server. The proxy already vouches who this
+      // is per request, so in a cell that is who it is.
+      const vouched = req.headers.get('x-maude-user');
+      if (isWorkspaceMode() && vouched) {
+        return Response.json({ name: vouched }, { headers: { 'Cache-Control': 'no-store' } });
+      }
       const name = await api.gitCurrentUser();
       return Response.json({ name }, { headers: { 'Cache-Control': 'no-store' } });
     },
@@ -4381,15 +4489,38 @@ export function createHttp(
         return serveMediaFile(fp, req, { 'X-Content-Type-Options': 'nosniff' });
       }
       // Bun.file streams transparently for binary content.
+      //
+      // B2 — THIS is the lane a design system's own photographs and webfonts
+      // come down (`system/<ds>/assets/graphics/camo-bg.png`, 446 kB;
+      // `…/fonts/*.woff2`). `no-store` here meant a teammate re-downloaded all
+      // of it on every pan, across the internet, on a project whose media is
+      // 266 MB. Verified against the real one after the first cloud deploy said
+      // `no-store` on exactly these files.
+      //
+      // `cacheControlFor` gives content-addressed names a year and everything
+      // else a revalidation — so a designer editing `hero.png` in place still
+      // sees the edit, at the cost of a 304 rather than the file.
+      const policy = cacheControlFor(fp);
       return new Response(file, {
         headers: {
           'Content-Type': MIME[e] || 'application/octet-stream',
-          'Cache-Control': 'no-store',
+          'Cache-Control': policy.cacheControl,
+          ...(policy.addEtag
+            ? {
+                ETag: `W/"${file.size.toString(16)}-${Math.trunc(file.lastModified).toString(16)}"`,
+              }
+            : {}),
           // DDR-088 follow-up — never let a browser MIME-sniff a served file
           // (e.g. an uploaded GIF/WEBP polyglot) into a richer type. Assets are
           // only referenced via <image href> + the canvas CSP blocks script, so
           // this is defense-in-depth on the static lane.
           'X-Content-Type-Options': 'nosniff',
+          // …and `nosniff` is not enough for the one type that is a DOCUMENT
+          // whether you sniff it or not. See INERT_DOCUMENT_CSP: an SVG
+          // NAVIGATED TO is a page with `<script>` in it, executing on this
+          // origin, and "the canvas CSP blocks script" above is true only of
+          // the shell — not of the asset served on its own.
+          ...(e === '.svg' ? { 'Content-Security-Policy': INERT_DOCUMENT_CSP } : {}),
         },
       });
     } catch (err) {
@@ -4401,7 +4532,7 @@ export function createHttp(
   async function serveCanvasShell(applyCsp: boolean, capture = false): Promise<Response> {
     const shellHtml = await Bun.file(join(TEMPLATES_DIR, '_shell.html')).text();
     // Inject inspector overlay — Cmd+Click selection + add-comment flow.
-    const injected = inspect.injectInspector(shellHtml);
+    const injected = inspect().injectInspector(shellHtml);
     const headers: Record<string, string> = {
       'Content-Type': 'text/html; charset=utf-8',
       'Cache-Control': 'no-store',
@@ -4504,7 +4635,22 @@ export function createHttp(
     if (safe.startsWith(designPrefix)) {
       const rest = safe.slice(designPrefix.length);
       // Reject runtime/state dirs+files (_comments, _sync.json, _history, …).
-      if (rest.split('/').some((seg) => seg.startsWith('_'))) return false;
+      //
+      // FIRST SEGMENT ONLY, and that is the taxonomy rather than a relaxation.
+      // Every runtime-state path DDR-115 names lives at the top level of the
+      // designRoot — `_history/`, `_canvas-state/`, `_state/`, `_chat/`,
+      // `_comments/`, `_untrusted/`, `_trash/`, `_draw/`, `_smoke/`,
+      // `_server.json`, `_active.json` — so a first-segment test rejects the
+      // whole of it, including everything nested underneath.
+      //
+      // Testing EVERY segment additionally rejected files that are versioned,
+      // shipped, and required: a design system's `system/<ds>/preview/
+      // _components.css` is the stylesheet the shell itself names in the
+      // iframe URL, and the underscore there is the DS's own convention for
+      // "aggregate, not a specimen". It 403'd, so every canvas rendered with
+      // its component styles missing and looked broken in a way that pointed
+      // nowhere near this line.
+      if (rest.split('/')[0].startsWith('_')) return false;
       return CANVAS_ASSET_EXTS.has(ext(safe));
     }
     // DDR-150 dogfood — `/assets/<file>`: the canvas-RELATIVE form every writer

package/apps/studio/inspect.ts

@@ -4,6 +4,7 @@
 import path from 'node:path';
 
 import type { Context } from './context.ts';
+import { normalizeSessionKey, sessionFile } from './session-scope.ts';
 
 export interface SelectedElement {
   file: string;
@@ -96,6 +97,8 @@ type SetSelectedInput =
   | null;
 
 export interface Inspect {
+  /** Whose state this is — `''` for the shared singleton (D3). */
+  sessionKey: string;
   state: ActiveState;
   load(): Promise<void>;
   setActive(file: string): void;
@@ -126,9 +129,16 @@ const NEW = (): ActiveState => ({
 
 export function createInspect(
   ctx: Context,
-  loadActiveComments: (file: string) => Promise<unknown[]>
+  loadActiveComments: (file: string) => Promise<unknown[]>,
+  /**
+   * Whose state this is — Cloud Phase 27 D3. `''` is the shared singleton every
+   * desktop has always had; a non-empty key gives one member of a cell their
+   * own selection, their own open tab, and their own `_active.<key>.json`.
+   */
+  sessionKey = ''
 ): Inspect {
   const state: ActiveState = NEW();
+  const activeFile = sessionFile(ctx.paths.activeFile, sessionKey);
   let saveQueued = false;
 
   async function save() {
@@ -144,7 +154,7 @@ export function createInspect(
         }
       }
       const enriched = { ...state, active_comments };
-      await Bun.write(ctx.paths.activeFile, JSON.stringify(enriched, null, 2));
+      await Bun.write(activeFile, JSON.stringify(enriched, null, 2));
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
       console.error('  warn: failed to save _active.json:', msg);
@@ -159,7 +169,7 @@ export function createInspect(
 
   async function load() {
     try {
-      const raw = await Bun.file(ctx.paths.activeFile).text();
+      const raw = await Bun.file(activeFile).text();
       const prev = JSON.parse(raw);
       Object.assign(state, prev, { session_started: new Date().toISOString() });
       // Pre-selections _active.json (or a hand-edited one) → keep the invariant.
@@ -222,10 +232,10 @@ export function createInspect(
     state.selected = file ? restoreFor(file) : null;
     state.last_change = new Date().toISOString();
     scheduleSave();
-    ctx.bus.emit('active', state.active);
+    ctx.bus.emit('active', state.active, { session: sessionKey });
     // Clients (StatusBar, shell halo, chat context chip) must see the restored
     // selection, not assume the pre-switch null.
-    ctx.bus.emit('selected', state.selected);
+    ctx.bus.emit('selected', state.selected, { session: sessionKey });
   }
 
   function setOpenTabs(tabs: string[]) {
@@ -320,7 +330,7 @@ export function createInspect(
     }
     state.last_change = new Date().toISOString();
     scheduleSave();
-    ctx.bus.emit('selected', state.selected);
+    ctx.bus.emit('selected', state.selected, { session: sessionKey });
   }
 
   function retarget(fromFile: string, toFile: string): boolean {
@@ -379,6 +389,7 @@ export function createInspect(
   }
 
   return {
+    sessionKey,
     state,
     load,
     setActive,
@@ -390,6 +401,55 @@ export function createInspect(
   };
 }
 
+/**
+ * One `Inspect` per member — Cloud Phase 27 D3.
+ *
+ * A desktop asks for `for('')` forever and gets the single instance it always
+ * had. A cell asks with the proxy's vouched session key and gets one per
+ * member, so an owner and a viewer stop overwriting each other's open tab and
+ * selection.
+ *
+ * Instances are created on demand and kept: they are small (one state object),
+ * a member reconnects to the same key across reloads, and evicting one would
+ * lose exactly the state this exists to preserve. The key space is bounded by
+ * the project's membership, not by anything a client can invent —
+ * `normalizeSessionKey` rejects a value that is not proxy-shaped, and the proxy
+ * strips inbound `x-maude-*` before injecting its own.
+ */
+export interface InspectRegistry {
+  /** The instance for this session key, created on first use. */
+  for(sessionKey?: string | null): Inspect;
+  /** Every live instance. */
+  all(): Inspect[];
+}
+
+export function createInspectRegistry(
+  ctx: Context,
+  loadActiveComments: (file: string) => Promise<unknown[]>
+): InspectRegistry {
+  const instances = new Map<string, Inspect>();
+
+  function get(sessionKey?: string | null): Inspect {
+    const key = normalizeSessionKey(sessionKey);
+    let found = instances.get(key);
+    if (!found) {
+      found = createInspect(ctx, loadActiveComments, key);
+      instances.set(key, found);
+      // A member returning after a reload picks their own place back up. Fire
+      // and forget: `load()` is a best-effort read of a file that usually does
+      // not exist yet, and blocking a request on it would trade a correctness
+      // nicety for latency on every first touch.
+      if (key) void found.load();
+    }
+    return found;
+  }
+
+  return {
+    for: get,
+    all: () => [...instances.values()],
+  };
+}
+
 // ---------- Inspector script injection ----------
 
 function injectInspector(html: string): string {

package/apps/studio/server.ts

@@ -31,8 +31,9 @@ import { createFsWatch } from './fs-watch.ts';
 import { createGenerationJobQueue } from './generation/jobs.ts';
 import { createGitWatch } from './git/watch.ts';
 import { createHttp } from './http.ts';
-import { createInspect } from './inspect.ts';
+import { createInspectRegistry } from './inspect.ts';
 import { startHeapWatch } from './mem.ts';
+import { normalizeSessionKey, runInSession, SESSION_HEADER } from './session-scope.ts';
 import { createSyncRuntime } from './sync/index.ts';
 import {
   assertContainment,
@@ -71,7 +72,7 @@ let collab: ReturnType<typeof createCollab> | null = null;
 // Forward-declared for the same reason — moveCanvas (feature-file-tree-
 // drag-drop-folders, Task 3) retargets `_active.json` through the live
 // Inspect instance, which is constructed after `api`.
-let inspectHandle: ReturnType<typeof createInspect> | null = null;
+let inspectHandle: ReturnType<typeof createInspectRegistry> | null = null;
 
 const api = createApi(ctx, {
   onCommentsChanged: async (file) => {
@@ -100,13 +101,17 @@ const api = createApi(ctx, {
     if (collab) await collab.registry.forceDrop(slug);
   },
   retargetActive: (fromFile, toFile) => {
-    inspectHandle?.retarget(fromFile, toFile);
+    // D3 — a canvas moved on disk moved for EVERY member, so every member's
+    // state is retargeted, not just the one whose request did it.
+    for (const one of inspectHandle?.all() ?? []) one.retarget(fromFile, toFile);
   },
 });
 
-const inspect = createInspect(ctx, (file) => api.loadCommentsForFile(file));
-inspectHandle = inspect;
-await inspect.load();
+const inspects = createInspectRegistry(ctx, (file) => api.loadCommentsForFile(file));
+inspectHandle = inspects;
+// The shared instance is the desktop's, and a cell's fallback for anything that
+// arrives without a vouched session.
+await inspects.for('').load();
 
 collab = createCollab(ctx, api);
 const aiActivity = createAiActivity(ctx);
@@ -134,11 +139,11 @@ const activity = createActivity(ctx);
 // editing" banner + presence as /design:edit (RC5,
 // rca/issue-canvas-hmr-optimistic-update-consistency).
 const acp = createAcp(ctx, aiActivity);
-const ws = createWs(ctx, api, inspect, collab, activity, acp);
+const ws = createWs(ctx, api, inspects, collab, activity, acp);
 const exportJobs = createExportJobQueue(ctx.bus, ctx.paths.designRoot);
 // feature-ai-media-generation (DDR-16x) — background AI-media generation queue.
 const generateJobs = createGenerationJobQueue(ctx.bus, ctx.paths.designRoot);
-const http = createHttp(ctx, api, inspect, aiActivity, exportJobs, generateJobs);
+const http = createHttp(ctx, api, inspects, aiActivity, exportJobs, generateJobs);
 const fsWatch = createFsWatch(ctx);
 
 // Port: --port arg > $PORT > $MDCC_DEV_PORT > 4399.
@@ -196,7 +201,51 @@ const SANDBOX_ARMED = isSandboxArmed();
 // post-condition on the pruning rather than a second, driftable opinion. A
 // prefix added to the vocabulary then both prunes and is verified, together.
 const pruned = WORKSPACE ? pruneForWorkspace(http.routes) : { routes: http.routes, removed: [] };
-const SERVER_ROUTES = pruned.routes as typeof http.routes;
+/**
+ * Establish WHOSE request this is, once, at the only place every request passes
+ * through — Cloud Phase 27 D3.
+ *
+ * Bun matches `routes` BEFORE `fetch`, so a wrapper on the fall-through alone
+ * would miss the entire route table (the same asymmetry that made a
+ * canvas-origin route 404 in Phase 23). Wrapping here covers both halves, and
+ * the leaves — `canvasViewPath`, `canvasStatePath` — read the ambient key
+ * instead of every function between here and there growing a parameter.
+ *
+ * Outside workspace mode this resolves to `''` on every request, which
+ * `runInSession` treats as "no scope at all" and skips.
+ */
+function withSession<T extends unknown[]>(
+  handler: (req: Request, ...rest: T) => Response | Promise<Response>
+): (req: Request, ...rest: T) => Response | Promise<Response> {
+  return (req, ...rest) =>
+    runInSession(WORKSPACE ? normalizeSessionKey(req.headers.get(SESSION_HEADER)) : '', () =>
+      handler(req, ...rest)
+    );
+}
+
+/** Bun route entries are either a handler or a `{ GET, POST, … }` map. */
+function scopeRoutes<R extends Record<string, unknown>>(routes: R): R {
+  const out: Record<string, unknown> = {};
+  for (const [path, entry] of Object.entries(routes)) {
+    if (typeof entry === 'function') {
+      out[path] = withSession(entry as (req: Request) => Response | Promise<Response>);
+    } else if (entry && typeof entry === 'object') {
+      const byMethod: Record<string, unknown> = {};
+      for (const [method, fn] of Object.entries(entry as Record<string, unknown>)) {
+        byMethod[method] =
+          typeof fn === 'function'
+            ? withSession(fn as (req: Request) => Response | Promise<Response>)
+            : fn;
+      }
+      out[path] = byMethod;
+    } else {
+      out[path] = entry;
+    }
+  }
+  return out as R;
+}
+
+const SERVER_ROUTES = scopeRoutes(pruned.routes) as typeof http.routes;
 if (WORKSPACE && pruned.removed.length > 0) {
   console.log(
     `[studio] workspace mode — withheld ${pruned.removed.length} route(s) that would evaluate ` +
@@ -265,9 +314,20 @@ function startServer(port: number): BunServer {
       // Phase 8 — collab WS, binary y-websocket protocol. Loopback-only;
       // DDR-047 makes cross-machine collab a Phase 9 hub-deploy story, not
       // a `--bind 0.0.0.0` flag on this server.
+      //
+      // IN A CELL the loopback gate can never pass — the hub's authenticating
+      // proxy rewrites Host to the public URL (D4) on purpose — and it must not
+      // have to: the proxy already terminated the session and vouches the role
+      // per request with injected `x-maude-*` headers (stripped-then-injected,
+      // the Cloud Phase 27 model the inspector branch below already trusts).
+      // Without this vouched path every cloud collab upgrade 403'd here and
+      // cursors/annotations/live-sync were dead in the browser door — RCA
+      // issue-cloud-live-collaboration-dead. Outside workspace mode the DDR-047
+      // gate is verbatim unchanged.
       const collabSlug = parseCollabSlug(pathname);
       if (collabSlug !== null) {
-        if (!isLoopbackHost(req.headers.get('host'))) {
+        const vouchedRole = WORKSPACE ? req.headers.get('x-maude-role') : null;
+        if (!isLoopbackHost(req.headers.get('host')) && !vouchedRole) {
           return new Response('cross-machine collab requires Phase 9 hub deploy', {
             status: 403,
           });
@@ -278,8 +338,15 @@ function startServer(port: number): BunServer {
             remote: req.headers.get('x-forwarded-for') ?? '127.0.0.1',
             kind: 'collab',
             slug: collabSlug,
-            // Privileged shell origin — ungated (see collab/origins.ts).
-            realm: 'main',
+            // Privileged shell origin — ungated (see collab/origins.ts) —
+            // UNLESS the proxy marked this socket as canvas-realm (a cell's
+            // canvas lane forwards here when the canvas listener is the same
+            // process; defense in depth either way).
+            realm:
+              WORKSPACE && req.headers.get('x-maude-collab-realm') === 'canvas' ? 'canvas' : 'main',
+            // Same fail-closed posture as the inspector branch: in a cell an
+            // absent header is an unproven session.
+            readOnly: WORKSPACE ? req.headers.get('x-maude-readonly') !== '0' : false,
           },
         });
         if (ok) return undefined as unknown as Response;
@@ -319,6 +386,9 @@ function startServer(port: number): BunServer {
             id: crypto.randomUUID(),
             remote: req.headers.get('x-forwarded-for') ?? '127.0.0.1',
             kind: 'inspector',
+            // D3 — whose socket this is, from the proxy's vouched header. Same
+            // handshake-time reasoning as `readOnly` below; `''` on a desktop.
+            session: WORKSPACE ? normalizeSessionKey(req.headers.get(SESSION_HEADER)) : '',
             // Cloud Phase 27 — stamp the role onto the socket at the handshake,
             // the one moment the session is unambiguous. Fails CLOSED in a cell
             // for the same reason the HTTP gate does: an absent header is an
@@ -330,7 +400,8 @@ function startServer(port: number): BunServer {
         if (ok) return undefined as unknown as Response;
         return new Response('Upgrade failed', { status: 400 });
       }
-      return http.fetch(req);
+      // D3 — the fall-through half of the same scope the route table gets above.
+      return withSession(http.fetch)(req);
     },
     websocket: ws.handler,
     error(e) {
@@ -382,10 +453,15 @@ function startCanvasServer(port: number): BunServer {
     async fetch(req, srv) {
       const pathname = new URL(req.url).pathname;
 
-      // Collab WS — shared registry, loopback-only (same gate as the main origin).
+      // Collab WS — shared registry, loopback-only (same gate as the main
+      // origin), with the same workspace-mode vouched path: in a cell the hub's
+      // canvas lane forwards the iframe's collab socket HERE, capability-
+      // authenticated, with Host rewritten to the public canvas origin (D4) —
+      // RCA issue-cloud-live-collaboration-dead.
       const collabSlug = parseCollabSlug(pathname);
       if (collabSlug !== null) {
-        if (!isLoopbackHost(req.headers.get('host'))) {
+        const vouchedRole = WORKSPACE ? req.headers.get('x-maude-role') : null;
+        if (!isLoopbackHost(req.headers.get('host')) && !vouchedRole) {
           return new Response('cross-machine collab requires Phase 9 hub deploy', { status: 403 });
         }
         const ok = srv.upgrade(req, {
@@ -396,8 +472,13 @@ function startCanvasServer(port: number): BunServer {
             slug: collabSlug,
             // UNTRUSTED canvas iframe origin (DDR-063 split). Every sync frame
             // from here goes through the origin gate and may never write a
-            // body lane — DDR-122 follow-up, collab/origins.ts.
+            // body lane — DDR-122 follow-up, collab/origins.ts. ALWAYS
+            // 'canvas' on this listener — the proxy's realm marker is not
+            // consulted, so a forged header cannot promote the socket.
             realm: 'canvas',
+            // Fail closed in a cell (absent header = unproven session);
+            // loopback desktop keeps full capability as before.
+            readOnly: WORKSPACE ? req.headers.get('x-maude-readonly') !== '0' : false,
           },
         });
         if (ok) return undefined as unknown as Response;
@@ -483,7 +564,23 @@ let server: BunServer;
 // listed: the server binds 127.0.0.1, so a user who opens the printed URL as
 // `127.0.0.1:<port>` is the same legit embedder — with only `localhost` allowed
 // the canvas iframe was silently refused (blank sad-page, no error anywhere).
-ctx.mainOrigin = `http://localhost:${server.port} http://127.0.0.1:${server.port}`;
+//
+// D4 AGAIN — the PUBLIC name, not the bound one. In a cell the parent frame is
+// `https://<project>.cloud.maude.sh`; listing only the loopback origins made the
+// browser refuse to render the canvas iframe at all ("refused to connect"),
+// which looks like a network failure and is a CSP one. The loopback spellings
+// stay for local tooling (screenshots, smoke) — a cell simply has one more legit
+// embedder, and naming it is configuration, never a Host header.
+const publicShellOrigin = (() => {
+  const url = process.env.HUB_PUBLIC_URL;
+  if (!url) return '';
+  try {
+    return ` ${new URL(url).origin}`;
+  } catch {
+    return '';
+  }
+})();
+ctx.mainOrigin = `http://localhost:${server.port} http://127.0.0.1:${server.port}${publicShellOrigin}`;
 
 // T2 (9.1-A) — segregated canvas-content origin. ON BY DEFAULT (opt-OUT) since
 // phase-9.1: a second listener binds an OS-assigned free port, advertised as