@1agh/maude 0.53.1 → 0.53.2

package/apps/studio/test/canvas-build-sandbox.test.ts

@@ -0,0 +1,69 @@
+// Cloud Phase 27 — the sandbox child's environment.
+//
+// Diagnosed against a real cell: the canvas module 422'd with "Cannot find
+// native binding" while running the identical worker command by hand with a
+// clean environment worked. The difference was one inherited variable.
+
+import { describe, expect, test } from 'bun:test';
+
+import { workerEnv } from '../canvas-build-sandbox.ts';
+
+describe('workerEnv', () => {
+  test('a compiled binary’s VIRTUAL binding path is not handed to a child', () => {
+    const env = workerEnv({
+      PATH: '/bin',
+      NAPI_RS_NATIVE_LIBRARY_PATH: '/$bunfs/root/parser.linux-arm64-gnu.node',
+    } as NodeJS.ProcessEnv);
+    expect(env.NAPI_RS_NATIVE_LIBRARY_PATH).toBeUndefined();
+  });
+
+  test('a REAL binding path still is', () => {
+    const env = workerEnv({
+      PATH: '/bin',
+      NAPI_RS_NATIVE_LIBRARY_PATH: '/maude/node_modules/@oxc-parser/binding-linux-arm64-gnu',
+    } as NodeJS.ProcessEnv);
+    expect(env.NAPI_RS_NATIVE_LIBRARY_PATH).toBe(
+      '/maude/node_modules/@oxc-parser/binding-linux-arm64-gnu'
+    );
+  });
+
+  test('the child environment carries no secret — it parses tenant source', () => {
+    const env = workerEnv({
+      PATH: '/bin',
+      HUB_SECRET: 'nope',
+      AWS_SECRET_ACCESS_KEY: 'also-nope',
+      MAUDE_PROJECT_TOKEN_KEY: 'definitely-nope',
+    } as NodeJS.ProcessEnv);
+    expect(env.HUB_SECRET).toBeUndefined();
+    expect(env.AWS_SECRET_ACCESS_KEY).toBeUndefined();
+    expect(env.MAUDE_PROJECT_TOKEN_KEY).toBeUndefined();
+  });
+});
+
+// Cloud Phase 27 B2 — content-addressed media is immutable; everything else
+// revalidates. `no-store` is right on a laptop and is a re-download of every
+// photograph on every pan over the internet.
+import { cacheControlFor } from '../http.ts';
+
+describe('cacheControlFor', () => {
+  test('a content-addressed name is immutable — the name IS the content', () => {
+    for (const p of ['/x/assets/deadbeef.png', '/a/b/0123456789abcdef.mp4']) {
+      expect(cacheControlFor(p).cacheControl).toBe('public, max-age=31536000, immutable');
+      expect(cacheControlFor(p).addEtag).toBe(false);
+    }
+  });
+
+  test('an AUTHORED name revalidates — a designer edits hero.png in place', () => {
+    for (const p of ['/x/assets/hero.png', '/x/system/ds/colors_and_type.css', '/x/logos.svg']) {
+      expect(cacheControlFor(p).cacheControl).toBe('no-cache');
+      expect(cacheControlFor(p).addEtag).toBe(true);
+    }
+  });
+
+  test('a name that merely LOOKS hex-ish is not treated as content-addressed', () => {
+    // `deadbee` is 7 chars; `deadbeefs` has a non-hex char. Getting either
+    // wrong caches a mutable file for a year.
+    expect(cacheControlFor('/x/deadbee.png').cacheControl).toBe('no-cache');
+    expect(cacheControlFor('/x/deadbeefs.png').cacheControl).toBe('no-cache');
+  });
+});

package/apps/studio/test/canvas-origin-gate.test.ts

