@augurworks/augur 0.15.1

package/scripts/offline.mjs

@@ -0,0 +1,247 @@
+// offline.mjs — local "offline mode" for Augur.
+//
+//   npm run offline   →  start   ·   Ctrl-C  →  stop
+//
+// What it does:
+//   1. Builds dist once (node build.js).
+//   2. Starts `wrangler dev` against a generated config (.wrangler/offline.toml) with
+//      src/entry.js as the entry — the SAME front door a deployed instance uses, running
+//      the real worker locally, so the per-user login gate is ON (same as live; sign in
+//      with an admin account — seed creds in src/identity.json) and every overlay API
+//      (comments / pins / status / names / piti) works. No deploy — a faithful local
+//      mirror of the live site.
+//      It used to be `wrangler pages dev dist`, and the difference is not cosmetic: a
+//      Worker serves a matching static asset BEFORE the worker runs unless the config says
+//      otherwise, and dist/__config/instance.json holds the roster with seed passwords.
+//      Running the deployed front door locally is how that difference gets found by a
+//      person. See scripts/lib/offline-wrangler.mjs.
+//      ⚠️ KV is LIVE/prod when .env.deploy holds Cloudflare creds: the worker reads/writes
+//      the REAL production KV via a REST shim (LIVE_KV below), so overlay edits made offline
+//      are live for everyone — intentional (offline editing, shared live overlay). Rename
+//      .env.deploy for a safe local-only KV sandbox (it then logs `KV: local`).
+//      Canvas realtime follows the same split: live KV + RT_SHARED_SECRET in .env.deploy
+//      → boards join the instance's real rooms; sandbox → realtime disabled outright
+//      (GV_RT_DISABLE), so a sandbox board can't broadcast into shared prod rooms.
+//      wrangler is supervised: a workerd crash respawns it (crash-loop cutoff in
+//      lib/offline-respawn.mjs) instead of killing the whole offline server.
+//   3. Watches the build inputs (the design system, the workspace, build.js, the
+//      worker) and rebuilds on any change. Each build writes a fresh BUILD_ID into
+//      dist/__config/instance.json — it is runtime DATA, not something stamped into the
+//      worker's code — and the page's live-reload poller (which polls /__version every
+//      ~1s on localhost) refreshes open tabs within the worker's ~1.5s config tick.
+//
+// Zero new dependencies: Node's recursive fs.watch + npx wrangler (same as deploy).
+
+import { spawn } from "node:child_process";
+import { watch, existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parseEnvFile, derivePosture, postureVars, postureBanner } from "./lib/offline-posture.mjs";
+import { offlineWranglerConfig } from "./lib/offline-wrangler.mjs";
+import { fileURLToPath } from "node:url";
+import { findShellDir } from "./lib/instance.mjs";
+import { respawnDelay } from "./lib/offline-respawn.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const PORT = process.env.OFFLINE_PORT || "8788";
+
+const log = (msg) => console.log(`\x1b[35m[offline]\x1b[0m ${msg}`);
+
+// Optional "offline-live" mode: if augur/.env.deploy holds Cloudflare creds, the local
+// worker talks to the REAL prod KV via the REST shim in _worker.js (kvFor) — so
+// comments/pins/status/renames are the shared live layer while prototypes stay local.
+// No creds → today's local KV, unchanged. Passed to the worker as
+// --binding GV_KV_* (read by kvFor). Prototypes/assets are always local regardless.
+// The live-vs-sandbox decision, and the bindings it implies, now live in
+// scripts/lib/offline-posture.mjs — a pure function with a table of cases under it in
+// test/offline-posture.test.mjs. It moved because it had NO coverage and it decides the
+// one thing about local development that can hurt somebody else: whether this process
+// reads and writes the LIVE KV namespace or a local sandbox. Getting it backwards is
+// silent in both directions, so a refactor of exactly this code is how a live-vs-sandbox
+// inversion ships green.
+//
+// `--sandbox` forces the safe posture whatever .env.deploy holds. There is deliberately
+// no inverse flag: nothing may turn a sandbox into a live run except the credentials
+// themselves being present.
+const POSTURE = derivePosture(
+  parseEnvFile((() => { try { return readFileSync(path.join(ROOT, ".env.deploy"), "utf8"); } catch (e) { return ""; } })()),
+  { forceSandbox: process.argv.includes("--sandbox") },
+);
+const POSTURE_VARS = postureVars(POSTURE);
+
+// Build from the canonical EDIT-HERE clones, not the pinned nested submodules.
+// One repo per space: a maintainer workspace puts each space repo — a self-contained
+// bundle with that space's design system AND prototypes at its root — as a sibling of
+// augur/ (../<space>, …), and that's where every agent edits. Building from them means
+// a local preview reflects live edits with no pin bump, no matter which agent made the
+// change. A sibling counts as a space iff it carries a space.json at its root — the same
+// filter build.js's discoverSpaces() applies — so augur itself and scratch dirs are
+// ignored. Fall back to the pinned submodules under augur/spaces/ if no sibling space
+// exists (e.g. augur cloned on its own, outside a multi-space workspace).
+const PARENT = path.join(ROOT, "..");
+let siblingSpaces = [];
+try {
+  siblingSpaces = readdirSync(PARENT, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && !e.name.startsWith(".")
+      && existsSync(path.join(PARENT, e.name, "space.json")))
+    .map((e) => path.join(PARENT, e.name));
+} catch {}
+const usingSiblings = siblingSpaces.length > 0;
+const SPACES_ROOT = usingSiblings ? PARENT : path.join(ROOT, "spaces");
+// Passed to build.js so it composes every space from here (see GV_SPACES_ROOT there).
+// GV_LOCAL says this build is only ever served from this machine, which is what lets a
+// space's tracks/ music play here while staying out of everything that ships.
+const BUILD_ENV = { ...process.env, GV_SPACES_ROOT: SPACES_ROOT, GV_LOCAL: "1" };
+// Identity + deploy config: explicit env wins; else auto-detect a sibling DEPLOY SHELL
+// by shape — any sibling dir with an identity.json at its root that is not a space
+// (shell repo names vary per instance). The shell also contributes deploy.config.json
+// when it has one. A raw engine clone with no shell falls back to the in-repo
+// src/identity.json (an empty [] placeholder → gate stays open).
+const SHELL_DIR = findShellDir(ROOT);
+const IDENTITY_PATH = process.env.GV_IDENTITY_PATH
+  || [SHELL_DIR && path.join(SHELL_DIR, "identity.json"), path.join(ROOT, "src", "identity.json")]
+    .filter(Boolean).find((p) => existsSync(p));
+if (IDENTITY_PATH) BUILD_ENV.GV_IDENTITY_PATH = IDENTITY_PATH;
+const DEPLOY_CONFIG_PATH = process.env.GV_DEPLOY_CONFIG_PATH
+  || (SHELL_DIR && existsSync(path.join(SHELL_DIR, "deploy.config.json"))
+      ? path.join(SHELL_DIR, "deploy.config.json") : null);
+if (DEPLOY_CONFIG_PATH) BUILD_ENV.GV_DEPLOY_CONFIG_PATH = DEPLOY_CONFIG_PATH;
+
+// Build inputs to watch — each space repo (its DS assets + prototypes) plus the
+// augur-owned build inputs. Specific subtrees only — never node_modules, .git, dist,
+// .wrangler, or space-specific bulk dirs (IGNORE below filters their events even
+// inside a watched space root; extend via GV_SCAN_IGNORE, comma-separated).
+const WATCH = [
+  path.join(ROOT, "build.js"),
+  path.join(ROOT, "src", "_worker.js"),
+  ...(IDENTITY_PATH ? [IDENTITY_PATH] : []),  // users + seed passwords → rebuild on change
+  ...(DEPLOY_CONFIG_PATH ? [DEPLOY_CONFIG_PATH] : []),  // instance config → rebuild on change
+  path.join(ROOT, "src", "canvas"),  // the infinite-canvas engine (emitted to /__canvas)
+  path.join(ROOT, "src", "review"),  // comment/annotation overlay (emitted to /__review)
+  path.join(ROOT, "pitis"),          // augur-owned cursor-companion layer
+  ...(usingSiblings ? siblingSpaces : [path.join(ROOT, "spaces")]),
+];
+
+// Paths whose changes are noise — ignore even if they live under a watched root.
+const IGNORE = [
+  "node_modules", "/.git/", "/dist/", "/.wrangler/", ".DS_Store",
+  ...(process.env.GV_SCAN_IGNORE || "").split(",").filter(Boolean),
+];
+// endsWith catches an event for the .git dir itself (no trailing slash) — the watch
+// roots are now whole sibling repos, which contain a real .git.
+const ignored = (abs) => IGNORE.some((frag) => abs.includes(frag)) || abs.endsWith("/.git");
+
+// ── build (run-to-completion, with a queued-rebuild guard) ───────────────────
+let building = false;
+let pending = false;
+
+function build(reason) {
+  if (building) { pending = true; return; }
+  building = true;
+  const started = Date.now();
+  log(`↻ building${reason ? ` (${reason})` : ""}…`);
+  const proc = spawn("node", ["build.js"], { cwd: ROOT, env: BUILD_ENV, stdio: ["ignore", "ignore", "pipe"] });
+  let err = "";
+  proc.stderr.on("data", (d) => { err += d; });
+  proc.on("close", (code) => {
+    building = false;
+    if (code === 0) log(`✓ built in ${((Date.now() - started) / 1000).toFixed(1)}s`);
+    else log(`✗ build failed (exit ${code})\n${err.trim()}`);
+    if (pending) { pending = false; build("queued change"); }
+  });
+}
+
+// ── initial build, then launch wrangler ──────────────────────────────────────
+log(`starting offline mode — building from ${usingSiblings ? "canonical sibling space clones (edit-here)" : "nested submodules (pinned)"}`);
+log(`  spaces: ${usingSiblings ? siblingSpaces.join(", ") : path.join(ROOT, "spaces")}`);
+await new Promise((resolve) => {
+  const proc = spawn("node", ["build.js"], { cwd: ROOT, env: BUILD_ENV, stdio: "inherit" });
+  proc.on("close", resolve);
+});
+
+log(`serving on http://localhost:${PORT}  (Ctrl-C to stop)`);
+// The posture prints on EVERY run, because a posture nobody prints is a posture nobody
+// checks. It carries no credential, which is the reason the banner takes the derived
+// posture rather than the env file.
+log(POSTURE.live
+  ? `KV: \x1b[1mLIVE\x1b[0m\x1b[35m — ${POSTURE.reason} (prototypes stay local)`
+  : `KV: local — ${POSTURE.reason}`);
+log({
+  joined: "realtime: LIVE — canvas boards join the instance's real rooms through /__rt",
+  solo: "realtime: \x1b[1mUNAVAILABLE\x1b[0m\x1b[35m — no RT_SHARED_SECRET in .env.deploy; canvas boards run SOLO (saves still land in prod KV)",
+  disabled: "realtime: disabled (sandbox) — canvas boards run solo against local KV",
+}[POSTURE.realtime]);
+let wrangler = null;
+let stopping = false;
+const crashTimes = [];
+// The config wrangler runs from, rewritten on every start so it can never be stale, and
+// written under .wrangler/ so a stray `npx wrangler` in this clone cannot pick it up.
+// Regenerating it here rather than committing it is also what keeps the gate line
+// (`run_worker_first`) impossible to lose to a local edit.
+const WRANGLER_CONFIG = path.join(ROOT, ".wrangler", "offline.toml");
+mkdirSync(path.dirname(WRANGLER_CONFIG), { recursive: true });
+writeFileSync(WRANGLER_CONFIG, offlineWranglerConfig({ root: ROOT }));
+
+function spawnWrangler() {
+  wrangler = spawn(
+    "npx",
+    // `wrangler dev`, not `wrangler pages dev` — the front door a deployed instance uses.
+    // `--local` is explicit rather than assumed: the COMMENTS binding here is a local
+    // namespace and must stay one. A live run reaches production KV through the REST shim
+    // inside the worker (GV_KV_* below), which is a different mechanism on purpose.
+    ["--yes", "wrangler", "dev",
+      "-c", WRANGLER_CONFIG,
+      "--local",
+      ...POSTURE_VARS,
+      "--port", PORT,
+      "--persist-to", ".wrangler/state"],
+    { cwd: ROOT, stdio: "inherit" },
+  );
+  // A workerd crash must not take the whole offline server with it — every open tab
+  // would lose its save rail AND its room at once, and unsaved board edits would sit
+  // in browser memory until someone noticed the port was dead. Respawn instead, with
+  // a crash-loop cutoff (policy in lib/offline-respawn.mjs) so an unstartable worker
+  // (port taken, broken build) fails loudly rather than restart-storming.
+  wrangler.on("close", (code) => {
+    if (stopping) process.exit(code ?? 0);
+    const now = Date.now();
+    const delay = respawnDelay(crashTimes, now);
+    crashTimes.push(now);
+    if (delay === null) {
+      log(`wrangler exited (${code}) — crash loop, giving up. Fix the cause and restart.`);
+      process.exit(code ?? 1);
+    }
+    log(`wrangler exited (${code}) — respawning in ${delay / 1000}s`);
+    setTimeout(spawnWrangler, delay);
+  });
+}
+spawnWrangler();
+
+// ── watch inputs, debounce, rebuild ──────────────────────────────────────────
+let timer = null;
+const onChange = (root) => (_evt, file) => {
+  // For a directory target, `file` is the path within it; for a file target, `file`
+  // is just that file's basename (so don't re-join it onto the already-full root).
+  const abs = file && !root.endsWith(file) ? path.join(root, file) : root;
+  if (ignored(abs)) return;
+  clearTimeout(timer);
+  timer = setTimeout(() => build(path.relative(ROOT, abs)), 200); // debounce bursts of fs events
+};
+
+for (const target of WATCH) {
+  try {
+    watch(target, { recursive: true }, onChange(target));
+  } catch {
+    // A watched path may not exist in every checkout (e.g. an optional dir) — skip it.
+  }
+}
+log(`watching ${WATCH.length} input paths for changes`);
+
+// ── teardown ─────────────────────────────────────────────────────────────────
+function shutdown() {
+  log("stopping.");
+  stopping = true;
+  if (wrangler) wrangler.kill("SIGINT");
+  else process.exit(0);
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/scripts/og.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// og.mjs — compose a 1200×630 Open Graph card for a prototype: the prototype's
+// poster screenshot framed in a browser chrome, beside the title + site wordmark,
+// on the site's indigo shell background. Writes og.jpg into the folder.
+//
+// Run AFTER shoot.mjs (it reuses each folder's preview.webp as the screenshot).
+//
+//   node scripts/og.mjs <path/to/folder>   # one folder
+//   node scripts/og.mjs                     # every card target (same set as shoot)
+//
+// Requires: playwright (devDep).
+
+import { chromium } from "playwright";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const OG = { width: 1200, height: 630 };
+
+async function exists(p) { try { await fs.access(p); return true; } catch { return false; } }
+async function isDir(p) { try { return (await fs.stat(p)).isDirectory(); } catch { return false; } }
+
+async function entry(dir) {
+  if (await exists(path.join(dir, "index.html"))) return path.join(dir, "index.html");
+  const es = await fs.readdir(dir, { withFileTypes: true });
+  const h = es.find((e) => e.isFile() && e.name.endsWith(".html"));
+  return h ? path.join(dir, h.name) : null;
+}
+
+// Folders inside a space root that never hold card targets. Space discovery mirrors
+// shoot.mjs: editable sibling clones (../<x> with space.json) first, pinned spaces/<id>
+// mirrors as the fallback.
+// Extend via GV_SCAN_IGNORE (comma-separated dir names) for space-specific bulk dirs.
+const IGNORE = new Set(["node_modules", "skills", "scripts", "registry", ".git", ".github", ".claude",
+  ...(process.env.GV_SCAN_IGNORE || "").split(",").filter(Boolean)]);
+async function spaceRoots() {
+  const roots = [];
+  for (const base of [path.join(ROOT, ".."), path.join(ROOT, "spaces")]) {
+    try {
+      for (const e of await fs.readdir(base, { withFileTypes: true })) {
+        if (!e.isDirectory() || e.name.startsWith(".")) continue;
+        if (await exists(path.join(base, e.name, "space.json"))) roots.push(path.join(base, e.name));
+      }
+    } catch {}
+    if (roots.length) break;
+  }
+  return roots;
+}
+async function targets() {
+  const out = [];
+  for (const root of await spaceRoots()) {
+    for (const t of await fs.readdir(root, { withFileTypes: true })) {
+      if (!t.isDirectory() || IGNORE.has(t.name) || t.name.startsWith(".")) continue;
+      const pp = path.join(root, t.name, "prototypes");
+      if (await isDir(pp)) {
+        for (const p of await fs.readdir(pp, { withFileTypes: true }))
+          if (p.isDirectory()) out.push(path.join(pp, p.name));
+      }
+    }
+    for (const group of ["pages", "components", "base", "patterns", "playground"]) {
+      const g = path.join(root, group);
+      if (await isDir(g)) {
+        for (const e of await fs.readdir(g, { withFileTypes: true }))
+          if (e.isDirectory() && !e.name.startsWith(".")) out.push(path.join(g, e.name));
+      }
+    }
+  }
+  return out;
+}
+
+// Bare card: just the prototype preview, centered, bottom-flush, on the soft site
+// shell. No logo/title/text — those live in the og:* meta tags, not the image.
+function cardHTML({ posterDataUri }) {
+  return `<!doctype html><html><head><meta charset="utf-8">
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  html,body { width:1200px; height:630px; }
+  body { position:relative; overflow:hidden; background:#fbfbfd; }
+  body::before {
+    content:""; position:absolute; inset:0;
+    background:
+      radial-gradient(1000px 520px at 50% -22%, rgba(94,106,210,0.13), transparent 60%),
+      linear-gradient(180deg, #f3f4fb 0%, #fbfbfd 62%);
+  }
+  .shot {
+    position:absolute; left:50%; bottom:0; transform:translateX(-50%);
+    width:940px; display:block; border-radius:14px 14px 0 0;
+    box-shadow:0 34px 90px -30px rgba(16,24,40,0.46), 0 2px 8px rgba(16,24,40,0.06);
+  }
+</style></head><body>
+  <img class="shot" src="${posterDataUri}">
+</body></html>`;
+}
+
+async function makeCard(browser, dir) {
+  const file = await entry(dir);
+  const rel = path.relative(ROOT, dir);
+  if (!file) { console.log("· skip (no html):", rel); return false; }
+  const posterPath = path.join(dir, "preview.webp");
+  if (!(await exists(posterPath))) { console.log("· skip (no poster — run shoot):", rel); return false; }
+
+  const posterB64 = (await fs.readFile(posterPath)).toString("base64");
+  const posterDataUri = `data:image/webp;base64,${posterB64}`;
+  const out = path.join(dir, "og.jpg");
+
+  // Up to 2 attempts, with per-card failures caught so a single transient screenshot
+  // hiccup can't crash the run and abort `npm run deploy` — the existing committed
+  // card is left in place and the run continues. Mirrors shoot.mjs.
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    // 1× = the OG spec size (1200×630). Unfurl thumbnails render ~500px wide, so a
+    // higher DPR only bloats the file (some bots time out on multi-MB images).
+    const page = await browser.newPage({ viewport: OG, deviceScaleFactor: 1 });
+    try {
+      await page.setContent(cardHTML({ posterDataUri }), { waitUntil: "load" });
+      await page.waitForTimeout(200); // let the poster decode
+      // JPEG q85 keeps each committed card ~80–120KB (vs ~300KB PNG) — invisible on an
+      // unfurl thumbnail, ~3× lighter in the repo as the prototype count grows.
+      await page.screenshot({ path: out, type: "jpeg", quality: 85, clip: { x: 0, y: 0, ...OG } });
+      const kb = Math.round((await fs.stat(out)).size / 1024);
+      console.log("✓", rel + "/og.jpg", kb + "KB");
+      return true;
+    } catch (e) {
+      const msg = e.message.split("\n")[0];
+      if (attempt < 2) { console.log("· retry", rel, "—", msg); continue; }
+      console.log("✗ FAIL", rel, "—", msg);
+      return false;
+    } finally {
+      await page.close().catch(() => {});
+    }
+  }
+  return false;
+}
+
+// A folder needs a fresh card when it has no og.jpg, or its poster/entry html is
+// newer than the existing card. Mirrors shoot.mjs's --stale so deploys stay cheap.
+async function needsCard(dir) {
+  const card = path.join(dir, "og.jpg");
+  if (!(await exists(card))) return true;
+  const cardM = (await fs.stat(card)).mtimeMs;
+  const poster = path.join(dir, "preview.webp");
+  const file = await entry(dir);
+  for (const p of [poster, file].filter(Boolean)) {
+    if (await exists(p) && (await fs.stat(p)).mtimeMs > cardM) return true;
+  }
+  return false;
+}
+
+const argv = process.argv.slice(2);
+const staleOnly = argv.includes("--stale");
+const pathArg = argv.find((a) => !a.startsWith("--"));
+let list = pathArg ? [path.resolve(pathArg)] : await targets();
+
+if (staleOnly) {
+  const fresh = [];
+  for (const d of list) if (await needsCard(d)) fresh.push(d);
+  const skipped = list.length - fresh.length;
+  if (skipped) console.log(`stale: ${skipped} card(s) up to date · ${fresh.length} to (re)make`);
+  list = fresh;
+}
+
+if (!list.length) {
+  console.log("nothing to make — all OG cards current");
+} else {
+  const browser = await chromium.launch();
+  let ok = 0;
+  for (const d of list) if (await makeCard(browser, d)) ok++;
+  await browser.close();
+  console.log(`\nmade ${ok}/${list.length} OG cards`);
+}

package/scripts/one-tenant-resolver.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// one-tenant-resolver — the seam stays a seam.
+//
+// WHY. `resolveTenant(request, env)` is the single place that decides which workspace a
+// request belongs to. Its value is that it is SINGLE: today it answers statically, and
+// swapping in a Host-header resolver is then a body change with nothing else to find.
+// The way that value is lost is not a red test — it is one more `await resolveTenant(…)`
+// added somewhere convenient, which in a single-workspace deployment returns the same
+// answer as the first one and is therefore invisible to every other check. A second call
+// site is also a second place to forget, and two callers with different answers is the
+// bug the whole phase exists to remove.
+//
+// WHAT IS ENFORCED.
+//
+//   ONE DECLARATION, with the pinned signature `async function resolveTenant(request, env)`.
+//   The signature is the contract the next implementation has to honour: a resolver that
+//   quietly grows a third parameter is a resolver its callers have to know something extra
+//   about.
+//
+//   ONE CALL SITE, and it is inside the worker's `fetch()`, BEFORE the config load. After
+//   the load is too late — the config would have been read for whichever workspace the
+//   isolate happened to look at last, which is the failure being designed out.
+//
+// Comments do not count as calls: the header above names the function repeatedly, and so
+// does the worker's own. Lines whose first non-space character starts a comment are
+// skipped, which is enough here because the worker writes no code after a `//` on the
+// same line and its embedded client scripts are all indented inside template literals.
+//
+// Usage: node scripts/one-tenant-resolver.mjs [--worker <path>] [--quiet]
+// No config, no dependencies. Exit 1 on any failure.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const DECLARATION = /^async function resolveTenant\(request, env\)\s*\{/;
+const CALL = /\bresolveTenant\s*\(/;
+const FETCH_OPEN = /^\s*async fetch\(request, env, ctx\)\s*\{/;
+const LOAD_CONFIG = /\bloadConfig\s*\(/;
+
+const isComment = (line) => {
+  const t = line.trim();
+  return t.startsWith("//") || t.startsWith("*") || t.startsWith("/*");
+};
+
+// Returns every problem found, each as `{ kind, line, message }`. An empty list passes.
+export function checkTenantResolver(source) {
+  const lines = source.split("\n");
+  const problems = [];
+  const at = (re, from = 0) => {
+    for (let i = from; i < lines.length; i++) if (!isComment(lines[i]) && re.test(lines[i])) return i;
+    return -1;
+  };
+
+  const declared = [];
+  const calls = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (isComment(line)) continue;
+    if (DECLARATION.test(line)) { declared.push(i + 1); continue; }
+    if (/^\s*(async\s+)?function resolveTenant\b/.test(line) || /^\s*(const|let|var)\s+resolveTenant\b/.test(line)) {
+      problems.push({
+        kind: "signature", line: i + 1,
+        message: "resolveTenant is declared with a different shape — the pinned contract is " +
+          "`async function resolveTenant(request, env)` at module scope",
+      });
+      continue;
+    }
+    if (CALL.test(line)) calls.push(i + 1);
+  }
+
+  if (declared.length !== 1) {
+    problems.push({
+      kind: "declaration", line: declared[1] || 0,
+      message: `expected exactly 1 declaration of resolveTenant, found ${declared.length}`,
+    });
+  }
+
+  if (calls.length !== 1) {
+    problems.push({
+      kind: "call-sites", line: calls[1] || 0,
+      message: `expected exactly 1 call site, found ${calls.length}` +
+        (calls.length ? ` (lines ${calls.join(", ")})` : "") +
+        " — the seam's whole value is that there is one place to change",
+    });
+  }
+
+  const fetchOpen = at(FETCH_OPEN);
+  if (fetchOpen < 0) {
+    problems.push({
+      kind: "fetch", line: 0,
+      message: "could not find `async fetch(request, env, ctx) {` — this checker is reading the wrong file, " +
+        "or the worker's entry point was renamed and this check needs updating with it",
+    });
+  } else if (calls.length === 1) {
+    const call = calls[0];
+    const loadConfig = at(LOAD_CONFIG, fetchOpen) + 1;
+    if (call <= fetchOpen) {
+      problems.push({
+        kind: "placement", line: call,
+        message: `the call site is at line ${call}, outside fetch() (which opens at ${fetchOpen + 1}) — ` +
+          "the tenant is a property of the request and must be resolved where the request arrives",
+      });
+    } else if (loadConfig > 0 && call > loadConfig) {
+      problems.push({
+        kind: "placement", line: call,
+        message: `the call site (line ${call}) comes AFTER the config load (line ${loadConfig}) — ` +
+          "config must be loaded FOR a tenant, so the tenant has to be known first",
+      });
+    }
+  }
+
+  return { declared, calls, problems };
+}
+
+// ---- CLI ----------------------------------------------------------------------------
+
+function main(argv) {
+  const opt = (flag, fallback) => {
+    const i = argv.indexOf(flag);
+    return i > -1 && argv[i + 1] ? argv[i + 1] : fallback;
+  };
+  const quiet = argv.includes("--quiet");
+  const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+  const worker = path.resolve(opt("--worker", path.join(root, "src", "_worker.js")));
+
+  const from = path.relative(process.cwd(), worker);
+  const rel = !from || from.startsWith("..") ? worker : from;
+  const { calls, problems } = checkTenantResolver(fs.readFileSync(worker, "utf8"));
+
+  if (problems.length) {
+    for (const p of problems) {
+      const where = p.line ? `${rel}:${p.line}` : rel;
+      console.error(`${where}: resolveTenant: ${p.message}`);
+    }
+    console.error(`\n${problems.length} problem(s) — see the header of scripts/one-tenant-resolver.mjs`);
+    return 1;
+  }
+
+  if (!quiet) console.log(`${rel}: resolveTenant declared once, called once (line ${calls[0]}), before the config load`);
+  return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exit(main(process.argv.slice(2)));
+}

package/scripts/open.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// augur open <prototype> [--new] [--dir <folder>] [--session <label>]
+//
+// Open one prototype into a folder of its own, as a draft that is live at once at its own
+// address. Prints who else is drafting it. The folder holds only that prototype's files and
+// a `.augur/draft.json`; nothing else on this machine is shared with any other session.
+// See docs/drafts-that-land.md §4.
+import fs from "node:fs";
+import path from "node:path";
+import { target, buildStamp } from "./lib/store.mjs";
+import { markPathFor } from "./lib/marks.mjs";
+import { unitClient, doOpen } from "./lib/draft.mjs";
+import { installAdapters } from "./lib/adapters.mjs";
+import { normUnit } from "../src/unit-core.mjs";
+
+const log = (m) => console.error(`\x1b[35m[open]\x1b[0m ${m}`);
+const die = (m) => { console.error(`\x1b[31m[open]\x1b[0m ${m}`); process.exit(1); };
+const argv = process.argv.slice(2);
+const opt = (n) => { const i = argv.indexOf(n); return i > -1 ? argv[i + 1] : null; };
+const positional = argv.filter((a, i) => !a.startsWith("--") && !(i > 0 && argv[i - 1].startsWith("--")));
+
+const raw = positional[0];
+if (!raw) die("name a prototype: `augur open <opportunity>/<prototype>` (a folder path works too).");
+const unit = normUnit(markPathFor(raw) || raw);
+if (!unit) die(`"${raw}" is not a prototype path.`);
+let origin, token;
+try { ({ origin, token } = target({ needToken: true })); } catch (e) { die(e.message); }
+// The space id addresses blob uploads. A folder with a space.json names it; otherwise the
+// instance's own build stamp does (one workspace serves one space).
+let space = null;
+try { space = JSON.parse(fs.readFileSync("space.json", "utf8")).id; } catch (e) { /* not in a space folder */ }
+if (!space) { try { space = Object.keys((await buildStamp(origin)).spaces || {})[0] || null; } catch (e) { /* stamp unreachable */ } }
+if (!space) die("could not tell which space this instance serves — run from a folder with space.json, or set AUGUR_ORIGIN.");
+const session = process.env.AUGUR_SESSION || opt("--session") || `session-${process.pid}`;
+const dir = path.resolve(opt("--dir") || unit.split("/").filter(Boolean).pop());
+
+const client = unitClient({ origin, token, space, session });
+const isNew = argv.includes("--new");
+const r = await doOpen({ client, unit, dir, origin, space, session, now: new Date().toISOString(), isNew });
+if (!r.ok) {
+  if (r.error === "folder-not-empty") die(`${r.dir} is not empty — pick another folder with --dir.`);
+  if (r.error === "unknown-unit") die(`${unit} does not exist here. To create it: \`augur open --new ${unit.replace(/^\/|\/$/g, "")}\`.`);
+  if (r.error === "unit-exists") die(`${unit} exists already — open it without --new.`);
+  if (r.error === "units-not-configured") die("this instance does not serve drafts yet (no unit store bound).");
+  if (r.error === "bad-unit" && r.reason === "reserved-folder") die(`${unit} sits under a folder the engine reserves — a prototype lives at <opportunity>/<prototype>.`);
+  if (r.error === "bad-unit" && r.reason === "not-a-prototype-folder") die(`${unit} is not a prototype folder — name one as <opportunity>/<prototype>.`);
+  die(`could not open: ${r.error || r.status}${r.reason ? ` (${r.reason})` : ""}`);
+}
+log(r.isNew ? `draft ${r.draftId} on ${unit} — a NEW prototype; ${dir} is empty, write its index.html there` : `draft ${r.draftId} on ${unit} — ${r.files} file(s) in ${dir}`);
+// The agent tool's hooks, installed for this machine the first time a draft is opened
+// here (idempotent; `AUGUR_NO_ADAPTERS=1` skips it — the suite and CI set it).
+if (!process.env.AUGUR_NO_ADAPTERS) {
+  for (const a of installAdapters()) {
+    if (a.result === "installed") log(`${a.name}: editor hooks installed (${a.path}) — edits in a draft folder save on their own; edits to a shared checkout's prototypes are refused.`);
+    else if (a.result === "updated") log(`${a.name}: editor hooks updated (${a.path}).`);
+  }
+}
+if (r.others.length) {
+  log("also drafting this prototype right now:");
+  for (const o of r.others) log(`  ${o.session || "someone"} (${o.active ? "active" : "idle"})`);
+  log("nothing here stops you; if you both land, the second one syncs first.");
+}
+console.log(r.address);