@augurworks/augur 0.15.1

package/scripts/restore.mjs

@@ -0,0 +1,322 @@
+// restore.mjs — put an `augur export` copy back into a bundle store.
+//
+//   augur restore <dir>                 every space in the export
+//   … --space <id>                      one space
+//   … --dry-run                         report what would ship, send nothing
+//   … --force                           overwrite live content that is NEWER than the copy
+//   … --allow-unpublish                 permit taking live public pages down — the copy is
+//                                       the truth, and the target may hold pages it never had
+//   … --state                           ALSO replay the workspace state a `--full` export
+//                                       carries: roster, invites, publish tokens, statuses,
+//                                       card names, boards, comment threads, pins, images
+//
+// A restore is an ordinary publish: blobs first, then one manifest commit per
+// space, so it lands atomically and gets its own version number. It does NOT
+// rewrite history — the versions the store already holds stay where they are, and
+// the restored state arrives on top. That is deliberate: a restore run by mistake
+// is then undone by `rollback`, not by another restore.
+//
+// ⚠️ AND THE COPY'S OWN HISTORY IS NOT REPLAYED EITHER. `augur export --history` walks
+// every retained version's manifest and downloads every blob any of them referenced; this
+// command reads none of it. The target ends up holding ONE version — the restored one —
+// whatever the copy carries, so a workspace that arrives by restore or by `augur migrate`
+// can be rolled back exactly zero publishes. Said out loud at the end of a run rather than
+// discovered on the day somebody needs to roll one back. The archive is still worth
+// taking: the manifests under `versions/` name every file of every past publish and the
+// blobs are all on disk, so a specific past publish can be reconstructed by hand.
+//
+// Provenance survives. The manifest carries `source` (the space repo sha and the
+// dirty flag) through unchanged, so a restored site still reports honestly in
+// /_build.json what it was built from — including that it came from a working tree
+// if it did.
+//
+// Target and token resolve exactly as `augur publish` does; see lib/store.mjs.
+// Recovery walkthrough: `docs/2026-08-09-bundle-store-recovery.md`.
+
+import { readFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { target, apiClient, buildStamp, CLIENT_PROTOCOL } from "./lib/store.mjs";
+
+const log = (msg) => console.error(`\x1b[36m[restore]\x1b[0m ${msg}`);
+const die = (msg) => { log(msg); process.exit(1); };
+
+const args = process.argv.slice(2);
+const flag = (f) => args.includes(f);
+const opt = (f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : null; };
+// The first bare argument is the directory. Walked by index rather than found by
+// value so a value that happens to equal an option's argument can't confuse it.
+let DIR = null;
+for (let i = 0; i < args.length; i++) {
+  if (args[i].startsWith("--")) { if (args[i] === "--space") i++; continue; }
+  DIR = args[i];
+  break;
+}
+const ONE = opt("--space");
+const DRY = flag("--dry-run");
+const FORCE = flag("--force");
+// Opt-in, and deliberately not implied by the copy having state in it. Replaying the
+// roster and the publish tokens changes WHO CAN GET IN — a different and larger act than
+// putting content back, and the case where somebody wants only the content is real (a
+// content restore onto a workspace whose membership has moved on since).
+const STATE = flag("--state");
+// A restore's commit can legitimately take live pages down — the copy is the truth and
+// the target may hold pages the source never had. Same escape hatch, and the same
+// transport-only field, as publish: nothing is persisted.
+const ALLOW_UNPUBLISH = flag("--allow-unpublish");
+if (!DIR) die("name the export directory: augur restore <dir>");
+if (!existsSync(path.join(DIR, "export.json"))) die(`${DIR} has no export.json — not an augur export.`);
+
+// Lists what would go dark and names the way out. A restore that takes pages down is a
+// real case (the copy predates them), which is why the flag exists — and a restore run
+// against the wrong target is the other case, which is why it is not the default.
+function dieUnpublish(id, removed, count) {
+  const shown = removed.slice(0, 12);
+  die(`${id}: this restore would REMOVE ${count} public page(s) that are live right now:\n` +
+      shown.map((p) => `    ${p}`).join("\n") +
+      (count > shown.length ? `\n    … and ${count - shown.length} more` : "") + "\n\n" +
+      `  ${id} was not committed. The copy does not carry these pages, so restoring it\n` +
+      `  takes them off the site — anyone's shared links and embeds for them would start\n` +
+      `  showing the login page the moment they go. Check this is the target you meant.\n\n` +
+      `  If you really are taking them down, re-run with --allow-unpublish.`);
+}
+
+let origin, token;
+try { ({ origin, token } = target()); } catch (e) { die(e.message); }
+const req = apiClient(origin, token);
+
+const meta = JSON.parse(await readFile(path.join(DIR, "export.json"), "utf8"));
+log(`${DIR} (taken ${meta.exportedAt} from ${meta.origin}) → ${origin}${DRY ? " [dry run]" : ""}`);
+if (meta.origin && meta.origin !== origin) {
+  log(`\x1b[33m⚠ this copy was taken from ${meta.origin}, you are restoring to ${origin}\x1b[0m`);
+}
+
+const files = (await readdir(path.join(DIR, "manifests"))).filter((f) => f.endsWith(".json"));
+const ids = ONE ? [ONE] : files.map((f) => f.replace(/\.json$/, ""));
+
+// What is live now — so a restore can refuse to bury newer content by accident.
+let live = {};
+try {
+  const stamp = await buildStamp(origin);
+  live = { ...stamp.spaces, _engine: stamp.engine };
+} catch (e) {
+  // ⚠️ NAMED AS A GUARD THAT IS OFF, not as a shrug. An empty store is the expected reason
+  // and it is not the only one — a target behind a 500, a wrong origin, a CDN serving an
+  // error for `/_build.json` all land here, and in every one of those cases the next few
+  // lines will publish over whatever is live without ever comparing dates. "Proceeding" on
+  // its own reads as "nothing to worry about", which is true exactly once.
+  log("\x1b[33m⚠ could not read the live build stamp at " + origin + " — an EMPTY STORE looks "
+    + "like this, and so does a target that is merely unreachable. The newer-than-this-copy "
+    + "guard is OFF for this run: nothing will stop a restore burying live content.\x1b[0m");
+}
+
+// Spaces the TARGET refuses because they are not a workspace's to hold. Today that is one
+// space and one reason: on a deployment that resolves workspaces from the Host, the engine
+// chrome (`_engine`) is a single bundle serving every workspace, so no workspace's own
+// publish token may write it — see `sharedChromeRefusal` in src/_worker.js. A copy taken
+// from a single-workspace instance always carries `_engine`, and `augur migrate` is exactly
+// the command that moves such a copy onto a shared deployment, so this is the ordinary case
+// rather than an error. Named and counted, never silent: a restore that quietly dropped a
+// space would be indistinguishable from a complete one.
+const declined = [];
+const DECLINED_REASON = "chrome-not-writable-here";
+
+let restored = 0;
+for (const id of ids) {
+  const file = path.join(DIR, "manifests", `${id}.json`);
+  if (!existsSync(file)) die(`${id}: no manifest in this export.`);
+  const m = JSON.parse(await readFile(file, "utf8"));
+  const total = Object.keys(m.files || {}).length;
+  if (!total) die(`${id}: the exported manifest has no files — refusing to publish an empty space.`);
+
+  const now = live[id];
+  if (now && now.publishedAt && meta.exportedAt && now.publishedAt > meta.exportedAt && !FORCE) {
+    // ⚠️ "NEWER" IS NOT THE QUESTION — "DIFFERENT" IS, and the difference is what makes a
+    // re-run possible. A restore stamps `publishedAt` at the moment it commits, so its own
+    // result is by definition newer than the copy that produced it. Read literally, the date
+    // guard therefore fires on the SECOND run of any restore — including the one an operator
+    // makes after a run that died halfway, and including `augur migrate`'s, which passes no
+    // `--force` and whose header promises re-running is safe. It was not: a migration that
+    // failed after committing one space of two could not be repeated at all.
+    //
+    // So when the date says bury, ask what would be buried. The live manifest's file map
+    // against this copy's: identical means live IS this copy and there is nothing to lose.
+    // Anything else and the guard stands exactly as it did.
+    // Compared on the CONTENT ADDRESSING and nothing else — path → hash, sorted. The rest
+    // of a file's record is server-assigned: the commit handler stamps `{by, editedAt}` on
+    // every file whose bytes changed, so a live manifest is never field-for-field equal to
+    // the copy that produced it even when every byte it serves came from there. Comparing
+    // whole records would make this recognise nothing and re-runs would stay broken.
+    const addressing = (files) => JSON.stringify(
+      Object.keys(files || {}).sort().map((p) => [p, (files[p] || {}).h]),
+    );
+    let same = false;
+    try {
+      const liveManifest = await (await req(`${id}/manifest`)).json();
+      same = addressing(liveManifest.files) === addressing(m.files);
+    } catch (e) { /* cannot read it ⇒ cannot claim it is the same ⇒ refuse below */ }
+    if (!same) {
+      die(`${id}: live content (published ${now.publishedAt}) is NEWER than this copy (${meta.exportedAt}) ` +
+          `and its files DIFFER from it. Restoring would bury it. Re-run with --force if that is what you mean.`);
+    }
+    log(`${id}: live is newer than this copy but byte-identical to it — this is a re-run, continuing`);
+  }
+
+  // Ask the store which blobs it is missing, then send only those. This is also the first
+  // request of the space, so it is where a target that will not take this space at all says
+  // so — before a single blob is uploaded.
+  let check;
+  try {
+    check = await (await req(`${id}/check`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ files: m.files }),
+    })).json();
+  } catch (e) {
+    if (!String(e.message).includes(DECLINED_REASON)) throw e;
+    // Explicitly asked for ⇒ a refusal is an answer to the question, not a detour around it.
+    if (ONE === id) {
+      die(`${id}: this target will not take it — the page chrome there is one build shared by `
+        + "every workspace, so no workspace's publish token may write it.");
+    }
+    log(`\x1b[33m⚠ ${id}: this target serves it from a shared build and will not take a `
+      + "workspace's copy of it — SKIPPED, and nothing else in this copy is affected\x1b[0m");
+    declined.push(id);
+    continue;
+  }
+  const missing = [...new Set(check.missing || [])];
+  log(`${id}: ${total} files, ${missing.length} blobs to upload, live v${check.liveVersion || 0}`);
+  if (DRY) continue;
+
+  const queue = [...missing];
+  let failed = 0;
+  await Promise.all(Array.from({ length: 8 }, async () => {
+    while (queue.length) {
+      const h = queue.pop();
+      const blob = path.join(DIR, "blobs", h);
+      if (!existsSync(blob)) { failed++; log(`${id}: blob ${h.slice(0, 12)} is not in this export`); continue; }
+      const body = await readFile(blob);
+      for (let attempt = 0; ; attempt++) {
+        try { await req(`${id}/blob/${h}`, { method: "PUT", body }); break; }
+        catch (e) {
+          if (attempt >= 2) { failed++; log(`${id}: blob ${h.slice(0, 12)} failed: ${e.message}`); break; }
+        }
+      }
+    }
+  }));
+  // Nothing is committed on a partial upload, so the live site is untouched and the
+  // run can simply be repeated once the copy is complete.
+  if (failed) die(`${id}: ${failed} blob(s) missing or failed — nothing committed, live untouched.`);
+
+  // Strip the fields the store assigns on commit; everything else (files, routing,
+  // space meta, source) is restored verbatim.
+  const { version, publishedAt, publishedBy, ...body } = m;
+  let res;
+  try {
+    res = await (await req(`${id}/commit`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      // Same protocol declaration a normal publish makes — a restore is an ordinary
+      // publish, so an instance with a floor must be able to judge this client too.
+      body: JSON.stringify({ ...body, clientProtocol: CLIENT_PROTOCOL,
+        ...(ALLOW_UNPUBLISH ? { allowUnpublish: true } : {}) }),
+    })).json();
+  } catch (e) {
+    // The store's unpublish guard, in words rather than a status code — the same guard,
+    // and the same way out, a publish gets. Every space committed before this one stays
+    // restored; this one and the rest are untouched.
+    const refused = /→ 422 (\{.*\})/.exec(String(e && e.message || ""));
+    let detail = null;
+    try { detail = refused && JSON.parse(refused[1]); } catch (x) { /* not the guard */ }
+    if (detail && detail.error === "unpublish-refused") dieUnpublish(id, detail.removed || [], detail.count || 0);
+    throw e;
+  }
+  log(`${id}: restored as v${res.version}`);
+  restored++;
+}
+
+// ── the workspace state ────────────────────────────────────────────────────
+// After the content, because the content is the thing a half-finished restore most needs
+// to have landed: a workspace with its pages back and its comments missing is recoverable
+// by re-running this, and the other way round is a site serving nothing.
+let stateReport = null;
+let boardPaths = [];
+if (STATE) {
+  if (!meta.full) {
+    die("--state needs a copy taken with `augur export --full`; this one carries content only.");
+  }
+  const file = path.join(DIR, "state.json");
+  if (!existsSync(file)) die(`${DIR} says it is a full copy but has no state.json — do not trust it.`);
+  const doc = JSON.parse(await readFile(file, "utf8"));
+
+  // The canvas images first. A board that references an image the store does not have
+  // renders a hole, and the board doc is what arrives in the same breath.
+  const hashes = doc.assets || [];
+  // The type each image was served as, recorded by the export beside the bytes. The
+  // endpoint takes the type from THIS HEADER and stores anything that is not an image type
+  // as `image/jpeg` — so a PUT that sends none silently re-labels every PNG, GIF and WebP
+  // on the way in, and content addressing cannot notice because the bytes are right. An
+  // older copy has no sidecar; it keeps the old behaviour and says so.
+  let types = {};
+  try { types = JSON.parse(await readFile(path.join(DIR, "assets.json"), "utf8")); } catch (e) {}
+  const untyped = hashes.filter((h) => !types[h]);
+  if (untyped.length) {
+    log(`\x1b[33m⚠ ${untyped.length} of ${hashes.length} image(s) carry no recorded content type `
+      + `(a copy taken before assets.json existed) — they will be stored as image/jpeg. `
+      + `Re-run \`augur export --full\` against the source to record them.\x1b[0m`);
+  }
+  let sent = 0, missing = 0;
+  for (const h of hashes) {
+    const blob = path.join(DIR, "assets", h);
+    if (!existsSync(blob)) { missing++; log(`image ${h.slice(0, 12)} is not in this export`); continue; }
+    if (DRY) { sent++; continue; }
+    try {
+      await req(`_state/asset/${h}`, {
+        method: "PUT",
+        body: await readFile(blob),
+        ...(types[h] ? { headers: { "content-type": types[h] } } : {}),
+      });
+      sent++;
+    } catch (e) { missing++; log(`image ${h.slice(0, 12)} failed: ${e.message}`); }
+  }
+  if (missing) die(`${missing} canvas image(s) missing or failed — nothing replayed, live state untouched.`);
+
+  const families = Object.keys(doc.families || {});
+  boardPaths = Object.keys((doc.families || {})["board:"] || {});
+  log(`workspace state: ${families.length} famil(y/ies), ${hashes.length} image(s)`);
+  if (!DRY) {
+    const res = await (await req("_state/import", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(doc),
+    })).json();
+    if (!res.ok) die(`the instance refused the state: ${res.reason}${res.failed ? ` (${res.failed.join(", ")})` : ""}`);
+    if (res.skipped && res.skipped.length) log(`\x1b[33mskipped (not in the instance's inventory): ${res.skipped.join(", ")}\x1b[0m`);
+    stateReport = res;
+  }
+}
+
+if (DRY) { console.log("(dry run, nothing shipped)"); process.exit(0); }
+console.log(`${origin}  ${restored} space(s) restored`
+  + (declined.length ? `, ${declined.length} declined by the target (${declined.join(", ")})` : "")
+  + (stateReport ? `, ${stateReport.written.length} state famil(y/ies) replayed` : ""));
+if (!STATE && meta.full) {
+  log("\x1b[33mthis copy also carries the roster, comments, boards and pins — pass --state to replay them\x1b[0m");
+}
+
+// ── the two things a restore does NOT put back, said every time ──────────────
+// Both are silent by nature: the site comes up, everything anybody looks at is there, and
+// what is missing is only missing the day somebody reaches for it. A line each is cheap.
+if (meta.history) {
+  log("\x1b[33m⚠ this copy carries publish HISTORY and a restore does not replay it — "
+    + `${origin} now holds one version per space, so \`augur rollback\` reaches nothing. `
+    + "The archive is intact on disk under versions/.\x1b[0m");
+}
+if (stateReport && boardPaths.length) {
+  log(`\x1b[33m⚠ ${boardPaths.length} canvas board(s) came from the KV MIRROR, which lags the `
+    + "room that owns them and has been measured minutes behind. Nothing here read the room. "
+    + "Per board, against the SOURCE, before you trust this:\x1b[0m");
+  for (const p of boardPaths) {
+    log(`    node scripts/board-snapshot.mjs move --from ${meta.origin || "<source>"} --to ${origin} --path ${p}`);
+  }
+}

