@augurworks/augur 0.15.3 → 0.15.5

package/agents/README.md

@@ -25,7 +25,9 @@ npx @augurworks/augur connect --origin https://<the workspace>
 ```
 
 It prints one line to relay — *ask the owner of this workspace to open `<link>` and
-enter `<code>`* — and waits. The owner opens the link in a browser they are already
+enter `<code>`* — and waits. If your person reads you through messages rather than a
+terminal, run it with `--no-wait`: it prints the line and exits, and running it again
+after they approve collects the token for that same code. The owner opens the link in a browser they are already
 signed in to and types the code; the token lands in `~/.config/augur/tokens.json`, and
 `augur ship` / `augur publish` use it from then on. `publish` runs the pairing itself when
 it finds no token, so inside a workspace tree nothing has to be done first. On a workspace

package/agents/drafts.md

@@ -78,6 +78,9 @@ you do not want (its saves stay on the instance for a while; nothing else is tou
 |---|---|---|
 | `main-moved` / "sync first" | somebody landed since you opened | `augur sync`, then `augur land` |
 | `stale-draft` | another process saved to this same draft | `augur sync`, then `augur save` |
+| `draft-closed` | somebody landed or discarded this draft from the site (it says who and when) | your edits are still in the folder; `augur open` the prototype again and copy them in |
+| `manifest-contended` | many landings hit the workspace in the same second; `land` already tried again | `augur land` once more |
+| `forbidden` with "run `augur connect` again" | this machine's token was revoked (a role change or a removal) or belongs to another workspace | `augur connect` |
 | `would-unpublish` | the draft has no files (the folder is empty) | check the folder; a deletion is its own verb |
 | `not-a-prototype-folder` / `reserved-folder` | the path is not `<opportunity>/<prototype>` | name the prototype folder |
 | `units-not-configured` | this instance does not serve drafts | `augur publish` — see publishing.md |

package/agents/publishing.md

@@ -229,11 +229,7 @@ them.
 purpose), say so:
 
 ```
-<<<<<<< HEAD
-node ../augur/scripts/publish.mjs --allow-unpublish
-=======
 augur publish --allow-unpublish