@@ -156,6 +156,11 @@ describe('canvas-origin gate — A1/A2 traversal + privilege containment', () =>
         '/_api/debug-bundle',
         '/_api/report',
         '/_api/report-fallback',
+        // …and the shell capture SPAWNS A PROCESS (screenshot.sh → a headless
+        // browser) and renders the whole project. Reachable from the canvas
+        // origin it would be a resource-exhaustion lever driven by untrusted
+        // canvas code, so it carries the same main-origin-only posture.
+        '/_api/shell-shot',
         // Stage F1 — the AssetPicker's asset-listing GET is a shell (main-origin)
         // concern; the untrusted canvas iframe must not enumerate project media.
         '/_api/assets',

package/apps/studio/test/canvas-url.test.ts

@@ -110,3 +110,29 @@ describe('canvasUrl — per-canvas design-system token resolution', () => {
     ).toBeNull();
   });
 });
+
+// Cloud Phase 27 (DDR-209) — the canvas origin's capability.
+//
+// In the cloud the canvas origin is a cookieless, cross-site hostname: a cookie
+// scoped widely enough to cover it would be readable by the untrusted canvas
+// content itself, which is the one thing the DDR-054 split exists to prevent.
+// So the capability rides in the URL. It reaches `cfg` through the `/_config`
+// projection — which silently dropped it once, and would have 401'd every
+// canvas iframe in production (see `config-projection.test.ts`).
+
+test('a canvas URL carries the capability when the server minted one', () => {
+  const url = canvasUrl('.design/ui/Home.tsx', {
+    designRel: '.design',
+    canvasOrigin: 'https://canvas.cloud.maude.sh/alligators',
+    canvasToken: 'cap-abc123',
+  });
+  expect(url.startsWith('https://canvas.cloud.maude.sh/alligators/_canvas-shell.html?')).toBe(true);
+  expect(new URL(url).searchParams.get('t')).toBe('cap-abc123');
+});
+
+test('a desktop URL is byte-identical to before — no capability, no query', () => {
+  // The loopback canvas origin needs none, so this must not change for the
+  // shell that has always worked.
+  const url = canvasUrl('.design/ui/Home.tsx', { designRel: '.design' });
+  expect(new URL(url, 'http://x').searchParams.has('t')).toBe(false);
+});

package/apps/studio/test/cloud-session-role.test.ts