package/scripts/review.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/*
+ * review.mjs — read & moderate prototype review comments straight from production.
+ *
+ * The user just drops pins on the live site (Shift+C → click an element → type).
+ * This tool reads them directly from the worker's secret-guarded export endpoint
+ * (no site password needed) and can resolve/close threads once addressed.
+ *
+ * Requires in .env.deploy (gitignored):
+ *   REVIEW_SITE_URL=https://your-project.pages.dev
+ *   REVIEW_EXPORT_KEY=<same value set as the Pages REVIEW_EXPORT_KEY secret>
+ *
+ * Usage:
+ *   node scripts/review.mjs                 # list every thread (rich: anchor, view, position, messages)
+ *   node scripts/review.mjs --open          # only unresolved threads
+ *   node scripts/review.mjs resolve <path> <id> ["note"]  # mark resolved (+ optional reply explaining the fix)
+ *   node scripts/review.mjs reply   <path> <id> "note"    # post a reply without resolving
+ *   node scripts/review.mjs reopen  <path> <id>   # mark it open again
+ *   node scripts/review.mjs delete  <path> <id>   # remove a thread
+ *
+ * Convention: when resolving, pass a very brief note saying HOW it was fixed — it
+ * posts as a "Claude" reply on the thread so the reviewer sees the resolution inline.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+async function loadEnv() {
+  const env = { ...process.env };
+  try {
+    const raw = await fs.readFile(path.join(ROOT, ".env.deploy"), "utf8");
+    for (const line of raw.split("\n")) {
+      const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+      if (m) env[m[1]] = m[2].replace(/^["']|["']$/g, "");
+    }
+  } catch {}
+  return env;
+}
+
+function fmt(iso) {
+  try { return new Date(iso).toLocaleString("en-US", { dateStyle: "medium", timeStyle: "short" }); }
+  catch { return iso || ""; }
+}
+
+async function main() {
+  const env = await loadEnv();
+  const base = (env.REVIEW_SITE_URL || "").replace(/\/$/, "");
+  const key = env.REVIEW_EXPORT_KEY;
+  if (!base || !key) {
+    console.error("Missing REVIEW_SITE_URL / REVIEW_EXPORT_KEY in .env.deploy.");
+    process.exit(1);
+  }
+  const exportUrl = `${base}/__review/api/export?key=${encodeURIComponent(key)}`;
+  const [cmd, argPath, argId, argNote] = process.argv.slice(2).filter((a) => a !== "--open");
+  const openOnly = process.argv.includes("--open");
+
+  const postOp = async (op) => {
+    const res = await fetch(exportUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(op),
+    });
+    if (!res.ok) { console.error(`Failed: ${res.status} ${res.statusText}`); process.exit(1); }
+    return res.json();
+  };
+
+  // ---- moderation ops (resolve / reopen / delete / reply) ----
+  if (cmd === "resolve" || cmd === "reopen" || cmd === "delete" || cmd === "reply") {
+    if (!argPath || !argId || (cmd === "reply" && !argNote)) {
+      console.error(`Usage: node scripts/review.mjs ${cmd} <path> <id>${cmd === "reply" ? ' "note"' : cmd === "resolve" ? ' ["note"]' : ""}`);
+      process.exit(1);
+    }
+    // Post the explanation reply first (resolve w/ note, or a bare reply).
+    if ((cmd === "resolve" || cmd === "reply") && argNote) {
+      await postOp({ path: argPath, op: "reply", id: argId,
+        message: { author: "Claude", body: argNote, at: new Date().toISOString() } });
+    }
+    if (cmd === "reply") {
+      console.log(`✓ replied on ${argId} (${argPath}).`);
+      return;
+    }
+    const op = cmd === "delete"
+      ? { path: argPath, op: "delete", id: argId }
+      : { path: argPath, op: "resolve", id: argId, resolved: cmd === "resolve" };
+    const data = await postOp(op);
+    console.log(`✓ ${cmd} ${argId} on ${argPath}${argNote ? " (+note)" : ""} — ${(data.threads || []).length} thread(s) remain on that page.`);
+    return;
+  }
+
+  // ---- read ----
+  const res = await fetch(exportUrl);
+  if (!res.ok) { console.error(`Export failed: ${res.status} ${res.statusText}`); process.exit(1); }
+  const data = await res.json();
+  const pages = data.pages || {};
+  const keys = Object.keys(pages).filter((p) => (pages[p] || []).length).sort();
+  console.log(`Review comments — pulled ${fmt(data.generatedAt)} from ${base}\n`);
+  const isAnno = (t) => !!t.annotation;
+  let total = 0, open = 0, annos = 0;
+  if (!keys.length) { console.log("No comments yet."); return; }
+  for (const p of keys) {
+    // Annotations are always-on dev-delivery notes, not feedback — never list them
+    // as actionable. --open hides them; the full list shows them flagged.
+    const threads = (pages[p] || []).filter((t) => (openOnly ? (!t.resolved && !isAnno(t)) : true));
+    if (!threads.length) continue;
+    console.log(`══ ${p}`);
+    threads.forEach((t) => {
+      total++;
+      if (isAnno(t)) annos++; else if (!t.resolved) open++;
+      const pos = (t.fx || t.fy)
+        ? `at ${Math.round(t.fx * 100)}%×${Math.round(t.fy * 100)}% of the element`
+        : `page ${Math.round(t.px)},${Math.round(t.py)}`;
+      const badge = isAnno(t) ? "📌 ANNOTATION (dev note — do NOT resolve)" : (t.resolved ? "✅" : "🟠");
+      console.log(`  • ${badge} id=${t.id}`);
+      console.log(`      module: ${t.sel || "(page)"}`);
+      console.log(`      view:   ${t.view || "(base)"}    pin: ${pos}`);
+      (t.messages || []).forEach((m) => console.log(`      “${m.body}”  — ${m.author}, ${fmt(m.at)}`));
+    });
+    console.log("");
+  }
+  console.log(`${total} thread(s)${openOnly ? "" : `, ${open} open comment(s), ${annos} annotation(s)`}.`);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/scripts/save.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// augur save — push every changed file in this draft folder. Live at the draft address on
+// return. Exit 1 with the reason when the instance refuses. See docs/drafts-that-land.md §4.
+import { resolveOrigin, resolveToken } from "./lib/store.mjs";
+import { readState, unitClient, doSave } from "./lib/draft.mjs";
+
+const die = (m) => { console.error(`\x1b[31m[save]\x1b[0m ${m}`); process.exit(1); };
+const dir = process.cwd();
+const st = readState(dir);
+if (!st) die("not a draft folder — run `augur open <prototype>` first.");
+const origin = st.origin || resolveOrigin();
+const token = resolveToken(origin);
+if (!token) die("no publish token — run `augur connect` once.");
+const client = unitClient({ origin, token, space: st.space, session: st.session });
+const r = await doSave({ client, dir });
+if (!r.ok) {
+  if (r.error === "stale-draft" || r.error === "stale-draft-revision") die("this draft moved under you (another process saved to it) — run `augur sync`.");
+  die(`save refused: ${r.error || r.status}`);
+}
+if (r.changed.length) console.error(`\x1b[35m[save]\x1b[0m ${r.changed.length} file(s) live at ${origin}${st.address}`);
+console.log(`${origin}${st.address}`);

package/scripts/shell-lint.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// shell-lint — a template-drift canary for deploy shells.
+//
+// health.yml asks "is what's LIVE what's in git?" for space content. This asks the
+// same question one layer up: is what a shell is RUNNING what the engine's template
+// says it should be running? Those workflows were hand-authored per shell for a long
+// time, so they drift silently — a fix lands in templates/shell/ and the shells that
+// already had a copy never take it, or a shell edits its own copy and the change is
+// invisible to everyone else.
+//
+// Run it FROM A SHELL, where both halves are already on disk:
+//
+//   node engine/scripts/shell-lint.mjs
+//
+// The engine submodule is the shell's pinned engine, so the templates it compares
+// against are the ones that shell is actually on — no fetching, no sha juggling.
+//
+//   --shell <path>      shell root (default: cwd)
+//   --templates <path>  template dir (default: <engine>/templates/shell)
+//   --strict            treat comment-only drift as failure too
+//   --quiet             only print problems
+//
+// Exit 1 on logic drift (or any drift under --strict). Missing/extra workflows are
+// reported but never fatal: which workflows a shell runs is that shell's call, and a
+// private prototype-delete or reseed workflow has no template by design.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ENGINE = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const argv = process.argv.slice(2);
+const opt = (f, d) => { const i = argv.indexOf(f); return i > -1 && argv[i + 1] ? argv[i + 1] : d; };
+const has = (f) => argv.includes(f);
+
+const SHELL = path.resolve(opt("--shell", process.cwd()));
+const TEMPLATES = path.resolve(opt("--templates", path.join(ENGINE, "templates", "shell")));
+const STRICT = has("--strict");
+const QUIET = has("--quiet");
+
+const say = (s) => { if (!QUIET) console.log(s); };
+const warn = (s) => console.log(s);
+
+// A template line whose VALUE is meant to be replaced before first use. The convention
+// across templates/shell is a `your-…` stand-in (your-site-origin.example,
+// your-pages-project), sometimes with a `# ←` pointer at what to put there; `<angled>`
+// is the older form. A shell that filled one of these in has done the right thing, so
+// a difference on such a line is expected, not drift.
+const isPlaceholder = (line) => /your-[a-z0-9-]+/i.test(line) || /#\s*←/.test(line) || /<[a-z][a-z0-9-]*>/i.test(line);
+
+// Not every fill-in has a `your-…` stand-in: some are a real, working value that a
+// shell is nonetheless expected to CHOOSE (engine-bump's TRACK is the case in point —
+// `release` is a legitimate setting, and so is `main`). Those are marked the way the
+// templates already mark them, with a `SET BEFORE USE` note in the comment block
+// directly above. Walk up the contiguous comment run to find it.
+function markedSetBeforeUse(lines, i) {
+  for (let k = i - 1; k >= 0; k--) {
+    const s = lines[k].trim();
+    if (!s.startsWith("#")) return false; // left the comment block without finding it
+    if (/SET BEFORE USE/i.test(s)) return true;
+  }
+  return false;
+}
+
+// Comments and blank lines carry no behaviour. A shell rewording a comment is worth
+// seeing but is not the thing this canary exists to catch, so it is reported apart
+// from logic drift unless --strict.
+const isProse = (line) => { const s = line.trim(); return s === "" || s.startsWith("#"); };
+
+// Longest common subsequence over lines — enough to align two versions of the same
+// file so an inserted block does not report every following line as changed.
+function align(a, b) {
+  const n = a.length, m = b.length;
+  const dp = Array.from({ length: n + 1 }, () => 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 ops = [];
+  let i = 0, j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) { ops.push({ t: "=", a: a[i], i, j }); i++; j++; }
+    else if (dp[i + 1][j] >= dp[i][j + 1]) { ops.push({ t: "-", a: a[i], i }); i++; }
+    else { ops.push({ t: "+", b: b[j], j }); j++; }
+  }
+  while (i < n) ops.push({ t: "-", a: a[i], i: i++ });
+  while (j < m) ops.push({ t: "+", b: b[j], j: j++ });
+  return ops;
+}
+
+// A removed line immediately followed by an added line is one line REWRITTEN. That
+// pairing is what lets a filled-in placeholder be recognised: the template side is the
+// line with `your-…` in it, and the shell side is whatever replaced it.
+const yamlKey = (line) => { const m = /^(\s*)([A-Za-z_][\w-]*):/.exec(line); return m ? `${m[1].length}:${m[2]}` : null; };
+
+function compare(templateSrc, shellSrc) {
+  const tLines = templateSrc.split("\n");
+  const ops = align(tLines, shellSrc.split("\n"));
+
+  // Pair each removal with the addition that REPLACED it, so a rewritten line reads as
+  // one change rather than two. Adjacency catches most of it. Same-key pairing catches
+  // the rest: when a shell also rewrites the comment block above a setting, the two
+  // halves drift apart in the op stream, and `TRACK: release` → `TRACK: main` would
+  // otherwise report as an unexplained insertion with nothing to compare it against.
+  const dels = [], adds = [];
+  for (let k = 0; k < ops.length; k++) {
+    const op = ops[k];
+    if (op.t === "-") dels.push({ ...op, adjacent: ops[k + 1] && ops[k + 1].t === "+" ? ops[k + 1] : null });
+    else if (op.t === "+") adds.push(op);
+  }
+  const pairs = [], usedAdd = new Set(), usedDel = new Set();
+  for (const d of dels) {
+    // Adjacency alone is not enough to call two lines the same line rewritten: when a
+    // shell expands the comment block above a setting, the template's last comment line
+    // sits immediately before the shell's new SETTING, and pairing those two would both
+    // mis-report the comment and starve the setting of its real counterpart. Only pair
+    // adjacent lines that agree about being a keyed setting.
+    if (!d.adjacent || usedAdd.has(d.adjacent.j)) continue;
+    if (yamlKey(d.a) !== yamlKey(d.adjacent.b)) continue;
+    pairs.push([d, d.adjacent]); usedAdd.add(d.adjacent.j); usedDel.add(d.i);
+  }
+  for (const d of dels) {
+    if (usedDel.has(d.i)) continue;
+    const key = yamlKey(d.a);
+    if (!key) continue;
+    const a = adds.find((x) => !usedAdd.has(x.j) && yamlKey(x.b) === key);
+    if (a) { pairs.push([d, a]); usedAdd.add(a.j); usedDel.add(d.i); }
+  }
+
+  const out = [];
+  for (const [d, a] of pairs) {
+    if (isPlaceholder(d.a) || markedSetBeforeUse(tLines, d.i)) continue; // filled in / chosen, as intended
+    out.push({ kind: isProse(d.a) && isProse(a.b) ? "prose" : "logic", line: d.i + 1, from: d.a, to: a.b });
+  }
+  for (const d of dels) if (!usedDel.has(d.i)) out.push({ kind: isProse(d.a) ? "prose" : "logic", line: d.i + 1, from: d.a, to: null });
+  for (const a of adds) if (!usedAdd.has(a.j)) out.push({ kind: isProse(a.b) ? "prose" : "logic", line: a.j + 1, from: null, to: a.b });
+  return out.sort((x, y) => x.line - y.line);
+}
+
+const wfDir = path.join(SHELL, ".github", "workflows");
+if (!fs.existsSync(wfDir)) {
+  console.error(`[shell-lint] no .github/workflows/ under ${SHELL} — is this a deploy shell? (pass --shell <path>)`);
+  process.exit(1);
+}
+if (!fs.existsSync(TEMPLATES)) {
+  console.error(`[shell-lint] no templates at ${TEMPLATES} — is the engine submodule checked out? (pass --templates <path>)`);
+  process.exit(1);
+}
+
+const templates = fs.readdirSync(TEMPLATES).filter((f) => f.endsWith(".yml")).sort();
+const installed = fs.readdirSync(wfDir).filter((f) => f.endsWith(".yml")).sort();
+
+let logicDrift = 0, proseDrift = 0;
+const missing = [], extra = [];
+
+for (const f of templates) {
+  if (!installed.includes(f)) { missing.push(f); continue; }
+  const diffs = compare(
+    fs.readFileSync(path.join(TEMPLATES, f), "utf8"),
+    fs.readFileSync(path.join(wfDir, f), "utf8"),
+  );
+  const logic = diffs.filter((d) => d.kind === "logic");
+  const prose = diffs.filter((d) => d.kind === "prose");
+  logicDrift += logic.length;
+  proseDrift += prose.length;
+  if (!diffs.length) { say(`  ok       ${f}`); continue; }
+  const bad = STRICT ? diffs : logic;
+  warn(`  ${bad.length ? "DRIFT   " : "reworded"} ${f}  (${logic.length} logic, ${prose.length} prose)`);
+  for (const d of bad.slice(0, 12)) {
+    warn(`      line ${d.line}:`);
+    if (d.from !== null) warn(`        template: ${d.from.trim().slice(0, 120)}`);
+    if (d.to !== null) warn(`        shell:    ${d.to.trim().slice(0, 120)}`);
+  }
+  if (bad.length > 12) warn(`      … and ${bad.length - 12} more`);
+}
+for (const f of installed) if (!templates.includes(f)) extra.push(f);
+
+say("");
+if (missing.length) warn(`  not installed (this shell's call, not an error): ${missing.join(", ")}`);
+if (extra.length) warn(`  no template (instance-specific, expected): ${extra.join(", ")}`);
+
+const fatal = STRICT ? logicDrift + proseDrift : logicDrift;
+if (fatal) {
+  console.log("");
+  console.error(`::error::shell-lint: ${fatal} line(s) diverge from the engine's templates — a fix in templates/shell/ has not reached this shell, or this shell edited its copy without sending it upstream.`);
+  process.exit(1);
+}
+console.log(`shell-lint: clean — ${templates.length - missing.length} workflow(s) match their template${proseDrift ? ` (${proseDrift} comment line(s) reworded; --strict to fail on those)` : ""}.`);