->>>>>>> 01da41b5 (npm: the engine speaks as a package — hooks, self-update and every contract)
 ```
 
 Adding pages is never blocked; only losing them is.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@augurworks/augur",
-  "version": "0.15.3",
+  "version": "0.15.5",
   "files": [
     "scripts/",
     "build.js",

package/scripts/connect.mjs

@@ -30,6 +30,28 @@ const ORIGIN = (opt("--origin") || process.env.AUGUR_ORIGIN || resolveOrigin() |
 if (!ORIGIN) die("no origin — pass --origin https://your.site, or set AUGUR_ORIGIN.");
 
 const POLL_MS = 2000;
+// `--no-wait`: print the line to relay and exit at once. For an agent that talks to its
+// person through messages rather than a terminal — a chat, a ticket, a print-mode run —
+// waiting here is a dead end: the person cannot see the code until the command ends, and
+// the command does not end until the person acts. The pairing is kept on this machine, so
+// `augur connect` run again after the approval collects the token, minting no new code.
+const NO_WAIT = argv.includes("--no-wait");
+const PENDING_FILE = path.join(os.homedir(), ".config", "augur", "pairing.json");
+const host = new URL(ORIGIN).host;
+function readPending() {
+  try {
+    const all = JSON.parse(readFileSync(PENDING_FILE, "utf8"));
+    const p = all[host];
+    return p && p.code && p.deviceSecret && Date.parse(p.expiresAt) > Date.now() ? p : null;
+  } catch (e) { return null; }
+}
+function writePending(p) {
+  mkdirSync(path.dirname(PENDING_FILE), { recursive: true });
+  let all = {};
+  try { all = JSON.parse(readFileSync(PENDING_FILE, "utf8")); } catch (e) {}
+  if (p) all[host] = p; else delete all[host];
+  writeFileSync(PENDING_FILE, JSON.stringify(all, null, 2), { mode: 0o600 });
+}
 
 async function post(pathPart, body) {
   const r = await fetch(`${ORIGIN}/__publish/_pair/${pathPart}`, {
@@ -42,7 +64,22 @@ async function post(pathPart, body) {
   return { status: r.status, json };
 }
 
-const start = await post("start");
+// A pairing this machine already started and nobody has collected: ask once whether it
+// was approved meanwhile, and if not, keep waiting on THAT code rather than minting a
+// second one for the same person to type.
+const pending = readPending();
+if (pending) {
+  const res = await post("claim", { code: pending.code, deviceSecret: pending.deviceSecret });
+  if (res.status === 200 && res.json && res.json.token) {
+    writePending(null);
+    finish(res.json);
+  } else if (res.status === 202) {
+    log(`the pairing started earlier is still waiting to be approved.`);
+  } else {
+    writePending(null);
+  }
+}
+const start = readPending() ? { status: 200, json: { ...readPending(), expiresInMs: Date.parse(readPending().expiresAt) - Date.now() } } : await post("start");
 if (start.status === 429) die("too many attempts from here. Wait a few minutes.");
 if (start.status !== 200 || !start.json || !start.json.code) {
   // The routes answer as though they are not there when the instance has not opted in,
@@ -53,8 +90,9 @@ if (start.status !== 200 || !start.json || !start.json.code) {
 }
 
 const { code, deviceSecret, approveUrl, expiresInMs } = start.json;
-const mins = Math.round((expiresInMs || 300000) / 60000);
+const mins = Math.max(1, Math.round((expiresInMs || 300000) / 60000));
 const pretty = code.length === 8 ? `${code.slice(0, 4)}-${code.slice(4)}` : code;
+if (!readPending()) writePending({ code, deviceSecret, approveUrl, startedAt: new Date().toISOString(), expiresAt: new Date(Date.now() + (expiresInMs || 300000)).toISOString() });
 
 // Written to be RELAYED, not read: the usual runner of this command is an agent, which
 // pastes the first line to a person. So the first line is the whole instruction, and it
@@ -68,6 +106,22 @@ console.log(`  The code is good for ${mins} minutes and only for this terminal.
 console.log("");
 console.log(`  ${C.warn}If you did not just run this command, do not approve it.${C.off}`);
 console.log("");
+if (NO_WAIT) {
+  console.log(`  ${C.dim}Not waiting. Once they have approved, run \`augur connect\` again here: it collects the`);
+  console.log(`  token for this same code and mints no new one.${C.off}`);
+  process.exit(0);
+}
+console.log(`  ${C.dim}You can stop waiting (Ctrl-C) and run \`augur connect\` again after they approve —`);
+console.log(`  it collects the token for this same code.${C.off}`);
+console.log("");
+// Addressed to an agent, in the second person, because the polite version above was
+// read and ignored: an agent whose person only sees its messages once it finishes its
+// turn kept polling here for the code's whole life, twice, and nobody ever saw the code.
+console.log(`  ${C.warn}AGENTS: if your person reads your messages only after you finish, do not wait here.`);
+console.log(`  Stop now, send them the first line above, and run \`augur connect\` again once they say`);
+console.log(`  they have approved — it collects the token then. (\`augur connect --no-wait\` does`);
+console.log(`  exactly that in one step.)${C.off}`);
+console.log("");
 
 const deadline = Date.now() + (expiresInMs || 300000);
 let saved = null;
@@ -76,9 +130,13 @@ while (Date.now() < deadline) {
   const res = await post("claim", { code, deviceSecret });
   if (res.status === 200 && res.json && res.json.token) { saved = res.json; break; }
   if (res.status === 202) continue;          // still waiting for somebody to approve
-  if (res.status === 404) die("this pairing is no longer valid. Run `augur connect` again.");
+  if (res.status === 404) { writePending(null); die("this pairing is no longer valid. Run `augur connect` again."); }
 }
