@1agh/maude 0.60.7 → 1.0.3

package/cli/commands/hub-workspace.mjs

@@ -24,6 +24,7 @@ import {
   renderCaddyfile,
   renderCompose,
   renderEnv,
+  safeSeedUrl,
   validateWorkspaceConfig,
   verificationPlan,
   workspaceBaseUrl,
@@ -37,6 +38,11 @@ export function usage() {
   before saying so.
 
   --domain HOST            public hostname (design.acme.com)
+  --canvas-domain HOST     SECOND hostname for the canvas origin
+                           (canvas.acme.com). The studio renders canvases on
+                           their own origin; without a public name for it the
+                           iframe points at a container-internal port and every
+                           canvas is a blank frame. Point DNS here too.
   --acme-email EMAIL       Let's Encrypt contact
   --admin-email EMAIL      the first person who can sign in
   --admin-password PASS    their initial password (>= 12 chars; generated if omitted)
@@ -53,6 +59,11 @@ export function usage() {
                            verification step — on a laptop, with no domain and
                            no paid account. Never serve a real workspace this
                            way: sign-in passwords would travel in the clear.
+  --render                 add the maude-render sidecar — the one container
+                           that carries a browser. Enables PNG/PDF/PPTX/video
+                           export from the hosted studio (DDR-230). Without
+                           it those formats say so and point at the desktop
+                           app; ZIP export works either way.
   --seed-repo URL          clone an existing project; omit to start fresh
   --image-tag TAG          default "latest" — pin it before you rely on this
   --config FILE            read all of the above from a JSON file
@@ -72,7 +83,7 @@ export function usage() {
 
 export async function run({ args, pkgRoot }) {
   const { flags } = parseArgs(args, {
-    booleans: ['help', 'dry-run', 'json', 'dev-minio', 'local'],
+    booleans: ['help', 'dry-run', 'json', 'dev-minio', 'local', 'render'],
   });
   if (flags.help) {
     process.stdout.write(usage());
@@ -90,7 +101,9 @@ export async function run({ args, pkgRoot }) {
       : {}),
     devMinio: flags['dev-minio'] === true || raw.devMinio === true,
     local: flags.local === true || raw.local === true,
+    render: flags.render === true || raw.render === true,
     seedRepo: flags['seed-repo'] ?? raw.seedRepo,
+    canvasDomain: flags['canvas-domain'] ?? raw.canvasDomain,
     imageTag: flags['image-tag'] ?? raw.imageTag,
     ...(flags['s3-endpoint'] || raw.s3
       ? {
@@ -103,9 +116,28 @@ export async function run({ args, pkgRoot }) {
           },
         }
       : {}),
+    // BYO identity travels via --config only: a client secret does not belong
+    // on a command line (argv is visible in `ps` and shell history — see
+    // _credentials.md). The config block is passed straight through to
+    // validateWorkspaceConfig, which renders and forwards the HUB_OIDC_* vars.
+    ...(raw.oidc ? { oidc: raw.oidc } : {}),
   };
 
-  const { ok, errors, config } = validateWorkspaceConfig(merged);
+  // Read the existing .env BEFORE validating, because whether this deployment
+  // already exists decides the backup namespace (Phase 0 F3).
+  const envPath = resolve(outDir, '.env');
+  const envExists = existsSync(envPath);
+  const existing = readExistingEnv(envPath);
+
+  // NEVER force a namespace onto a deployment that has been running without
+  // one. A prefixed target lists a DISJOINT keyspace, so adding one makes every
+  // existing generation invisible to `listBackups` — orphaned, unprunable, and
+  // the next lost volume would see zero generations and seed over the loss. The
+  // write-side identity refusal already protects the bare root, so the prefix
+  // is a remedy here rather than the safety mechanism.
+  const backupPrefix = envExists ? existing.MAUDE_BACKUP_PREFIX || null : undefined;
+
+  const { ok, errors, config } = validateWorkspaceConfig({ ...merged, backupPrefix });
   if (!ok) {
     if (flags.json) {
       process.stdout.write(`${JSON.stringify({ ok: false, errors }, null, 2)}\n`);
@@ -117,15 +149,42 @@ export async function run({ args, pkgRoot }) {
     process.exit(2);
   }
 
+  // REFUSE a new admin password on a re-run, rather than writing one that goes
+  // nowhere.
+  //
+  // `seedFirstUser()` (first-user.mjs) creates the account on FIRST BOOT only.
+  // On a re-run the account already exists and keeps its original password, so
+  // letting `--admin-password` win here produces a `.env` that states one
+  // password and a database that holds another. The command's own verification
+  // then reports `HTTP 401 — the first user cannot sign in`, and the only
+  // repair found on the live AWS run was `docker compose down -v` — on a
+  // production box that is losing the project, not fixing the password.
+  //
+  // Checked BEFORE anything is written or started, so the refusal costs the
+  // operator a message rather than a half-applied run.
+  if (config.adminPassword && existing.MAUDE_ADMIN_PASSWORD) {
+    const message =
+      'the first user already exists — `--admin-password` applies to a FIRST boot only. ' +
+      'Change their password in the admin UI; re-run without the flag to leave it alone.';
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify({ ok: false, errors: [message] }, null, 2)}\n`);
+    } else {
+      process.stderr.write(`maude hub workspace-up: ${message}\n`);
+    }
+    process.exit(2);
+  }
+
   // Reuse existing secrets — re-minting on a re-run would lock out every peer
   // that already holds a token, and re-running is exactly what someone does
-  // after a failed attempt.
-  const existing = readExistingEnv(resolve(outDir, '.env'));
+  // after a failed attempt. (`existing` was read above, before validation.)
   const hubSecret = existing.HUB_SECRET || randomBytes(32).toString('hex');
   const adminPassword = config.adminPassword || existing.MAUDE_ADMIN_PASSWORD || generatePassword();
   const reusedSecret = Boolean(existing.HUB_SECRET);
+  // Its OWN secret (DDR-230) — rotating the render bearer must never lock out
+  // peers holding hub tokens, and vice versa. Reused on re-runs like the rest.
+  const renderSecret = existing.MAUDE_RENDER_SECRET || randomBytes(32).toString('hex');
 
-  const entries = envEntries(config, { hubSecret, adminPassword });
+  const entries = envEntries(config, { hubSecret, adminPassword, renderSecret });
   const files = [
     { name: '.env', body: renderEnv(entries), mode: 0o600 },
     { name: 'docker-compose.yml', body: renderCompose(config), mode: 0o644 },
@@ -145,10 +204,15 @@ export async function run({ args, pkgRoot }) {
       reusedSecret,
     };
     if (flags.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    else printDryRun({ config, outDir, files, plan, duties, reusedSecret });
+    else {
+      printDryRun({ config, outDir, files, plan, duties, reusedSecret });
+      warnNoCanvasDomain(config);
+    }
     return;
   }
 
+  warnNoCanvasDomain(config);
+
   mkdirSync(outDir, { recursive: true });
   for (const f of files) {
     const path = resolve(outDir, f.name);
@@ -255,7 +319,10 @@ function readExistingEnv(path) {
   try {
     for (const line of readFileSync(path, 'utf8').split('\n')) {
       const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
-      if (m) out[m[1]] = m[2];
+      // Values are single-quoted by renderEnv (F8), so unquote on the way back
+      // in — otherwise a re-run reads `'secret'` (with quotes) and re-quotes it,
+      // and every peer holding the old HUB_SECRET is locked out.
+      if (m) out[m[1]] = unquoteEnvValue(m[2]);
     }
   } catch {
     /* unreadable → treat as absent */
@@ -263,6 +330,14 @@ function readExistingEnv(path) {
   return out;
 }
 
+/** Reverse of `renderEnvValue`: strip the single quotes and unescape. */
+function unquoteEnvValue(v) {
+  if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) {
+    return v.slice(1, -1).replace(/'\\''/g, "'");
+  }
+  return v;
+}
+
 /** Readable, high-entropy, and safe to paste — no ambiguous glyphs. */
 function generatePassword() {
   const alphabet = 'abcdefghjkmnpqrstuvwxyzABCDEFGHJKMNPQRSTUVWXYZ23456789';
@@ -343,7 +418,9 @@ async function runVerification(step, { config, hubSecret, adminPassword, outDir,
     case 's3-no-expiry':
       return verifyNoLifecycle(config, pkgRoot);
     case 'restore-drill':
-      return verifyRestoreDrill(config);
+      return verifyRestoreDrill(config, { outDir, pkgRoot });
+    case 'render-health':
+      return verifyRenderHealth(outDir);
     default:
       return {
         ok: false,
@@ -377,6 +454,44 @@ async function verifySignin(base, email, password) {
   }
 }
 
+/**
+ * The render sidecar answers AND is configured (DDR-230).
+ *
+ * Probed from INSIDE the hub container, because that is the only place the
+ * service is reachable from — it deliberately has no public port. `configured`
+ * comes from the service's own /_health: a booted sidecar with a missing
+ * secret or an empty origin allowlist refuses every job, and "up but refusing
+ * everything" must not read as a pass.
+ */
+async function verifyRenderHealth(outDir) {
+  const probe = await sh(
+    'docker',
+    [
+      'compose',
+      'exec',
+      '-T',
+      'hub',
+      'sh',
+      '-c',
+      'wget -q -O - http://render:8790/_health || curl -sf http://render:8790/_health',
+    ],
+    { cwd: outDir }
+  );
+  if (probe.code !== 0) return { ok: false, note: 'the render service did not answer /_health' };
+  try {
+    const body = JSON.parse(probe.stdout);
+    if (body?.ok && body?.configured) return { ok: true };
+    return {
+      ok: false,
+      note: body?.ok
+        ? 'render service is up but not configured (missing secret or canvas-origin allowlist)'
+        : 'render service /_health did not report ok',
+    };
+  } catch {
+    return { ok: false, note: 'render service /_health returned something that is not JSON' };
+  }
+}
+
 /**
  * The server-side checkout has real commits (Cloud Phase 16).
  *
@@ -523,10 +638,21 @@ async function verifyNoLifecycle(config, pkgRoot) {
     if (res.status === 404) return { ok: true, note: 'no lifecycle configuration' };
     if (!res.ok) {
       // Cannot read the config ⇒ cannot claim it is safe. Skipped, never passed.
+      //
+      // 403 gets its own sentence because it is almost always OUR fault, not a
+      // misconfiguration: the least-privilege policy we ship omitted
+      // `s3:GetLifecycleConfiguration` until 2026-08-20, so following the docs
+      // to the letter left this check permanently skipped — and the thing it
+      // guards (an expiry rule silently deleting media that canvases still
+      // reference) has no recovery path once it fires.
+      const why =
+        res.status === 403
+          ? 'the credential may not read lifecycle config — add s3:GetLifecycleConfiguration on the bucket ARN'
+          : `HTTP ${res.status}`;
       return {
         ok: false,
         skipped: true,
-        note: `could not read lifecycle config (HTTP ${res.status})`,
+        note: `could not read lifecycle config (${why})`,
       };
     }
     const xml = await res.text();
@@ -548,19 +674,92 @@ async function verifyNoLifecycle(config, pkgRoot) {
   }
 }
 
-/** A backup nobody has restored is a hypothesis. Runs the real drill. */
-async function verifyRestoreDrill(config) {
+/**
+ * Turn a failed drill subprocess into a verdict — and separate the two very
+ * different things a non-zero exit can mean.
+ *
+ * Exported because this distinction, not the spawning, is the thing worth
+ * pinning: on the first live AWS run all three of "no generation yet",
+ * "nowhere to run" and "the restore is broken" printed as a single red
+ * `failed`, and the operator spent the evening on the third when the truth was
+ * the second.
+ */
+export function classifyDrillFailure(text) {
+  if (/no complete backup generation/i.test(text)) {
+    return {
+      ok: false,
+      skipped: true,
+      note: 'no generation exists yet (the first one lands within 6h) — run `maude hub restore-drill` then',
+    };
+  }
+  // "NOWHERE TO RUN" IS NOT "THE BACKUP IS BROKEN". The standard deployment
+  // this command generates is container-only: the host clone has no
+  // `node_modules` (so `backup.mjs` dies on `Cannot find module
+  // 'better-sqlite3'`) and the image carries the bundled server, not
+  // `cli/bin/maude.mjs` — so the drill has nowhere to execute, through no
+  // fault of the backups. Reported as `failed`, that reads as data loss.
+  if (/cannot find module|backup engine.*not found|ERR_MODULE_NOT_FOUND/i.test(text)) {
+    return {
+      ok: false,
+      skipped: true,
+      note:
+        'the drill could not run here — this host has no installed backup engine, so nothing ' +
+        'about the backups was proven either way. Run `maude hub restore-drill` from a full ' +
+        'checkout against the same target.',
+    };
+  }
+  return { ok: false, note: `provisioning drill failed: ${text.trim().slice(0, 160)}` };
+}
+
+/**
+ * A backup nobody has restored is a hypothesis. Runs the real drill.
+ *
+ * This used to report `skipped` unconditionally, on the grounds that "the
+ * drill needs the hub's own data dir, which lives inside the container". That
+ * was never true of the drill: `runRestoreDrill` restores into a SCRATCH
+ * directory from a target resolved off flags and env — it never touches the
+ * hub's data dir. And the credentials it needs are the ones we just rendered
+ * into `.env` on this machine.
+ *
+ * What the old note WAS right about is the claim it makes. Running it at
+ * provisioning time proves the code path works against this bucket with these
+ * credentials; it does not prove the deployment is restorable next month. So
+ * it is labelled a PROVISIONING drill and the recurring duty stays uncrossed
+ * in `operatorDuties()`.
+ */
+async function verifyRestoreDrill(config, { outDir, pkgRoot }) {
   if (!config.s3) return { ok: false, skipped: true, note: 'no backup target configured' };
-  // The drill needs the hub's own data dir, which lives inside the container.
-  // Deliberately left to the operator's `maude hub restore-drill` rather than
-  // reaching into a volume from out here: a half-run drill that reports
-  // success is worse than an honest skip, and this is the one check whose
-  // whole point is that somebody actually did it.
-  return {
-    ok: false,
-    skipped: true,
-    note: 'run `maude hub restore-drill` against this deployment — it needs the hub data dir',
-  };
+
+  // PASS THE RENDERED ENV EXPLICITLY.
+  //
+  // The subprocess resolves its target through `engine.targetFromEnv()` — the
+  // SHELL's environment. `MAUDE_S3_*` was rendered into `.env` for the
+  // CONTAINER and was never exported here, so the drill reported "no backup
+  // target configured" on a deployment whose storage was configured and
+  // working. The note above this function said the credentials "are the ones
+  // we just rendered into `.env` on this machine": rendered, yes — loaded, no.
+  const rendered = readExistingEnv(resolve(outDir, '.env'));
+  const env = { ...process.env };
+  for (const [key, value] of Object.entries(rendered)) {
+    if (
+      key.startsWith('MAUDE_S3_') ||
+      key === 'MAUDE_BACKUP_TARGET' ||
+      key === 'MAUDE_BACKUP_PREFIX'
+    ) {
+      env[key] = value;
+    }
+  }
+
+  const drill = await sh(
+    process.execPath,
+    [resolve(pkgRoot, 'cli/bin/maude.mjs'), 'hub', 'restore-drill', '--json'],
+    { env }
+  );
+  if (drill.code !== 0) {
+    const text = `${drill.stdout}${drill.stderr}`;
+    return classifyDrillFailure(text);
+  }
+  return { ok: true, note: 'provisioning drill passed — schedule it, this proves today only' };
 }
 
 /** Retry a flaky-at-startup operation. Rethrows the LAST error, so the
@@ -596,13 +795,35 @@ async function tryFetch(url, init) {
   }
 }
 
+/**
+ * The M7 warning — LOUD, in both the dry run and the real one.
+ *
+ * Without a canvas domain the stack comes up, every verification step passes,
+ * and every canvas renders as a blank frame: the iframe's origin defaults to
+ * `http://localhost:<container port>`, an address only the server itself can
+ * reach. The spike hit exactly this, concluded "the workspace can't render by
+ * design", and planned around a limitation that was one missing hostname.
+ */
+function warnNoCanvasDomain(config) {
+  if (config.canvasDomain || config.local) return;
+  process.stderr.write(
+    '\n  ⚠ no --canvas-domain: canvases will NOT render in remote browsers.\n' +
+      '    The canvas iframe needs its own public hostname (e.g. canvas.' +
+      config.domain.replace(/^[^.]+\./, '') +
+      ').\n' +
+      '    Point a DNS record at this machine and re-run with --canvas-domain <host>.\n' +
+      '    The studio chrome (file tree, comments) works either way.\n\n'
+  );
+}
+
 function printDryRun({ config, outDir, files, plan, duties, reusedSecret }) {
   process.stdout.write(
     `maude hub workspace-up — DRY RUN, nothing was written\n\n` +
       `  workspace   ${workspaceBaseUrl(config)}${config.local ? '  (LOCAL — plain HTTP)' : ''}\n` +
       `  first user  ${config.adminEmail}\n` +
       `  storage     ${config.s3 ? `${config.s3.bucket} @ ${config.s3.endpoint}${config.s3.dev ? ' (dev MinIO)' : ''}` : 'none — media stays in git'}\n` +
-      `  project     ${config.seedRepo ?? 'starts fresh'}\n` +
+      `  project     ${safeSeedUrl(config.seedRepo) ?? 'starts fresh'}\n` +
+      `  canvas      ${config.canvasDomain ? `${config.local ? 'http' : 'https'}://${config.canvasDomain}` : config.local ? 'same-machine (local mode — the browser can reach the container port)' : 'NOT SET — canvases will not render in remote browsers'}\n` +
       `  image       ghcr.io/1agh/maude-hub:${config.imageTag}\n` +
       `  out         ${outDir}\n` +
       (reusedSecret ? '  secrets     reusing HUB_SECRET from the existing .env\n' : '') +

package/cli/commands/hub-workspace.test.mjs

@@ -0,0 +1,171 @@
+// `maude hub workspace-up` end-to-end via spawnSync — the properties that only
+// hold on the REAL command surface, not on the planning layer under it.
+//
+// Both cases come from the first live AWS run of `workspace-up` (2026-08-20).
+
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const BIN = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'maude.mjs');
+
+const { classifyDrillFailure } = await import('./hub-workspace.mjs');
+
+function runCli(args, { cwd } = {}) {
+  return spawnSync(process.execPath, [BIN, ...args], { cwd, encoding: 'utf8' });
+}
+
+function withDir(fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'maude-workspace-'));
+  try {
+    return fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const BASE = [
+  'hub',
+  'workspace-up',
+  '--domain',
+  'design.acme.com',
+  '--acme-email',
+  'ops@acme.com',
+  '--admin-email',
+  'ops@acme.com',
+];
+
+// M3 — the recommended seed URL is
+// `https://x-access-token:<PAT>@github.com/org/repo.git` (`seed-repo.mjs`
+// accepts no other shape), and this command printed it unredacted, `--dry-run`
+// included. On the live run the PAT landed in SSM command history, CloudTrail
+// and a session transcript, and had to be revoked.
+test('--dry-run never prints the seed URL credential', () => {
+  withDir((dir) => {
+    const r = runCli(
+      [...BASE, '--dry-run', '--seed-repo', 'https://x-access-token:SECRET123@github.com/o/r.git'],
+      { cwd: dir }
+    );
+    assert.equal(r.status, 0, r.stderr);
+    const out = `${r.stdout}${r.stderr}`;
+    assert.ok(!out.includes('SECRET123'), 'the token must not reach stdout or stderr');
+    assert.match(out, /https:\/\/\*\*\*@github\.com\/o\/r\.git/);
+  });
+});
+
+// M2 — `--admin-password` beat the existing `.env`, so the new value was
+// written to disk while `seedFirstUser()` (first boot only) kept the old one.
+// The verification step then reported `HTTP 401 — the first user cannot sign
+// in`, and the only repair anyone found was `docker compose down -v`: on a
+// live box, losing the project rather than fixing the password.
+test('--admin-password on a re-run is refused, not silently written', () => {
+  withDir((dir) => {
+    const first = runCli([...BASE, '--dry-run', '--admin-password', 'first-password-ok'], {
+      cwd: dir,
+    });
+    assert.equal(first.status, 0, first.stderr);
+
+    // Stand in for a hub that has already booted once.
+    writeFileSync(
+      join(dir, '.env'),
+      "MAUDE_ADMIN_EMAIL='ops@acme.com'\nMAUDE_ADMIN_PASSWORD='first-password-ok'\nHUB_SECRET='abc'\n",
+      { mode: 0o600 }
+    );
+
+    const rerun = runCli([...BASE, '--admin-password', 'second-password-ok'], { cwd: dir });
+    assert.notEqual(rerun.status, 0, 'a re-run with a new password must not report success');
+    assert.match(`${rerun.stdout}${rerun.stderr}`, /already exists/i);
+    // The file on disk must still describe the password the database holds.
+    assert.match(readFileSync(join(dir, '.env'), 'utf8'), /first-password-ok/);
+    assert.ok(!readFileSync(join(dir, '.env'), 'utf8').includes('second-password-ok'));
+  });
+});
+
+test('a re-run WITHOUT --admin-password still proceeds past the password gate', () => {
+  withDir((dir) => {
+    writeFileSync(
+      join(dir, '.env'),
+      "MAUDE_ADMIN_EMAIL='ops@acme.com'\nMAUDE_ADMIN_PASSWORD='first-password-ok'\nHUB_SECRET='abc'\n",
+      { mode: 0o600 }
+    );
+    const r = runCli([...BASE, '--dry-run'], { cwd: dir });
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(existsSync(join(dir, '.env')));
+  });
+});
+
+// M1 — on the live AWS run `restore-drill` reported a flat red `failed` for
+// something that was not a backup problem at all: the host clone had no
+// `node_modules`, so `backup.mjs` died on `Cannot find module
+// 'better-sqlite3'`, and the image ships the bundled server rather than
+// `cli/bin/maude.mjs`, so there was no third place to try. An operator reading
+// "the backup is broken" starts recovering from a problem they do not have.
+test('a drill that could not RUN is skipped, not failed', () => {
+  const verdict = classifyDrillFailure(
+    "maude hub backup: Cannot find module 'better-sqlite3'\nRequire stack: /x/apps/hub/src/backup.mjs"
+  );
+  assert.equal(verdict.ok, false);
+  assert.equal(verdict.skipped, true, 'unrunnable must not be reported as a failure');
+  assert.match(verdict.note, /could not run/i);
+});
+
+test('a missing backup engine is skipped too', () => {
+  const verdict = classifyDrillFailure(
+    'maude hub: the backup engine (apps/hub/src/backup.mjs) was not found.'
+  );
+  assert.equal(verdict.skipped, true);
+});
+
+test('no generation yet is skipped and says when to retry', () => {
+  const verdict = classifyDrillFailure('no complete backup generation exists');
+  assert.equal(verdict.skipped, true);
+  assert.match(verdict.note, /6h/);
+});
+
+// The drill doing its job must stay loud — this is the case the skips above
+// must never swallow.
+test('a REAL restore failure is still a failure', () => {
+  const verdict = classifyDrillFailure('restored database has documents 0 — refusing to pass');
+  assert.equal(verdict.ok, false);
+  assert.ok(!verdict.skipped, 'an empty restore is a genuine failure, not a skip');
+  assert.match(verdict.note, /provisioning drill failed/);
+});
+
+// M7 — without a canvas domain the stack comes up green and every canvas is a
+// blank frame. Verification never catches it (all eight steps pass), so the
+// COMMAND has to say it — loudly, in both the dry run and the real one.
+test('--dry-run without --canvas-domain warns that canvases will not render remotely', () => {
+  withDir((dir) => {
+    const r = runCli([...BASE, '--dry-run'], { cwd: dir });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(`${r.stdout}${r.stderr}`, /canvases will NOT render in remote browsers/i);
+    assert.match(r.stdout, /canvas\s+NOT SET/);
+  });
+});
+
+test('--canvas-domain silences the warning and renders the full chain', () => {
+  withDir((dir) => {
+    const r = runCli([...BASE, '--dry-run', '--canvas-domain', 'canvas.acme.com'], { cwd: dir });
+    assert.equal(r.status, 0, r.stderr);
+    const out = `${r.stdout}${r.stderr}`;
+    assert.ok(!/NOT render in remote browsers/i.test(out), 'warning must be gone');
+    assert.match(r.stdout, /canvas\s+https:\/\/canvas\.acme\.com/);
+    // The duty list tells the operator the second DNS record is on them.
+    assert.match(r.stdout, /DNS for the canvas domain/);
+  });
+});
+
+test('--local does not warn — localhost IS reachable from the browser that matters there', () => {
+  withDir((dir) => {
+    const r = runCli(
+      ['hub', 'workspace-up', '--local', '--admin-email', 'ops@acme.com', '--dry-run'],
+      { cwd: dir }
+    );
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(!/NOT render in remote browsers/i.test(`${r.stdout}${r.stderr}`));
+  });
+});

package/cli/commands/hub.mjs

@@ -26,6 +26,7 @@ const SUBCOMMANDS = new Set([
   'backup',
   'restore-drill',
   'asset-check',
+  'backup-owners',
   'workspace-up',
   'help',
 ]);
@@ -50,6 +51,7 @@ export async function run({ args, pkgRoot }) {
   if (sub === 'backup') return runBackupNow({ args, pkgRoot });
   if (sub === 'restore-drill') return runRestoreDrill({ args, pkgRoot });
   if (sub === 'asset-check') return runAssetCheck({ args, pkgRoot });
+  if (sub === 'backup-owners') return runBackupOwners({ args, pkgRoot });
   if (sub === 'workspace-up') {
     const mod = await import('./hub-workspace.mjs');
     return mod.run({ args, pkgRoot });
@@ -57,7 +59,7 @@ export async function run({ args, pkgRoot }) {
 }
 
 function usage() {
-  return `maude hub <serve|token|status|deploy|backup|restore-drill|asset-check|workspace-up> [options]
+  return `maude hub <serve|token|status|deploy|backup|restore-drill|asset-check|backup-owners|workspace-up> [options]
 
   serve [--port N] [--data PATH] [--secret HEX] [--insecure-http] [--dev]
         Start the self-hostable Yjs sync hub in the current process tree.
@@ -370,6 +372,13 @@ function runDeploy({ args, pkgRoot }) {
   }
 
   const outDir = flags.out ? resolve(String(flags.out)) : process.cwd();
+  // CREATE IT. The docs' own command is `--out ./deploy` on a fresh box, where
+  // that directory does not exist yet — and the emitter used to write straight
+  // into it, so the very first thing a self-hoster runs died on
+  // `ENOENT ... docker-compose.yml`. Found by running the operator path end to
+  // end (B2/D7) rather than reading it. `process.cwd()` always exists, so this
+  // only ever fires for an explicit --out.
+  mkdirSync(outDir, { recursive: true });
 
   if (target === 'fly') return deployFly({ hubRoot, outDir, flags });
   return deployDocker({ hubRoot, outDir, flags });
@@ -656,6 +665,67 @@ async function runRestoreDrill({ args, pkgRoot }) {
  * and no amount of syncing fixes it. Content addressing means we can check it
  * cheaply — the reference IS the identity.
  */
+/**
+ * `maude hub backup-owners` — who owns the generations in this keyspace.
+ *
+ * ADVISORY, and deliberately so. Workspace identity (Phase 0 F1) is
+ * forward-only: from the upgrade on, every new generation names its owner and
+ * the write refusal stops two hubs destroying each other. It says nothing
+ * about a bucket whose generations are ALREADY interleaved — those predate the
+ * field, are indistinguishable from each other, and are still being pruned
+ * across. This reports that so a person can act on it.
+ *
+ * It never gates anything. Spacing and counts are evidence, not conditions:
+ * a merged series that happens to look evenly spaced would pass, and a
+ * single-owner series whose hub was down a day would fail.
+ */
+async function runBackupOwners({ args, pkgRoot }) {
+  const { flags } = parseArgs(args);
+  const engine = await loadBackupEngine(pkgRoot);
+  const target = resolveTarget(engine, flags);
+  const identity = await loadWorkspaceIdentity(pkgRoot);
+  const dataDir = flags['data-dir'] ?? process.env.DATA_DIR ?? null;
+  const workspace = dataDir && identity ? identity.readWorkspaceId(dataDir) : null;
+
+  let report;
+  try {
+    report = await engine.inspectKeyspace(target, { workspace });
+  } catch (err) {
+    if (flags.json) process.stdout.write(`${JSON.stringify({ ok: false, error: err.message })}\n`);
+    else process.stderr.write(`maude hub backup-owners: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify({ ok: true, ...report }, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write(
+    `[backup-owners] ${report.describe}\n` +
+      `  generations   ${report.generations}\n` +
+      `  owners        ${report.owners.length ? report.owners.join(', ') : '(none recorded)'}\n` +
+      `  unidentified  ${report.unidentified}\n` +
+      `  verdict       ${report.verdict}\n`
+  );
+  if (report.shared) {
+    process.stdout.write(
+      '\nTwo hubs sharing one keyspace prune each other\u2019s history. Give each its own\n' +
+        'MAUDE_BACKUP_PREFIX, or its own bucket. Nothing here has changed anything.\n'
+    );
+  }
+}
+
+/** The identity helpers live beside the backup engine; same resolution rule. */
+async function loadWorkspaceIdentity(pkgRoot) {
+  for (const candidate of [
+    resolve(pkgRoot, 'apps/hub/src/workspace-identity.mjs'),
+    resolve(pkgRoot, '../apps/hub/src/workspace-identity.mjs'),
+  ]) {
+    if (existsSync(candidate)) return import(`file://${candidate}`);
+  }
+  return null;
+}
+
 async function runAssetCheck({ args, pkgRoot }) {
   const { flags } = parseArgs(args);
   const root = resolve(flags.root ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd());