@augurworks/augur 0.15.1

package/scripts/lib/instance.mjs

@@ -0,0 +1,74 @@
+// instance.mjs — how a script in this engine finds ITS instance's config.
+//
+// The engine is generic and shared by every instance: it carries no account ids, no
+// worker names, no origins. Those live in the DEPLOY SHELL — a sibling repo holding
+// identity.json + deploy.config.json — whose repo NAME differs per instance. So the
+// shell is resolved by SHAPE, never by name: a sibling dir with an identity.json at its
+// root that is not a space and is not the engine. Explicit env always wins; a raw engine
+// clone with no shell resolves to nothing, and callers fall back or fail loudly.
+//
+// build.js takes the same values through GV_IDENTITY_PATH / GV_DEPLOY_CONFIG_PATH (the
+// shell's CI passes them explicitly); this is the local-script equivalent.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ENGINE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+export function findShellDir(root = ENGINE_ROOT, originHost = "") {
+  const parent = path.join(root, "..");
+  try {
+    const shells = readdirSync(parent, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith(".")
+        && path.resolve(parent, e.name) !== path.resolve(root)
+        && !existsSync(path.join(parent, e.name, "space.json"))
+        && existsSync(path.join(parent, e.name, "identity.json")))
+      .map((e) => path.join(parent, e.name)).sort();
+    // Several instances can share one parent folder. When the caller knows which
+    // ORIGIN it is talking to, the shell whose declared siteOrigin matches that
+    // host wins; with one shell, or no host, it is the first by name.
+    if (originHost && shells.length > 1) {
+      const match = shells.find((s) => {
+        try {
+          const o = JSON.parse(readFileSync(path.join(s, "deploy.config.json"), "utf8")).siteOrigin || "";
+          return new URL(o).host === originHost;
+        } catch { return false; }
+      });
+      if (match) return match;
+    }
+    return shells[0] || null;
+  } catch { return null; }
+}
+
+// The host of an origin URL, or "" if it isn't one. Shared so every caller feeds
+// findShellDir the same shape.
+export function originHost(origin) {
+  try { return new URL(origin).host; } catch { return ""; }
+}
+
+// The instance's deploy.config.json (siteOrigin, realtimeOrigin, …) — the same file the
+// build injects into the worker. GV_DEPLOY_CONFIG_PATH wins, then the shell's, then one
+// at the engine root (a single-repo instance). Missing or unreadable → {}.
+//
+// `preferHost` disambiguates when several instances share one parent folder. Without
+// it findShellDir falls back to the first shell BY NAME, so with two shells checked
+// out side by side the alphabetically-first one answered for every space in the
+// folder — and since this config's siteOrigin outranks the space's own in every
+// origin-resolving caller, `augur publish` and `augur login` from space B aimed
+// themselves at instance A. Which live instance a publish reached came down to
+// directory sort order.
+//
+// Callers pass the host of the space's OWN declared siteOrigin: the space repo names
+// the instance it belongs to, so it is the right tiebreak. It is only ever a
+// tiebreak — with one shell (the ordinary case, and anyone who cloned a starter
+// space to run their own instance) the answer is that shell either way, so a fork
+// still publishes to ITS shell rather than to the origin its space.json inherited.
+export function deployConfig(root = ENGINE_ROOT, preferHost = "") {
+  const shell = findShellDir(root, preferHost);
+  const file = process.env.GV_DEPLOY_CONFIG_PATH
+    || [shell && path.join(shell, "deploy.config.json"), path.join(root, "deploy.config.json")]
+      .filter(Boolean).find((f) => existsSync(f));
+  if (!file || !existsSync(file)) return {};
+  try { return JSON.parse(readFileSync(file, "utf8")); } catch { return {}; }
+}

package/scripts/lib/marks.mjs

@@ -0,0 +1,107 @@
+// Working marks, client side — one definition of the path spelling and one of the phrasing.
+//
+// `F-presence-marks`. Three commands surface marks (`mark`, `status`, `pull`) and a fourth
+// will. If each spelled a path its own way, two agents naming the same folder would write
+// two rows and read past each other — which is the exact failure the feature exists to
+// prevent, arriving through the tool that was supposed to prevent it. So the normalization
+// here MIRRORS `normalizeMarkPath` in src/_worker.js on purpose, and the server's answer is
+// always the one printed back: the client never assumes its own spelling won.
+//
+// ⚠️ A MARK REFUSES NOTHING. Nothing in this file returns a verdict, sets an exit code, or
+// gives a caller something to branch on that would let it block. It reads, and it prints.
+
+/** Leading and trailing slash. Same rule as the worker, for the same containment reason. */
+export function normalizeMarkPath(p) {
+  const s = String(p == null ? "" : p).trim().slice(0, 300);
+  if (!s) return "";
+  const t = s.replace(/^\.\//, "").replace(/\/{2,}/g, "/");
+  if (!t || t === "/") return "/";
+  return `/${t.replace(/^\/+/, "").replace(/\/+$/, "")}/`;
+}
+
+/**
+ * A REPO folder, as the URL it publishes to.
+ *
+ * `<project>/prototypes/<name>` is the nesting `discoverSpaces()` looks in, and it is
+ * served at `/<project>/<name>/`. An agent has just been editing the folder, so it is the
+ * folder it will type; taking it without translation would mark a path no card and no
+ * published unit will ever match.
+ */
+export function markPathFor(input) {
+  return normalizeMarkPath(String(input == null ? "" : input).replace(/\/prototypes\//g, "/"));
+}
+
+/** Does either path contain the other? The whole overlap test. */
+export function marksOverlap(a, b) {
+  const x = normalizeMarkPath(a), y = normalizeMarkPath(b);
+  if (!x || !y) return false;
+  return x === y || x.startsWith(y) || y.startsWith(x);
+}
+
+/**
+ * Of the marks that were there before you wrote yours, whose are worth telling you about.
+ *
+ * ⚠️ "SOMEBODY ELSE" IS DECIDED BY WHO, NEVER BY WHERE, and this function exists so that
+ * decision has somewhere to be tested. The obvious way to stop your own renewal warning at
+ * you is to drop the exact path from the list — and that silently drops the ONE case the
+ * whole feature exists to surface: two agents on the same prototype. It shipped that way
+ * once and printed nothing at all for an exact collision, which is worse than not having
+ * the warning, because it reads as an all-clear.
+ *
+ * `mine` is the id the INSTANCE resolved from the credential and handed back, never one the
+ * client worked out for itself — the same rule the row's authorship follows.
+ */
+export function othersOverlapping(before, path, mine) {
+  return (before || []).filter((m) => m && m.personId !== mine && marksOverlap(m.path, path));
+}
+
+/**
+ * Every live mark at an instance. NEVER THROWS: a `status` or a `pull` that died because
+ * the coordination note could not be fetched would make the note the most fragile thing in
+ * the toolchain. An older instance answers 404 and gets an empty list, which reads exactly
+ * like "nobody is working on anything" — and is the right answer there, because on that
+ * instance nobody can be.
+ */
+export async function fetchMarks(req) {
+  try {
+    const r = await req("_marks/list");
+    const body = await r.json();
+    return Array.isArray(body.marks) ? body.marks : [];
+  } catch (e) { return []; }
+}
+
+const plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
+
+/** "4 minutes ago" / "just now", from a millisecond age. */
+export function since(ms) {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 45) return "just now";
+  if (s < 5400) return `${plural(Math.round(s / 60), "minute")} ago`;
+  return `${plural(Math.round(s / 3600), "hour")} ago`;
+}
+
+/**
+ * "for another 6 minutes", from a millisecond remainder.
+ *
+ * Switches to hours at exactly 3600s rather than at the 90 minutes `since` uses, because
+ * a mark's ceiling IS an hour: at the other threshold the longest mark anybody can ask
+ * for would read "for another 60 minutes", and the hours branch could never fire at all.
+ */
+export function forAnother(ms) {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `for another ${plural(s, "second")}`;
+  if (s < 3600) return `for another ${plural(Math.round(s / 60), "minute")}`;
+  return `for another ${plural(Math.round(s / 3600), "hour")}`;
+}
+
+/**
+ * One line per mark. `by` is null when the id behind the mark resolves to nobody on the
+ * roster — a token an admin labelled by hand, or somebody who has since left — and
+ * "Someone" is the honest rendering of that, never a guess.
+ */
+export function markLine(m) {
+  const who = m.by || "Someone";
+  const started = Date.parse(m.startedAt);
+  const age = Number.isFinite(started) ? since(Date.now() - started) : "";
+  return `${m.path}  ${who}${age ? ` · started ${age}` : ""} · ${forAnother(m.expiresIn)}`;
+}

package/scripts/lib/materialize.mjs

@@ -0,0 +1,138 @@
+// Live URL → source path. The reverse of what build.js does one way.
+//
+// `C-clone-pull-materializer`. A published manifest is a map of URLs to content hashes.
+// Turning it back into an editable tree means undoing build.js's mapping, and that mapping
+// is LOSSY in one specific place: `/<folder>/<name>/` is a prototype whose source lives at
+// `<folder>/prototypes/<name>/`, while `/base/<name>/` is a gallery tier whose source is
+// the URL verbatim. Nothing in the path itself distinguishes them.
+//
+// SO IT DOES NOT GUESS. The manifest carries `routing.publicPrefixes`, which is exactly
+// the list of prototype folders — the same list the unpublish guard is built on. A URL
+// under one of those is a prototype; a URL under a tier name is a tier; everything else is
+// either verbatim or generated. Reading the answer out of the manifest is what makes this
+// correct rather than a heuristic that works until somebody names a project "base".
+//
+// WHAT IS GENERATED AND MUST NOT BE WRITTEN. A publish ships build OUTPUT as well as
+// source: the landing page, each project's index, each tier's index, the whole /tokens/
+// page and the search index. Writing those into a source tree would produce a tree that
+// rebuilds into something different from what it came from — a clone that cannot be
+// published back. They are skipped, and `skipped` reports what and why, because a silent
+// omission in a tool whose whole promise is "leaving is free" is the wrong kind of quiet.
+
+/** Gallery tiers: authored folders whose URL is their source path. */
+export const TIERS = Object.freeze(["base", "components", "pages", "patterns"]);
+
+/**
+ * Files at the root of a space that are real source.
+ *
+ * `registry.json` is the overlay catalog — the design system's contract, which the build
+ * REQUIRES beside a skill and refuses to build without — and `prototype-status.json` is
+ * the dev-status baseline every project index is rendered from. Both ship with the publish
+ * for exactly this reason (`C-clone-publish-roundtrip`): a clone that came back without them
+ * was a tree that could not be published again — the build said so only after the clone had
+ * said everything was fine — or one that rebuilt into a different site. The rule is the
+ * build's own: what it READS to reproduce a space travels; what it WRITES is skipped here.
+ */
+const ROOT_SOURCE = new Set(["space-icon.png", "space-icon.svg", "registry.json", "prototype-status.json"]);
+
+/** Generated pages a publish carries that no source tree contains. */
+const GENERATED_EXACT = new Set(["/index.html", "/__search.json"]);
+
+/**
+ * Decide what one published URL is.
+ * Returns { kind: "source", path } | { kind: "generated", why }.
+ *
+ * `prefixes` is the manifest's routing.publicPrefixes.
+ */
+export function classify(url, prefixes = []) {
+  if (!url || url[0] !== "/") return { kind: "generated", why: "not a rooted URL" };
+  if (GENERATED_EXACT.has(url)) return { kind: "generated", why: "the built landing page or search index" };
+
+  const rel = url.slice(1);
+  const parts = rel.split("/");
+
+  // Root-level source files.
+  if (parts.length === 1) {
+    return ROOT_SOURCE.has(parts[0])
+      ? { kind: "source", path: parts[0] }
+      : { kind: "generated", why: "a built file at the site root" };
+  }
+
+  // The design system's own assets ship verbatim under their declared prefix — with one
+  // exception build.js writes INTO the skill folder rather than beside it: graph.js, the
+  // composition graph parsed from the very stylesheets sitting next to it. It lives there
+  // because it is space content rather than shared chrome, and it is derived, so a clone
+  // that wrote it back would put build output into a source tree.
+  if (parts[0] === "skills") {
+    if (parts[parts.length - 1] === "graph.js") {
+      return { kind: "generated", why: "the composition graph, parsed from the stylesheets beside it" };
+    }
+    return { kind: "source", path: rel };
+  }
+
+  // The tokens page is generated FROM the stylesheet; the stylesheet itself lives under
+  // skills/ and is caught above.
+  if (parts[0] === "tokens") return { kind: "generated", why: "the tokens page is derived from the stylesheet" };
+
+  // A tier: /base/<name>/… is source at the same path. /base/index.html is the tier index,
+  // which build.js writes.
+  if (TIERS.includes(parts[0])) {
+    if (parts.length === 2 && parts[1] === "index.html") return { kind: "generated", why: `the ${parts[0]} tier index` };
+    return { kind: "source", path: rel };
+  }
+
+  // Playground ships verbatim; its folder index is generated.
+  if (parts[0] === "playground") {
+    if (parts.length === 2 && parts[1] === "index.html") return { kind: "generated", why: "the playground index" };
+    return { kind: "source", path: rel };
+  }
+
+  // Anything else is a project folder. A file directly inside it is that project's
+  // generated index; a file inside a NAMED sub-folder is a prototype — but only if the
+  // manifest says so, which is the whole point of consulting publicPrefixes.
+  if (parts.length === 2) return { kind: "generated", why: `the ${parts[0]} project index` };
+  const prefix = `/${parts[0]}/${parts[1]}/`;
+  if (prefixes.includes(prefix)) {
+    return { kind: "source", path: [parts[0], "prototypes", ...parts.slice(1)].join("/") };
+  }
+  return { kind: "generated", why: `not a published prototype (${prefix} is not in publicPrefixes)` };
+}
+
+/**
+ * Classify a whole manifest. Returns { files: [{url, path, h, s}], skipped: [{url, why}] }.
+ * Deterministic order, so two runs produce the same plan and a diff of the plan is readable.
+ */
+export function materializePlan(manifest) {
+  const prefixes = (manifest && manifest.routing && manifest.routing.publicPrefixes) || [];
+  const files = [], skipped = [];
+  for (const [url, meta] of Object.entries((manifest && manifest.files) || {}).sort(([a], [b]) => (a < b ? -1 : 1))) {
+    const c = classify(url, prefixes);
+    if (c.kind === "source") files.push({ url, path: c.path, h: meta && meta.h, s: (meta && meta.s) || 0 });
+    else skipped.push({ url, why: c.why });
+  }
+  return { files, skipped };
+}
+
+/**
+ * A space.json for a cloned tree. space.json is not a served asset and is in no manifest
+ * as a file, so it has to be synthesized — and it is deliberately minimal: anything
+ * INFERRED rather than known would be a guess written into the file that decides how the
+ * space builds.
+ *
+ * What the manifest does KNOW is carried (`C-clone-publish-roundtrip`): the build records
+ * the space's own record on every manifest (`manifest.space` — name, badge, description,
+ * projects label, help sections), and each of those is baked into the generated pages, so
+ * a tree without them rebuilds into a site with a different name on it. They are copied
+ * only when the record actually carries them; an empty value is the build's default, not
+ * a fact about the space. `siteOrigin` is always the origin this clone was taken from —
+ * the address the workspace answers at now — never one recorded before a move.
+ */
+export function synthesizeSpaceJson(id, origin, space = null) {
+  const out = { id, default: true, siteOrigin: origin };
+  const s = space && typeof space === "object" ? space : {};
+  for (const k of ["name", "badge", "description", "projectsLabel"]) {
+    if (typeof s[k] === "string" && s[k].trim()) out[k] = s[k];
+  }
+  if (Array.isArray(s.help) && s.help.length) out.help = s.help;
+  return out;
+}

package/scripts/lib/merge3.mjs

@@ -0,0 +1,124 @@
+// merge3.mjs — line diff and three-way merge, for `augur sync`.
+//
+// The server never merges (docs/drafts-that-land.md). What the CLI may do, on the agent's
+// own disk and for the agent to check, is fold a landing on main into a draft where the two
+// sets of changes touch DIFFERENT lines. Where they touch the same lines it stops and says
+// so — both versions are handed over, nothing is guessed.
+//
+// Plain Node, no dependencies. The diff trims the common prefix and suffix first — an
+// agent's edit is a few hunks in a mostly identical file — and runs a plain longest-common-
+// subsequence table over what is left. A middle region too large for the table (a rewrite,
+// not an edit) becomes ONE hunk: coarser, so it conflicts more readily, and never wrong.
+
+/** Cells the LCS table may hold before the middle is treated as one hunk (2000 × 2000). */
+export const LCS_CELLS = 4_000_000;
+
+/** Replace hunks turning `a` into `b`, both arrays of lines. */
+export function diffLines(a, b) {
+  let pre = 0;
+  while (pre < a.length && pre < b.length && a[pre] === b[pre]) pre++;
+  let suf = 0;
+  while (suf < a.length - pre && suf < b.length - pre && a[a.length - 1 - suf] === b[b.length - 1 - suf]) suf++;
+  const A = a.slice(pre, a.length - suf), B = b.slice(pre, b.length - suf);
+  return hunksLCS(A, B).map((h) => ({ aStart: h.aStart + pre, aEnd: h.aEnd + pre, bStart: h.bStart + pre, bEnd: h.bEnd + pre }));
+}
+
+function hunksLCS(a, b) {
+  const N = a.length, M = b.length;
+  if (!N && !M) return [];
+  if (!N) return [{ aStart: 0, aEnd: 0, bStart: 0, bEnd: M }];
+  if (!M) return [{ aStart: 0, aEnd: N, bStart: 0, bEnd: 0 }];
+  if (N * M > LCS_CELLS) return [{ aStart: 0, aEnd: N, bStart: 0, bEnd: M }];
+  // dp[i][j] = length of the longest common subsequence of a[i..] and b[j..]
+  const dp = new Array(N + 1);
+  for (let i = 0; i <= N; i++) dp[i] = new Uint32Array(M + 1);
+  for (let i = N - 1; i >= 0; i--) {
+    for (let j = M - 1; j >= 0; j--) {
+      dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    }
+  }
+  const hunks = [];
+  let i = 0, j = 0, open = null;
+  const close = () => { if (open) { open.aEnd = i; open.bEnd = j; hunks.push(open); open = null; } };
+  while (i < N || j < M) {
+    if (i < N && j < M && a[i] === b[j]) { close(); i++; j++; continue; }
+    if (!open) open = { aStart: i, aEnd: i, bStart: j, bEnd: j };
+    if (j < M && (i >= N || dp[i][j + 1] >= dp[i + 1][j])) j++; // a line of b is inserted
+    else i++;                                                    // a line of a is deleted
+  }
+  close();
+  return hunks;
+}
+
+const split = (s) => {
+  const str = String(s);
+  if (str === "") return { lines: [], trailing: false };
+  const lines = str.split("\n");
+  const trailing = lines[lines.length - 1] === "";
+  if (trailing) lines.pop();
+  return { lines, trailing };
+};
+
+/** Push `arr`'s elements onto `out` without spreading — a spread throws past ~120k args. */
+function append(out, arr) {
+  for (let i = 0; i < arr.length; i += 10000) push.apply(out, arr.slice(i, i + 10000));
+  return out;
+}
+const push = Array.prototype.push;
+
+/** Three-way merge of strings. Overlaps are conflicts, never guesses. */
+export function merge3(base, mine, theirs) {
+  const B = split(base), A = split(mine), C = split(theirs);
+  const ha = diffLines(B.lines, A.lines).map((h) => ({ ...h, side: "mine", lines: A.lines.slice(h.bStart, h.bEnd) }));
+  const hc = diffLines(B.lines, C.lines).map((h) => ({ ...h, side: "theirs", lines: C.lines.slice(h.bStart, h.bEnd) }));
+  const out = [];
+  const conflicts = [];
+  let pos = 0;
+  let i = 0, j = 0;
+  const overlaps = (p, q) => p.aStart < q.aEnd && q.aStart < p.aEnd || (p.aStart === p.aEnd && q.aStart === q.aEnd && p.aStart === q.aStart);
+  while (i < ha.length || j < hc.length) {
+    const p = ha[i], q = hc[j];
+    let take, region;
+    if (p && q && overlaps(p, q)) {
+      // Grow the region until neither side overlaps it any further.
+      let start = Math.min(p.aStart, q.aStart), end = Math.max(p.aEnd, q.aEnd);
+      let ii = i + 1, jj = j + 1;
+      for (;;) {
+        let grew = false;
+        while (ii < ha.length && ha[ii].aStart < end) { end = Math.max(end, ha[ii].aEnd); ii++; grew = true; }
+        while (jj < hc.length && hc[jj].aStart < end) { end = Math.max(end, hc[jj].aEnd); jj++; grew = true; }
+        if (!grew) break;
+      }
+      const mineLines = applyHunks(B.lines, ha.slice(i, ii), start, end);
+      const theirLines = applyHunks(B.lines, hc.slice(j, jj), start, end);
+      const identical = mineLines.length === theirLines.length && mineLines.every((l, k) => l === theirLines[k]);
+      if (!identical) conflicts.push({ baseStart: start, baseEnd: end, mine: mineLines, theirs: theirLines });
+      take = mineLines; region = { aStart: start, aEnd: end };
+      i = ii; j = jj;
+    } else if (!q || (p && p.aStart <= q.aStart)) {
+      take = p.lines; region = p; i++;
+    } else {
+      take = q.lines; region = q; j++;
+    }
+    append(out, B.lines.slice(pos, region.aStart));
+    append(out, take);
+    pos = region.aEnd;
+  }
+  append(out, B.lines.slice(pos));
+  const trailing = A.trailing || C.trailing;
+  const text = out.length === 0 ? "" : out.join("\n") + (trailing ? "\n" : "");
+  return { ok: conflicts.length === 0, text, conflicts };
+}
+
+/** The lines `base[start..end)` become after applying `hunks` (all inside that range). */
+function applyHunks(base, hunks, start, end) {
+  const out = [];
+  let pos = start;
+  for (const h of hunks) {
+    append(out, base.slice(pos, h.aStart));
+    append(out, h.lines);
+    pos = h.aEnd;
+  }
+  append(out, base.slice(pos, end));
+  return out;
+}

package/scripts/lib/offline-posture.mjs

@@ -0,0 +1,120 @@
+// Which store a local preview talks to, and whether its canvas joins the real rooms.
+//
+// WHY THIS IS ITS OWN FILE. It used to be twenty lines in the middle of offline.mjs with
+// no coverage at all, and it decides the one thing about local development that can hurt
+// somebody else: whether `npm run offline` reads and writes the LIVE KV namespace — real
+// comments, real pins, real rosters, real canvas boards — or a local sandbox.
+//
+// Getting it backwards is silent in both directions. A run that thinks it is live but is
+// not shows an empty site and wastes an afternoon. A run that thinks it is a sandbox but
+// is not writes a stranger's comment thread from a half-finished branch. Neither prints
+// a warning, because both are working exactly as the code says.
+//
+// A refactor of exactly this code is how the second one ships green, which is why it is
+// now a pure function with a table of cases under it.
+//
+// THE RULE, and it is one rule with two halves that must agree:
+//
+//   LIVE     the credentials for the real namespace are all present, so the worker talks
+//            to production KV through the REST shim. If the instance's realtime secret is
+//            there too, the canvas joins the real rooms; without it the realtime worker
+//            answers 403 and the canvas degrades to solo, which is correct but worth
+//            knowing.
+//   SANDBOX  no credentials, so KV is local — AND realtime is disabled outright. A
+//            "sandbox" whose boards still broadcast into the shared production rooms is
+//            not a sandbox, and that half is the one somebody would drop by accident.
+
+/** Parse a KEY=value env file. Tolerant by design: a missing file is an empty posture. */
+export function parseEnvFile(text) {
+  const out = {};
+  for (const line of String(text || "").split("\n")) {
+    const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+    if (m) out[m[1]] = m[2].trim();
+  }
+  return out;
+}
+
+/**
+ * Decide the posture from a parsed env file.
+ *
+ * Returns {live, realtime, reason, kv, secrets} where `secrets` is a name→value map the
+ * caller turns into bindings. `reason` is a sentence for a human: this is the value that
+ * gets printed, and a posture nobody prints is a posture nobody checks.
+ */
+export function derivePosture(envFile = {}, opts = {}) {
+  const e = envFile || {};
+  const wanted = ["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID", "GV_KV_NS"];
+  const present = wanted.filter((k) => e[k]);
+  const live = present.length === wanted.length;
+
+  // An explicit sandbox request beats credentials that happen to be lying around. There
+  // is deliberately no inverse flag: nothing may turn a sandbox into a live run except
+  // the credentials themselves being present.
+  if (opts.forceSandbox) {
+    return {
+      live: false, realtime: "disabled",
+      reason: "sandbox (forced): local KV, realtime disabled",
+      kv: "local", secrets: { GV_RT_DISABLE: "1" },
+    };
+  }
+
+  if (!live) {
+    // PARTIAL credentials are the case worth naming. Two of three present means somebody
+    // is halfway through configuring, and silently running as a sandbox reads as "the
+    // credentials do not work".
+    const partial = present.length > 0;
+    return {
+      live: false, realtime: "disabled",
+      reason: partial
+        ? `sandbox: local KV, realtime disabled — ${wanted.filter((k) => !e[k]).join(", ")} missing from .env.deploy`
+        : "sandbox: local KV, realtime disabled",
+      kv: "local", secrets: { GV_RT_DISABLE: "1" },
+      missing: wanted.filter((k) => !e[k]),
+    };
+  }
+
+  const secrets = {
+    GV_KV_TOKEN: e.CLOUDFLARE_API_TOKEN,
+    GV_KV_ACCOUNT: e.CLOUDFLARE_ACCOUNT_ID,
+    GV_KV_NS: e.GV_KV_NS,
+  };
+  if (e.RT_SHARED_SECRET) {
+    secrets.RT_SHARED_SECRET = e.RT_SHARED_SECRET;
+    return {
+      live: true, realtime: "joined",
+      reason: "LIVE production KV, and the canvas joins the real rooms",
+      kv: "live", secrets,
+    };
+  }
+  return {
+    live: true, realtime: "solo",
+    reason: "LIVE production KV; no RT_SHARED_SECRET, so boards run solo (the realtime worker will 403)",
+    kv: "live", secrets,
+  };
+}
+
+/**
+ * The wrangler argv a posture implies: `--var K:V` per secret.
+ *
+ * ON ARGV RATHER THAN IN THE GENERATED CONFIG. These values are a Cloudflare API token and
+ * the shared realtime secret, read out of `.env.deploy`. Putting them in the wrangler.toml
+ * the offline server writes would be a SECOND copy of a live credential on disk, in a file
+ * nobody edits and everybody forgets — the first copy at least announces itself by name.
+ *
+ * `--var K:V` splits on the FIRST colon and keeps the rest, so a secret containing colons
+ * survives (verified against the wrangler this repo spawns). `--var K=V` is silently
+ * ignored — it binds nothing and reports nothing, which is why this is one function with a
+ * test rather than a string built at the call site.
+ */
+export function postureVars(posture) {
+  return Object.entries(posture.secrets || {}).flatMap(([k, v]) => ["--var", `${k}:${v}`]);
+}
+
+/**
+ * The line a human reads before deciding whether to type anything. It must never carry a
+ * credential — the whole point is that it is printed on every run, and a token echoed on
+ * every local start ends up in a screen recording.
+ */
+export function postureBanner(posture) {
+  return `[offline] KV: ${posture.kv} — ${posture.reason}`;
+}

package/scripts/lib/offline-respawn.mjs

@@ -0,0 +1,18 @@
+// Respawn policy for the offline server's wrangler child. Pure on purpose: the
+// decision ("respawn in N ms" / "give up") is the part worth testing, and importing
+// this must never spawn anything. See test/offline-sandbox.test.mjs.
+//
+// A crash LOOP (the port is taken, the built worker doesn't parse) must not turn
+// into an infinite restart storm: five crashes inside a minute means retrying won't
+// help and a human needs the log.
+const LOOP_WINDOW_MS = 60_000;
+const LOOP_LIMIT = 5;
+
+// crashTimes: ms timestamps of previous unexpected exits (any monotonic clock).
+// Returns the delay in ms before the next spawn, or null to give up.
+export function respawnDelay(crashTimes, now) {
+  const recent = crashTimes.filter((t) => now - t < LOOP_WINDOW_MS).length;
+  if (recent >= LOOP_LIMIT) return null;
+  // 1s, 2s, 4s, 8s… per recent crash — quick after a one-off, calmer under repeats.
+  return 1000 * Math.pow(2, recent);
+}

package/scripts/lib/offline-wrangler.mjs

@@ -0,0 +1,78 @@
+// The wrangler config `npm run offline` writes for itself.
+//
+// `A-offline-worker`. The offline server used to spawn `wrangler pages dev dist`, which
+// needs no config at all — Pages takes the asset directory as an argument and infers the
+// rest. A plain Worker cannot: the asset directory, its binding, the KV namespace and the
+// entry all have to be declared, and one of those declarations IS THE LOGIN GATE.
+//
+// WHY LOCAL DEVELOPMENT MOVES TO THE WORKER FRONT DOOR AT ALL. Pages and Workers invert
+// request precedence, silently. Pages runs the worker first and lets it decide what is
+// public; a Worker serves a MATCHING STATIC ASSET FIRST and only invokes the worker on a
+// miss, unless `run_worker_first = true`. The asset directory here is `dist`, and
+// `dist/__config/instance.json` carries the roster INCLUDING SEED PASSWORDS. So the
+// difference between the two front doors is the difference between a gated site and a
+// published roster, and until now nobody ran the second one except in production.
+//
+// Running it locally every day is how that difference gets found by a person rather than
+// by a stranger. It is the same reasoning as scripts/wrangler-preflight.mjs, one step
+// earlier: the preflight refuses a bad deploy config, and this makes the good shape the
+// one every local run exercises.
+//
+// It is GENERATED rather than committed for the same reason the shell template is not a
+// live wrangler.toml: a config in the repo root is a config a stray `npx wrangler` picks
+// up. This one is written into `.wrangler/`, which is gitignored, and rewritten on every
+// start so it can never be stale.
+//
+// WHAT IS DELIBERATELY NOT IN IT: the posture secrets. Those are a live Cloudflare API
+// token and the shared realtime secret, and they ride on argv (see postureVars) so this
+// file never becomes a second copy of a credential on disk.
+
+/** The `[assets]` line the whole gate depends on. Exported so a test can name it. */
+export const RUN_WORKER_FIRST = "run_worker_first = true";
+
+/**
+ * The TOML text. Absolute paths throughout, because wrangler resolves them relative to the
+ * CONFIG rather than to the cwd, and this config does not live beside the things it names.
+ *
+ * @param {{root: string, compatibilityDate?: string, kvId?: string}} opts
+ */
+export function offlineWranglerConfig({ root, compatibilityDate = "2024-09-01", kvId = "offline-local" } = {}) {
+  if (!root) throw new Error("offlineWranglerConfig needs the engine root");
+  return `# GENERATED by scripts/offline.mjs on every start — edit that, not this.
+# Not a deploy config: no account, no real namespace id, no route. See
+# templates/shell/wrangler.example.toml for the shape a real instance uses.
+
+name = "augur-offline"
+# The REAL deploy entry, the same file a live Worker runs and the same one
+# scripts/no-tenant-globals.mjs scans — so a local run exercises the deployed module graph
+# rather than the copy build.js leaves in dist/.
+main = ${JSON.stringify(join(root, "src/entry.js"))}
+compatibility_date = ${JSON.stringify(compatibilityDate)}
+
+[assets]
+directory = ${JSON.stringify(join(root, "dist"))}
+binding = "ASSETS"
+# ⛔ THE GATE. Without this, a Worker serves a matching static asset BEFORE the worker runs
+# — including dist/__config/instance.json, which carries the roster with seed passwords,
+# and every built page. Pages had the opposite default, which is why this line is new and
+# why it is the one line in this file worth reading twice.
+${RUN_WORKER_FIRST}
+# A miss is a miss, so the worker's own 404 branches fire and dist/404.html is reachable.
+not_found_handling = "none"
+# /foo, /foo/ and /foo/index.html all resolve — what published prototype folders rely on.
+html_handling = "auto-trailing-slash"
+
+# Comments, pins, statuses, rosters, boards. LOCAL: a live run reaches production KV
+# through the REST shim in the worker (GV_KV_* on argv), never through this binding, so
+# there is nothing here that a stray local write could reach.
+[[kv_namespaces]]
+binding = "COMMENTS"
+id = ${JSON.stringify(kvId)}
+`;
+}
+
+// No node:path import: this module is pure text and its only path work is a join, which
+// keeps it testable without a filesystem.
+function join(a, b) {
+  return a.replace(/\/+$/, "") + "/" + b;
+}