-if (!saved) die(`nobody approved it within ${mins} minutes. Run \`augur connect\` again.`);
+if (!saved) { writePending(null); die(`nobody approved it within ${mins} minutes. Run \`augur connect\` again.`); }
+writePending(null);
+finish(saved);
+
+function finish(saved) {
 
 const dir = path.join(os.homedir(), ".config", "augur");
 mkdirSync(dir, { recursive: true });
@@ -100,4 +158,6 @@ if (saved.expiresAt) {
   console.log(`${C.dim}It expires in ${days} days (${saved.expiresAt.slice(0, 10)}). Run \`augur connect\` again then.${C.off}`);
 } else {
   console.log(`${C.dim}It expires on its own. Run \`augur connect\` again when it does.${C.off}`);
+}
+  process.exit(0);
 }

package/scripts/hook.mjs

@@ -63,5 +63,6 @@ const client = unitClient({ origin, token, space: st.space, session: st.session
 const r = await doSave({ client, dir: target.dir });
 if (r.ok) process.exit(0);
 if (r.error === "stale-draft" || r.error === "stale-draft-revision") refuse(`draft ${st.draftId} not saved: it moved under you (another process saved to it) — run augur sync, then augur save.`);
+if (r.error === "draft-closed") refuse(`draft ${st.draftId} not saved: it was ${r.landed ? `landed by ${r.name || r.by || "someone"}${r.session ? ` (${r.session})` : ""} at ${r.at}` : "discarded"} — this folder is no longer a draft. Your edits are still here; run augur open on the prototype again and copy them in.`);
 if (r.error === "network") refuse(`draft ${st.draftId} not saved: ${origin} is unreachable (${r.message}). Nothing is lost — the next save carries every change since.`);
-refuse(`draft ${st.draftId} not saved: ${r.error || r.status}${r.reason ? ` (${r.reason})` : ""}. Fix it and run augur save.`);
+refuse(`draft ${st.draftId} not saved: ${r.error || r.status}${r.reason ? ` (${r.reason})` : ""}${r.message ? ` — ${r.message}` : ""}. Fix it and run augur save.`);

package/scripts/land.mjs

@@ -26,7 +26,10 @@ if (!r.ok) {
     die("run `augur sync` to fold those in, check the draft address, then `augur land` again.");
   }
   if (r.error === "landing-in-progress") die("somebody is landing this prototype right now — try again in a few seconds.");
-  die(`land refused: ${r.error || r.status}`);
+  if (r.error === "manifest-contended") die("the workspace was busy landing other prototypes — nothing changed; run augur land again.");
+  if (r.error === "draft-closed") die(`this draft was ${r.landed ? `landed by ${r.name || r.by || "someone"}${r.session ? ` (${r.session})` : ""} at ${r.at}` : "discarded"} — the folder is no longer a draft. Your edits are still here; run augur open on the prototype again and copy them in.`);
+  if (r.error === "network") die(`could not reach the instance (${r.message}). Nothing is lost — run augur land again.`);
+  die(`land refused: ${r.error || r.status}${r.message ? ` — ${r.message}` : ""}`);
 }
 // The bytes are live; when `recorded` is false only the history entry is missing. Said out
 // loud because the next call adopts that landing as the instance's own, and nobody would

package/scripts/lib/draft.mjs

@@ -11,6 +11,8 @@ import { createHash } from "node:crypto";
 import { merge3 } from "./merge3.mjs";
 
 export const STATE_FILE = ".augur/draft.json";
+/** How many times `land` tries again when the space's manifest is contended. */
+export const LAND_RETRIES = 4;
 export const THEIRS_DIR = ".augur/theirs";
 // The machine-wide registry of open draft folders. `AUGUR_DRAFTS_REGISTRY` exists for the
 // test suite, which must never write into the developer's own home folder.
@@ -111,17 +113,30 @@ export const registryList = () => readRegistry().drafts;
  * `/__unit/<verb>` and blobs at `/__publish/<space>/blob/<hash>`. Non-2xx answers come back
  * as `{status, ...body}` rather than throwing, because a 409 is an answer, not a failure.
  */
+/**
+ * The server answers a token it does not know with a bare `forbidden` and no sentence,
+ * ON PURPOSE — a guessed token must learn nothing. This side knows something the server
+ * will not say: the token it just sent is the one saved on this machine, so a bare
+ * refusal means that token is dead here — revoked by a role change or a removal, or
+ * minted for another workspace — and the way back is to pair again.
+ */
+export const TOKEN_NOT_ACCEPTED = "this machine's publish token is not accepted here — it may have been revoked (a role change or a removal does that), or it belongs to another workspace. Run `augur connect` again.";
+export function explainRefusal(body, status) {
+  if (status === 403 && body && body.error === "forbidden" && !body.message) return { ...body, message: TOKEN_NOT_ACCEPTED };
+  return body;
+}
+
 export function unitClient({ origin, token, space, session }) {
   const headers = { Authorization: `Bearer ${token}`, "X-Augur-Session": session || "" };
   const post = async (verb, body) => {
     const r = await fetch(`${origin}/__unit/${verb}`, { method: "POST", headers: { ...headers, "content-type": "application/json" }, body: JSON.stringify(body) });
     const out = await r.json().catch(() => ({}));
-    return r.ok ? out : { status: r.status, ...out };
+    return r.ok ? out : { status: r.status, ...explainRefusal(out, r.status) };
   };
   const get = async (verb, unit) => {
     const r = await fetch(`${origin}/__unit/${verb}?unit=${encodeURIComponent(unit)}`, { headers });
     const out = await r.json().catch(() => ({}));
-    return r.ok ? out : { status: r.status, ...out };
+    return r.ok ? out : { status: r.status, ...explainRefusal(out, r.status) };
   };
   return {
     open: (b) => post("open", b), save: (b) => post("save", b), land: (b) => post("land", b),
@@ -129,16 +144,31 @@ export function unitClient({ origin, token, space, session }) {
     main: (unit) => get("main", unit),
     async blobPut(h, body) {
       const r = await fetch(`${origin}/__publish/${space}/blob/${h}`, { method: "PUT", headers, body });
-      if (!r.ok && r.status !== 204) throw new Error(`blob upload failed: ${r.status}`);
+      if (!r.ok && r.status !== 204) throw await refusalError("blob upload", r);
     },
     async blobGet(h) {
       const r = await fetch(`${origin}/__publish/${space}/blob/${h}`, { headers });
-      if (!r.ok) throw new Error(`blob fetch failed: ${r.status}`);
+      if (!r.ok) throw await refusalError("blob fetch", r);
       return Buffer.from(await r.arrayBuffer());
     },
   };
 }
 
+/**
+ * A non-2xx answer from the blob routes, carried as an error that REMEMBERS it was an
+ * answer: the status and whatever the server said. `guarded` turns that back into a
+ * result, so a role refusal on an upload reads as the refusal it is — before this, a
+ * viewer's save came back as "unreachable, nothing is lost", which was neither.
+ */
+async function refusalError(what, r) {
+  let body = null;
+  try { body = await r.json(); } catch (e) { /* not JSON */ }
+  const err = new Error(`${what} failed: ${r.status}${body && body.error ? ` ${body.error}` : ""}`);
+  err.status = r.status;
+  err.body = body && typeof body === "object" ? explainRefusal(body, r.status) : null;
+  return err;
+}
+
 // ── the verbs ────────────────────────────────────────────────────────────────
 // `blobPut`/`blobGet` throw on a non-2xx answer, and a raw `fetch` can reject outright
 // (offline, DNS, a dropped connection mid-transfer) — a transient failure anywhere inside
@@ -150,7 +180,15 @@ export function unitClient({ origin, token, space, session }) {
 function guarded(fn) {
   return async (...args) => {
     try { return await fn(...args); }
-    catch (err) { return { ok: false, error: "network", message: String((err && err.message) || err) }; }
+    catch (err) {
+      // An answer the server gave (a status) is a refusal and keeps the server's words;
+      // anything else — DNS, a dropped connection, a thrown fixture — is the network.
+      if (err && err.status) {
+        const body = err.body || {};
+        return { ok: false, status: err.status, error: body.error || "refused", message: body.message || String(err.message), ...(body.reason ? { reason: body.reason } : {}) };
+      }
+      return { ok: false, error: "network", message: String((err && err.message) || err) };
+    }
   };
 }
 
@@ -226,7 +264,17 @@ async function doLandImpl({ client, dir, note }) {
   if (!st) return { ok: false, error: "not-a-draft", dir };
   const saved = await doSave({ client, dir });
   if (!saved.ok) return saved;
-  const r = await client.land({ unit: st.unit, draftId: st.draftId, baseRevision: st.baseRevision, note: note || "" });
+  // Every landing in a space writes the one manifest by compare-and-set, so eight agents
+  // landing eight prototypes in the same second contend on it. The server retries a few
+  // times and then answers `manifest-contended`; that is a moment, not a refusal — the
+  // draft is still open, its lease released — so this side lands again, with a little
+  // jitter, before telling anyone. Measured live: 8 parallel landings, 2 contended.
+  let r;
+  for (let attempt = 0; ; attempt++) {
+    r = await client.land({ unit: st.unit, draftId: st.draftId, baseRevision: st.baseRevision, note: note || "" });
+    if (r.error !== "manifest-contended" || attempt >= LAND_RETRIES) break;
+    await new Promise((res) => setTimeout(res, 150 + Math.random() * 400 * (attempt + 1)));
+  }
   if (r.status) return { ok: false, ...r };
   st.landed = true; st.landedRevision = r.revision;
   writeState(dir, st);

package/scripts/open.mjs

@@ -43,7 +43,8 @@ if (!r.ok) {
   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})` : ""}`);
+  if (r.error === "network") die(`could not reach the instance (${r.message}).`);
+  die(`could not open: ${r.error || r.status}${r.reason ? ` (${r.reason})` : ""}${r.message ? ` — ${r.message}` : ""}`);
 }
 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

package/scripts/read.mjs

@@ -3,7 +3,8 @@
 // under _read/<unit>/ beside the draft folders; files carry no write bit and the deny hook
 // refuses edits there. `augur close` inside it removes it. See docs/drafts-that-land.md §7.
 import path from "node:path";
-import { target } from "./lib/store.mjs";
+import fs from "node:fs";
+import { target, buildStamp } from "./lib/store.mjs";
 import { unitClient, doRead, readDirFor, unitPathFor } from "./lib/draft.mjs";
 import { normUnit } from "../src/unit-core.mjs";
 
@@ -19,12 +20,19 @@ if (!unit) die(`"${raw}" is not a prototype path.`);
 let origin, token;
 try { ({ origin, token } = target({ needToken: true })); } catch (e) { die(e.message); }
 const dir = path.resolve(opt("--dir") || readDirFor(unit));
-const client = unitClient({ origin, token, space: "", session: "" });
+// The blob routes are per space, so the copy needs the space id exactly as `open` does:
+// from a space.json in this folder, else from what the instance says it serves.
+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 client = unitClient({ origin, token, space, session: "" });
 const r = await doRead({ client, unit, dir, origin, now: new Date().toISOString() });
 if (!r.ok) {
   if (r.error === "folder-not-empty") die(`${r.dir} is not empty — pick another folder with --dir.`);
   if (r.error === "units-not-configured") die("this instance does not serve drafts yet (no unit store bound).");
-  die(`could not read: ${r.error || r.status}${r.reason ? ` (${r.reason})` : ""}`);
+  if (r.error === "network") die(`could not reach the instance (${r.message}).`);
+  die(`could not read: ${r.error || r.status}${r.reason ? ` (${r.reason})` : ""}${r.message ? ` — ${r.message}` : ""}`);
 }
 log(`${r.files} file(s) of ${unit} at revision ${r.revision}, read-only`);
 console.log(dir);

package/scripts/save.mjs

@@ -15,7 +15,9 @@ 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.error === "draft-closed") die(`this draft was ${r.landed ? `landed by ${r.name || r.by || "someone"}${r.session ? ` (${r.session})` : ""} at ${r.at}` : "discarded"} — the folder is no longer a draft. Your edits are still here; run augur open on the prototype again and copy them in.`);
+  if (r.error === "network") die(`could not reach the instance (${r.message}). Nothing is lost — the next save carries every change since.`);
+  die(`save refused: ${r.error || r.status}${r.message ? ` — ${r.message}` : ""}`);
 }
 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/sync.mjs