@@ -0,0 +1,131 @@
+// Cloud Phase 27 A3/A4 + C2/C4 (DDR-209) — the studio in a cell.
+//
+// The behaviour under test is the one that makes a cell multi-tenant-safe: in
+// workspace mode this process serves an owner and a viewer at the SAME TIME, so
+// "what may this request do" cannot come from a file on disk. It comes from the
+// proxy in front, per request, and in the absence of proof it is `viewer`.
+//
+// The local gate this replaces fails OPEN by design — `isHubReadOnly()` returns
+// false from its `catch`, and `projectReadOnly()` returns false when `linkedHub`
+// is unset. That is correct for a tool on your own laptop and is the whole
+// ballgame on the internet, which is why the no-header case below is the most
+// important assertion in the file.
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import type { Subprocess } from 'bun';
+
+import { bootServer, killProc, makeSandbox, nextPort } from './_helpers.ts';
+
+const procs: Subprocess[] = [];
+afterAll(async () => {
+  for (const p of procs) await killProc(p);
+});
+
+async function bootCell() {
+  const { root } = makeSandbox();
+  const port = nextPort();
+  const proc = await bootServer(root, port, {
+    MAUDE_WORKSPACE_MODE: '1',
+    // A dev checkout resolves Playwright (the E2E harness), which is a
+    // legitimate devDependency here and would otherwise fail the module half of
+    // the containment assert before workspace mode could be tested at all.
+    MAUDE_WORKSPACE_ALLOW_DEV_MODULES: '1',
+    HUB_DASHBOARD_URL: 'https://cloud.maude.sh',
+    MAUDE_PROJECT_NAME: 'Alligators',
+  });
+  procs.push(proc);
+  return { base: `http://localhost:${port}` };
+}
+
+describe('a cell resolves the role per request, and defaults to read-only', () => {
+  test('no injected role at all ⇒ read-only, and writes are refused', async () => {
+    const { base } = await bootCell();
+
+    const cfg = (await (await fetch(`${base}/_config`)).json()) as { readOnly?: boolean };
+    expect(cfg.readOnly).toBe(true);
+
+    const res = await fetch(`${base}/_api/edit-text`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ file: 'ui/Sample.tsx', id: 'x', text: 'y' }),
+    });
+    expect(res.status).toBe(403);
+    expect(((await res.json()) as { reason?: string }).reason).toBe('read-only');
+  });
+
+  test('a vouched editing role opens the same write', async () => {
+    const { base } = await bootCell();
+
+    const cfg = (await (
+      await fetch(`${base}/_config`, { headers: { 'x-maude-readonly': '0' } })
+    ).json()) as { readOnly?: boolean };
+    expect(cfg.readOnly).toBe(false);
+
+    const res = await fetch(`${base}/_api/edit-text`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-maude-readonly': '0' },
+      body: JSON.stringify({ file: 'ui/Sample.tsx', id: 'x', text: 'y' }),
+    });
+    // Whatever the handler makes of the payload, the GATE let it through — the
+    // read-only refusal is the specific thing that must not happen.
+    expect(res.status).not.toBe(403);
+  });
+
+  test('anything other than a positive `0` is read-only', async () => {
+    // The failure mode this rules out: a truthy-string check, where
+    // `x-maude-readonly: false` (a plausible thing for a future caller to send)
+    // reads as "not read-only".
+    const { base } = await bootCell();
+    for (const value of ['1', 'false', 'no', '', 'true', 'owner']) {
+      const cfg = (await (
+        await fetch(`${base}/_config`, { headers: { 'x-maude-readonly': value } })
+      ).json()) as { readOnly?: boolean };
+      expect(cfg.readOnly).toBe(true);
+    }
+  });
+
+  test('two requests to ONE process get two different answers', async () => {
+    // The actual multi-tenancy property, stated as a test: this is what a
+    // per-PROCESS config file cannot do, and it is why A3 exists.
+    const { base } = await bootCell();
+    const [viewer, member] = await Promise.all([
+      fetch(`${base}/_config`, { headers: { 'x-maude-readonly': '1' } }).then((r) => r.json()),
+      fetch(`${base}/_config`, { headers: { 'x-maude-readonly': '0' } }).then((r) => r.json()),
+    ]);
+    expect((viewer as { readOnly: boolean }).readOnly).toBe(true);
+    expect((member as { readOnly: boolean }).readOnly).toBe(false);
+  });
+});
+
+describe('the cloud shell states what it is', () => {
+  test('/_config carries the cloud block C2 and C4 render from', async () => {
+    const { base } = await bootCell();
+    const cfg = (await (await fetch(`${base}/_config`)).json()) as {
+      cloud?: { dashboardUrl?: string; projectName?: string };
+    };
+    expect(cfg.cloud).toBeTruthy();
+    expect(cfg.cloud?.dashboardUrl).toBe('https://cloud.maude.sh');
+    expect(cfg.cloud?.projectName).toBe('Alligators');
+  });
+
+  test('the canvas capability is echoed only when the proxy minted one', async () => {
+    const { base } = await bootCell();
+    const without = (await (await fetch(`${base}/_config`)).json()) as { canvasToken?: string };
+    expect(without.canvasToken).toBeUndefined();
+
+    const with_ = (await (
+      await fetch(`${base}/_config`, { headers: { 'x-maude-canvas-token': 'cap-123' } })
+    ).json()) as { canvasToken?: string };
+    expect(with_.canvasToken).toBe('cap-123');
+  });
+
+  test('a cell SERVES the canvas surfaces it used to 404 (DDR-209 A′1)', async () => {
+    const { base } = await bootCell();
+    // The shell is a static harness; the browser is what evaluates it. Before
+    // DDR-209 this was a hard 404 in workspace mode, which is precisely why
+    // Phase 25 had to hand-roll a second studio.
+    const shell = await fetch(`${base}/_canvas-shell.html`);
+    expect(shell.status).toBe(200);
+    expect(shell.headers.get('content-type')).toContain('text/html');
+  });
+});