@@ -15,7 +15,9 @@ 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 doSync({ client, dir });
-if (!r.ok) die(`sync refused: ${r.error || r.status}`);
+if (!r.ok && r.error === "draft-closed") die(`this draft was ${r.landed ? `landed by ${r.name || r.by || "someone"}${r.session ? ` (${r.session})` : ""} at ${r.at}` : "discarded"} — the folder is no longer a draft. Your edits are still here; run augur open on the prototype again and copy them in.`);
+if (!r.ok && r.error === "network") die(`could not reach the instance (${r.message}). Nothing is lost — run augur sync again.`);
+if (!r.ok) die(`sync refused: ${r.error || r.status}${r.message ? ` — ${r.message}` : ""}`);
 for (const f of r.taken) log(`took theirs   ${f}`);
 for (const f of r.merged) log(`merged        ${f}`);
 for (const c of r.conflicts) {

package/src/_worker.js

@@ -4803,6 +4803,9 @@ function publishRefusalBody(refusal) {
     "viewer-role": "This account can look around but not publish.",
     "not-an-admin": "This token was minted for an admin and this account is no longer one. Run `augur login` again for a token scoped to what it may still publish.",
   }[refusal];
+  // `unknown-token` and `wrong-space` stay a bare `forbidden` ON PURPOSE: a guessed token
+  // must not learn whether it exists somewhere. The sentence a person needs — pair again —
+  // is said by the CLI, which knows it just used a saved token (scripts/lib/draft.mjs).
   return message ? { error: "forbidden", message } : { error: "forbidden" };
 }
 