package/apps/studio/test/cloud-shell-surfaces.test.ts

@@ -0,0 +1,90 @@
+// Surfaces a cloud tab must not offer — Cloud Phase 27, found by using it.
+//
+// The phase's rule is C1's: role shapes what is OFFERED, never what is VISIBLE.
+// That rule is about ROLES. A different question turned up the moment the real
+// studio actually ran in a browser: what about a control whose feature cannot
+// exist in THIS SHELL at all?
+//
+// Three answers, and the difference between them is the whole point:
+//
+//   the agent chat        ABSENT, WITH A NOTICE. It runs on your own Claude
+//                         subscription on your own machine (DDR-123). The
+//                         feature exists and you can have it — the menu row
+//                         stays, disabled, saying where. (C2)
+//
+//   "Sign in to Maude     ABSENT, SILENTLY. It offers to do the thing you have
+//    Cloud"               already done: you reached this tab THROUGH a Maude
+//                         account. There is nothing to explain.
+//
+//   AI generation /       ABSENT, SILENTLY. These configure ffmpeg, mlx-vlm, a
+//   Subtitles / Video     HuggingFace cache and your own provider keys — none
+//                         of which a browser tab has, and whose routes a cell
+//                         refuses by design (DDR-209 D1). Left in, they render
+//                         as a wall of `HTTP 404`, which is what the owner saw.
+//
+// Source-level assertions, because the menubar's dropdowns do not open under a
+// synthetic click and a test that cannot fail is worse than no test. What these
+// pin is exactly what would regress: someone re-introducing `TABS.map` or
+// dropping the gate on `<CloudBar />`.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const STUDIO = join(import.meta.dir, '..');
+const APP = readFileSync(join(STUDIO, 'client', 'app.jsx'), 'utf8');
+const SETTINGS = readFileSync(join(STUDIO, 'client', 'panels', 'SettingsPanel.jsx'), 'utf8');
+
+describe('the cloud shell offers nothing it cannot honour', () => {
+  test('the local-machine settings tabs are flagged, and only those three', () => {
+    const flagged = [
+      ...SETTINGS.matchAll(/\{ id: '([a-z-]+)', label: '[^']+', local: true \}/g),
+    ].map((m) => m[1]);
+    expect(flagged.sort()).toEqual(['ai-generation', 'subtitles', 'video']);
+  });
+
+  test('the tab rail renders the FILTERED list, not the raw table', () => {
+    // `TABS.map` is what shipped the wall of 404s.
+    expect(SETTINGS).toContain('{tabs.map((t) => (');
+    expect(SETTINGS).not.toContain('{TABS.map(');
+    // …and every keyboard path must walk the same list, or End/Home select a
+    // tab that is not on screen.
+    expect(SETTINGS).not.toMatch(/setTab\(TABS\[/);
+    expect(SETTINGS).toContain('const tabs = useMemo(');
+  });
+
+  test('a remembered tab this shell does not have cannot select nothing', () => {
+    // Open Video on the desktop, then open Settings in the cloud.
+    const init =
+      /const \[tab, setTab\] = useState\(\(\) => \{[\s\S]*?\}\);/.exec(SETTINGS)?.[0] ?? '';
+    expect(init).toContain('!(cloud && t.local)');
+  });
+
+  test('the cloud sign-in is not offered inside the cloud', () => {
+    expect(APP).toContain('{cloud ? null : <CloudBar />}');
+  });
+
+  test('every component that gates on the shell is actually GIVEN the flag', () => {
+    // The bug this exists for: three `cfg?.cloud` reads inside a component that
+    // never receives `cfg` — a ReferenceError at render, and a blank app.
+    for (const call of ['<Menubar', '<Sidebar', '<SettingsPanel']) {
+      const at = APP.indexOf(call);
+      expect(at).toBeGreaterThan(0);
+      const props = APP.slice(at, at + 900);
+      expect(props).toContain('cloud={cfg?.cloud ?? null}');
+    }
+  });
+
+  test('no component reaches for `cfg` where only the flag was passed', () => {
+    // `cfg` is a real variable at the top level, so a stray reference in a
+    // child component is a ReferenceError the bundler happily emits.
+    for (const fn of ['function Menubar({', 'function Sidebar({']) {
+      const start = APP.indexOf(fn);
+      expect(start).toBeGreaterThan(0);
+      // Bounded window: the component's own body, not the whole file.
+      const body = APP.slice(start, APP.indexOf('\nfunction ', start + 10));
+      expect(body).not.toMatch(/\bcfg\?\./);
+      expect(body).not.toMatch(/\bcfg\./);
+    }
+  });
+});

package/apps/studio/test/config-projection.test.ts

@@ -0,0 +1,104 @@
+// The `/_config` projection — Cloud Phase 27.
+//
+// WHAT WENT WRONG, TWICE IN ONE CHANGE.
+//
+// The server's `/_config` handler adds fields to the config it returns. The
+// client does NOT spread that response — it builds a new object naming each
+// field it wants (a deliberate choice: `/_config` and `/_index-data` race, and
+// a full replace would clobber `canvasDesignSystems`). So a field the server
+// starts returning arrives nowhere until somebody names it on the client too,
+// and NOTHING says so. Phase 27 added two and named neither:
+//
+//   `cloud`        → the cloud studio rendered without its "which project am I
+//                    in / how do I leave" chrome, silently.
+//   `canvasToken`  → every canvas iframe loaded the cookieless canvas origin
+//                    with no capability, so every canvas would have 401'd.
+//
+// Both shipped to production. The first was found by looking at the page; the
+// second had not been found at all.
+//
+// This test reads BOTH sides out of source and demands they agree. It is a
+// grep-gate, the same trade `scripts/check-containment.sh` makes, and it is
+// sound for the same reason: the shapes it matches are the ones both files have
+// had since they were written, and the "did the regex find anything" assertions
+// below are what stop it passing vacuously.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const STUDIO = join(import.meta.dir, '..');
+const HTTP_TS = readFileSync(join(STUDIO, 'http.ts'), 'utf8');
+const APP_JSX = readFileSync(join(STUDIO, 'client', 'app.jsx'), 'utf8');
+
+/**
+ * Fields the `/_config` handler adds ON TOP of the `...ctx.cfg` spread.
+ *
+ * The spread itself is not enumerable from source and does not need to be: it
+ * is the project's own config file, which the client already carries wholesale.
+ * The risk is in the COMPUTED fields — the ones the server decides per request.
+ */
+function serverComputedConfigFields(): string[] {
+  const start = HTTP_TS.indexOf("'/_config':");
+  expect(start).toBeGreaterThan(0);
+  // The handler is short; take to the end of its `Response.json({...})`.
+  const body = HTTP_TS.slice(start, start + 2000);
+  const end = body.indexOf('\n    // ');
+  const src = end > 0 ? body.slice(0, end) : body;
+
+  const fields = new Set<string>();
+  // `canvasOrigin: ctx.canvasOrigin,` / `readOnly: projectReadOnly(req),`
+  for (const m of src.matchAll(/^\s{8}([a-zA-Z][a-zA-Z0-9]*):\s/gm)) fields.add(m[1]);
+  // Conditionally-spread fields: `? { canvasToken: … }` / `? { cloud: { … } }`
+  for (const m of src.matchAll(/\?\s*\{\s*([a-zA-Z][a-zA-Z0-9]*):/g)) fields.add(m[1]);
+  return [...fields].sort();
+}
+
+/** Fields the client's `/_config` handler copies into `cfg`. */
+function clientProjectedFields(): string[] {
+  const start = APP_JSX.indexOf("fetch('/_config')");
+  expect(start).toBeGreaterThan(0);
+  const end = APP_JSX.indexOf('.catch(() => {});', start);
+  expect(end).toBeGreaterThan(start);
+  const src = APP_JSX.slice(start, end);
+  const fields = new Set<string>();
+  for (const m of src.matchAll(/^\s{10}([a-zA-Z][a-zA-Z0-9]*):\s/gm)) fields.add(m[1]);
+  return [...fields].sort();
+}
+
+describe('/_config projection', () => {
+  test('the scrape finds both sides — a regex that matches nothing approves everything', () => {
+    const server = serverComputedConfigFields();
+    const client = clientProjectedFields();
+    expect(server.length).toBeGreaterThanOrEqual(3);
+    expect(client.length).toBeGreaterThanOrEqual(5);
+    expect(server).toContain('readOnly');
+    expect(client).toContain('readOnly');
+  });
+
+  test('every field the server COMPUTES is named by the client', () => {
+    const client = new Set(clientProjectedFields());
+    const missing = serverComputedConfigFields().filter((f) => !client.has(f));
+    expect(missing).toEqual([]);
+  });
+
+  test('the two fields this gate was written for are both present', () => {
+    // Named explicitly as well as covered by the rule above, because these are
+    // the ones that actually shipped broken and a future refactor of the regex
+    // should not be able to quietly stop covering them.
+    const client = new Set(clientProjectedFields());
+    expect(client.has('canvasToken')).toBe(true);
+    expect(client.has('cloud')).toBe(true);
+  });
+
+  test('the client still MERGES rather than replaces', () => {
+    // The reason the projection is explicit in the first place: `/_config` and
+    // `/_index-data` race, and a full replace clobbers `canvasDesignSystems`
+    // (DDR-093). Anyone "simplifying" this into a spread of `data` must not
+    // also drop the functional merge.
+    const start = APP_JSX.indexOf("fetch('/_config')");
+    const src = APP_JSX.slice(start, APP_JSX.indexOf('.catch(() => {});', start));
+    expect(src).toContain('setCfg((prev) => ({');
+    expect(src).toContain('...prev,');
+  });
+});

package/apps/studio/test/read-only-gate.test.ts

@@ -128,3 +128,53 @@ describe('read-only gate — viewer role refuses project writes locally', () =>
     expect(r.status).not.toBe(403);
   }, 30000);
 });
+
+// ---------------------------------------------------------------------------
+// Cloud Phase 27 — the one write a viewer holds.
+//
+// The role matrix has said `viewer.comment === true` since Phase 25 C4 and the
+// People page promises it in those words. This list did not have it, so a
+// viewer's comment was allowed by the authority (the cell's proxy) and then
+// refused by the defence-in-depth layer behind it. Found by commenting as a
+// viewer against a real cell, not by reading either file.
+
+describe('a viewer may comment — the matrix says so, and so must this gate', () => {
+  test('comment + reply pass; annotate still does not', async () => {
+    const { base } = await boot('viewer');
+
+    const comment = await fetch(`${base}/_comments`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ file: 'ui/Sample.tsx', text: 'looks off to me' }),
+    });
+    expect(comment.status).not.toBe(403);
+
+    const reply = await fetch(`${base}/_api/comments/abc123/reply`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ text: 'agreed' }),
+    });
+    expect(reply.status).not.toBe(403);
+
+    // An annotation is drawn ON the design and versioned with it — the matrix
+    // files it with `edit`, and that distinction has to survive this change.
+    const annotate = await fetch(`${base}/_api/annotations`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ file: 'ui/Sample.tsx', svg: '<svg/>' }),
+    });
+    expect(annotate.status).toBe(403);
+  });
+
+  test('the reply pattern does not open the whole comment namespace', async () => {
+    const { base } = await boot('viewer');
+    for (const path of [
+      '/_api/comments/abc/delete',
+      '/_api/comments/abc/reply/../../edit-text',
+      '/_api/comments//reply',
+    ]) {
+      const res = await fetch(`${base}${path}`, { method: 'POST' });
+      expect(res.status).not.toBe(200);
+    }
+  });
+});