@@ -5099,7 +5102,12 @@ function defaultSpaceIdFromManifests(manifests) {
  * rule the commit handler already keeps. `unitSources` records the landing so the old
  * composed publish treats the unit as somebody's work rather than as a fast-forward.
  */
-const UNIT_LANDING_ATTEMPTS = 3;
+// Every landing in a space writes the one manifest by compare-and-set. Three attempts
+// with no pause between them lost 2 of 8 landings made in the same second (measured live,
+// 6 Sep 2026); six attempts with a little jitter between them is what a burst of agents
+// landing at once needs. The CLI lands again on `manifest-contended` as well.
+const UNIT_LANDING_ATTEMPTS = 6;
+const landingBackoff = (attempt) => new Promise((r) => setTimeout(r, 30 + Math.random() * 90 * (attempt + 1)));
 async function writeUnitLanding(tctx, env, spaceId, unit, table, changed, who, now) {
   const bundles = bundlesFor(env, tctx.tenantId);
   const key = `spaces/${spaceId}/manifest.json`;
@@ -5184,7 +5192,7 @@ async function writeUnitLanding(tctx, env, spaceId, unit, table, changed, who, n
     // A store that answers `null` refused the precondition — R2's way of saying the object
     // moved under us. Anything else is a write.
     const wrote = await bundles.put(key, JSON.stringify(out), etag ? { onlyIf: { etagMatches: etag } } : undefined);
-    if (etag && wrote === null) { bustManifests(tctx.tenantId); continue; }
+    if (etag && wrote === null) { bustManifests(tctx.tenantId); await landingBackoff(attempt); continue; }
     // THE BYTES ARE LIVE FROM HERE: the manifest is the pointer visitors follow. The version
     // document is the rollback record, and a store failure writing it must not turn a landing
     // that already happened into a reported failure with no lease release — it is logged as
@@ -5275,6 +5283,12 @@ async function unitCaller(tctx, request, env, spaceId) {
   return { who: { personId: personId(me.email), label: me.email }, session: session || "browser" };
 }
 
+/** A `draft-closed` answer names who landed it by id; the roster puts the face on it. */
+function closedFace(tctx, body) {
+  if (!body || body.error !== "draft-closed" || !body.by) return body;
+  return { ...body, ...personFace(tctx.USERS, body.by) };
+}
+
 async function unitApi(tctx, request, url, env) {
   const verb = url.pathname.slice(UNIT_API_PREFIX.length);
   if (!/^[a-z-]+$/.test(verb)) return jsonResponse({ error: "bad-path" }, 400);
@@ -5399,13 +5413,13 @@ async function unitApi(tctx, request, url, env) {
     }
     if (missing.length) return jsonResponse({ error: "missing-blobs", missing: [...new Set(missing)] }, 409);
     const r = await unitCall(stub, "/save", { draftId: body.draftId, draftRevision: body.draftRevision, changes, baseRevision: body.baseRevision, at: now });
-    return jsonResponse(r.body, r.status);
+    return jsonResponse(closedFace(tctx, r.body), r.status);
   }
   if (verb === "land" || verb === "restore") {
     const r = await unitCall(stub, `/${verb}`, verb === "land"
       ? { draftId: body.draftId, baseRevision: body.baseRevision, at: now }
       : { revision: body.revision, at: now });
-    if (r.status !== 200) return jsonResponse(r.body, r.status);
+    if (r.status !== 200) return jsonResponse(closedFace(tctx, r.body), r.status);
     const written = await writeUnitLanding(tctx, env, spaceId, unit, r.body.table, r.body.changed, who, now);
     if (written.error) {
       await unitCall(stub, "/abandon-land", { lease: r.body.lease });
@@ -5444,7 +5458,7 @@ async function unitApi(tctx, request, url, env) {
   if (verb === "sync" || verb === "discard") {
     const r = await unitCall(stub, `/${verb}`, { draftId: body.draftId, at: now });
     if (verb === "discard" && r.status === 200) await noteUnitDrafts(tctx, env, stub, unit, now);
-    return jsonResponse(r.body, r.status);
+    return jsonResponse(closedFace(tctx, r.body), r.status);
   }
   return jsonResponse({ error: "unknown-verb" }, 404);
 }
@@ -9119,7 +9133,13 @@ function doorText(f) {
       + `  ${f.connect}\n\n`
       + `It prints a link and a code. The owner of this workspace opens the link in a\n`
       + `browser they are already signed in to and enters the code. The token lands on\n`
-      + `that machine, and every verb below uses it from then on. With no\n`
+      + `that machine, and every verb below uses it from then on.\n\n`
+      + `AGENTS: if your person reads your messages only after you finish your turn, run\n`
+      + `it with --no-wait. It prints the line and exits; send them that line, end your\n`
+      + `turn, and run the same command again once they say they approved — the token is\n`
+      + `collected then, for that same code. Do not poll for the approval in one turn:\n`
+      + `the code lives five minutes and nobody sees it until you stop.\n\n`
+      + `With no\n`
       + `source tree yet, \`npx @augurworks/augur clone --space ${f.workspace}\` then fetches one (it reads\n`
       + `the origin from the pairing).\n\n`
     : `Device pairing is switched off on this workspace. Ask an admin for an invite;\n`

package/src/unit-object.mjs

@@ -109,6 +109,24 @@ export class UnitObject {
     const rows = [...this.sql.exec(`SELECT * FROM drafts WHERE id = ?`, id)];
     return rows.length ? rowDraft(rows[0]) : null;
   }
+  /**
+   * A verb on a draft that no longer exists as a draft. A draft nobody ever opened is
+   * `unknown-draft`; one that was CLOSED answers `draft-closed` and says how — landed
+   * (with who landed it, from the landing row it produced) or discarded — because the
+   * one process that asks is the owner's terminal, which was not told: any member may
+   * land or discard any draft from the bar, and the owner's next save is where they
+   * find out. A bare 404 there read as "nothing to do"; this reads as what happened.
+   */
+  closedAnswer(d) {
+    if (!d) return [404, { error: "unknown-draft" }];
+    const landed = !d.discarded;
+    let by = null, session = null, at = d.closedAt, revision = null;
+    if (landed) {
+      const rows = [...this.sql.exec(`SELECT by, session, at, revision FROM landings WHERE draft_id = ? ORDER BY revision DESC LIMIT 1`, d.id)];
+      if (rows.length) ({ by, session, at, revision } = rows[0]);
+    }
+    return [410, { error: "draft-closed", draftId: d.id, landed, discarded: !landed, by, session, at, revision }];
+  }
   openDrafts() {
     return [...this.sql.exec(`SELECT * FROM drafts WHERE closed_at IS NULL ORDER BY opened_at`)].map(rowDraft);
   }
@@ -150,7 +168,7 @@ export class UnitObject {
 
   save({ draftId, draftRevision, changes, baseRevision, at }) {
     const d = this.draft(draftId);
-    if (!d || d.closedAt) return [404, { error: "unknown-draft" }];
+    if (!d || d.closedAt) return this.closedAnswer(d);
     const held = this.lease(Date.parse(at));
     if (held && held.draftId === draftId) return [409, { error: "landing-in-progress" }];
     if (Number(draftRevision) !== d.revision) return [409, { error: "stale-draft-revision", draftRevision: d.revision }];
@@ -185,7 +203,7 @@ export class UnitObject {
 
   land({ draftId, baseRevision, at }) {
     const d = this.draft(draftId);
-    if (!d || d.closedAt) return [404, { error: "unknown-draft" }];
+    if (!d || d.closedAt) return this.closedAnswer(d);
     const main = this.mainRevision();
     if (d.baseRevision !== main || Number(baseRevision) !== main) {
       const base = this.landing(d.baseRevision);
@@ -230,7 +248,7 @@ export class UnitObject {
 
   sync({ draftId }) {
     const d = this.draft(draftId);
-    if (!d || d.closedAt) return [404, { error: "unknown-draft" }];
+    if (!d || d.closedAt) return this.closedAnswer(d);
     const base = this.landing(d.baseRevision);
     const delta = tableDelta(base ? JSON.parse(base.tbl) : {}, this.mainTable());
     return [200, { mainRevision: this.mainRevision(), baseRevision: d.baseRevision, ...delta }];
@@ -238,7 +256,7 @@ export class UnitObject {
 
   discard({ draftId, at }) {
     const d = this.draft(draftId);
-    if (!d || d.closedAt) return [404, { error: "unknown-draft" }];
+    if (!d || d.closedAt) return this.closedAnswer(d);
     this.sql.exec(`UPDATE drafts SET closed_at = ?, discarded = 1 WHERE id = ?`, at, draftId);
     return [200, { closed: true }];
   }