package/apps/studio/test/workspace-containment.test.ts

@@ -18,8 +18,10 @@ import {
   FORBIDDEN_ROUTE_PREFIXES,
   formatContainmentFailure,
   isForbiddenRoute,
+  isSandboxedRoute,
   isWorkspaceMode,
   pruneForWorkspace,
+  SANDBOXED_ROUTE_PREFIXES,
 } from '../workspace-mode.ts';
 
 const CELL = { MAUDE_WORKSPACE_MODE: '1' } as NodeJS.ProcessEnv;
@@ -73,8 +75,8 @@ describe('checkContainment — what a cell may serve', () => {
     for (const route of [
       '/_api/export-jobs',
       '/_api/export/png',
-      '/_canvas-shell.html',
-      '/_canvas-runtime/react.js',
+      '/_api/github/repos',
+      '/_api/claude/signin',
       '/_ws/acp',
     ]) {
       const report = checkContainment([...ALLOWED_ROUTES, route]);
@@ -145,18 +147,67 @@ describe('assertContainment — the boot gate', () => {
   test('the failure message names the surface, the reason, and the way out', () => {
     let message = '';
     try {
-      assertContainment([...ALLOWED_ROUTES, '/_canvas-shell.html'], { env: CELL });
+      assertContainment([...ALLOWED_ROUTES, '/_api/export'], { env: CELL });
     } catch (err) {
       message = (err as Error).message;
     }
-    expect(message).toContain('/_canvas-shell.html');
+    expect(message).toContain('/_api/export');
     expect(message).toContain('DDR-193');
-    expect(message).toContain('executes a canvas module');
+    expect(message).toContain('headless browser');
     // The escape hatch is named so the next engineer doesn't invent a flag.
     expect(message).toContain('Direction B');
     expect(message).toContain('HARD PREREQUISITE');
   });
 
+  // ---- DDR-209 A′1: the sandboxed lane -----------------------------------
+  //
+  // `/_canvas-shell` and `/_canvas-runtime` used to be on the forbidden list.
+  // They are not forbidden and they are not free: a cell may serve them ONLY
+  // while the out-of-process build sandbox is armed. These three tests are the
+  // difference between a reclassification and a loosening.
+
+  test('a canvas surface is REFUSED when the build sandbox is not armed', () => {
+    const report = checkContainment([...ALLOWED_ROUTES, '/_canvas-shell.html'], {
+      sandboxArmed: false,
+    });
+    expect(report.ok).toBe(false);
+    expect(report.unattested[0]?.route).toBe('/_canvas-shell.html');
+    // And it is NOT reported as forbidden — the two failures have different
+    // fixes, and collapsing them would send someone to delete a route that is
+    // supposed to be there.
+    expect(report.routes).toEqual([]);
+  });
+
+  test('a canvas surface is PERMITTED once the sandbox is armed', () => {
+    const report = checkContainment(
+      [...ALLOWED_ROUTES, '/_canvas-shell.html', '/_canvas-runtime/react.js'],
+      { sandboxArmed: true }
+    );
+    expect(report.ok).toBe(true);
+  });
+
+  test('the attestation defaults to UNMET — an unstated contract is not a contract', () => {
+    expect(checkContainment(['/_canvas-shell.html']).ok).toBe(false);
+  });
+
+  test('arming the sandbox does not permit anything on the FORBIDDEN list', () => {
+    // The failure this rules out: `sandboxArmed: true` becoming a master key.
+    const report = checkContainment([...ALLOWED_ROUTES, '/_api/export', '/_ws/acp'], {
+      sandboxArmed: true,
+    });
+    expect(report.ok).toBe(false);
+    expect(report.routes.map((r) => r.route).sort()).toEqual(['/_api/export', '/_ws/acp']);
+  });
+
+  test('the unattested message explains the contract rather than just refusing', () => {
+    const message = formatContainmentFailure(
+      checkContainment(['/_canvas-shell.html'], { sandboxArmed: false })
+    );
+    expect(message).toContain('BUILD SANDBOX is not armed');
+    expect(message).toContain('EMPTY environment');
+    expect(message).toContain('DDR-209');
+  });
+
   test('formatContainmentFailure reports routes and modules together', () => {
     const report = checkContainment([...ALLOWED_ROUTES, '/_api/export'], {
       resolveModule: (s) => s === 'puppeteer',
@@ -175,13 +226,34 @@ describe('the vocabulary itself', () => {
     // quietly dropping an entry while every other test stays green. Changing
     // this list should require changing this test, on purpose.
     expect(FORBIDDEN_ROUTE_PREFIXES.map((f) => f.prefix).sort()).toEqual([
+      // Surfaces that EVALUATE tenant content on our compute…
+      '/_api/acp',
+      '/_api/claude',
+      '/_api/cloud',
+      '/_api/debug-bundle',
+      '/_api/design',
       '/_api/export',
       '/_api/generate',
+      '/_api/github',
+      '/_api/hub',
       '/_api/photo-edit',
+      // Spawns a headless browser against the studio — same evaluation as
+      // `/_api/export`, and there is no browser in a cell image.
+      '/_api/shell-shot',
+      '/_ws/acp',
+    ]);
+    // …and the two that a cell SERVES, under an asserted contract (DDR-209 A′1).
+    // They moved lists; they did not stop being checked. See the sandbox tests
+    // above for what "under contract" is worth.
+    expect(SANDBOXED_ROUTE_PREFIXES.map((f) => f.prefix).sort()).toEqual([
       '/_canvas-runtime',
       '/_canvas-shell',
-      '/_ws/acp',
     ]);
+    // Nothing may be on both lists — that would make the weaker one decorative.
+    const forbidden = new Set(FORBIDDEN_ROUTE_PREFIXES.map((f) => f.prefix));
+    for (const { prefix } of SANDBOXED_ROUTE_PREFIXES) {
+      expect(forbidden.has(prefix)).toBe(false);
+    }
     expect([...FORBIDDEN_MODULES].sort()).toEqual([
       'playwright',
       'playwright-core',
@@ -245,14 +317,21 @@ describe('pruneForWorkspace — how a cell can boot at all', () => {
   });
 
   test('isForbiddenRoute is the single predicate both the table and fetch use', () => {
-    // The `fetch` fall-through owns paths that are not in the route table
-    // (/_ws/acp, /_canvas-shell.html, /_canvas-runtime/*), so it gates on this
-    // same function. One predicate, so the two gates cannot disagree.
-    expect(isForbiddenRoute('/_canvas-shell.html')).toBe(true);
-    expect(isForbiddenRoute('/_canvas-runtime/react.js')).toBe(true);
+    // The `fetch` fall-through owns `/_ws/acp`, which is not in the route table,
+    // so it gates on this same function. One predicate, so the two gates cannot
+    // disagree.
     expect(isForbiddenRoute('/_ws/acp')).toBe(true);
+    expect(isForbiddenRoute('/_api/github/repos')).toBe(true);
     expect(isForbiddenRoute('/_ws')).toBe(false);
     expect(isForbiddenRoute('/_health')).toBe(false);
     expect(isForbiddenRoute('/_api/asset')).toBe(false);
+    // DDR-209 A′1 — the canvas surfaces are NOT forbidden, which is exactly why
+    // the fall-through stopped 404-ing them. `isSandboxedRoute` is where they
+    // are now accounted for.
+    expect(isForbiddenRoute('/_canvas-shell.html')).toBe(false);
+    expect(isForbiddenRoute('/_canvas-runtime/react.js')).toBe(false);
+    expect(isSandboxedRoute('/_canvas-shell.html')).toBe(true);
+    expect(isSandboxedRoute('/_canvas-runtime/react.js')).toBe(true);
+    expect(isSandboxedRoute('/_health')).toBe(false);
   });
 });