clearotron 0.3.1-beta.2 → 0.3.1-beta.4

package/scripts/deprecate-below.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// deprecate-below.mjs — put one warning on every published version below a named stable.
+//
+//   node scripts/deprecate-below.mjs --below 0.3.1 [--dry-run]
+//
+// ── WHY THIS IS A SCRIPT IN CI AND NOT SOMETHING A PERSON RUNS ──────────────────────────────────────
+//
+// Nobody on a development box can do it: the publish credential lives only in CI, `npm whoami` is 401
+// there by design, and that design is not something to work around. So the work is a script, and the way
+// a person asks for it is a workflow dispatch.
+//
+// ── WHAT IT REFUSES, AND WHY EACH REFUSAL IS CHEAPER THAN THE MISTAKE ───────────────────────────────
+//
+// `npm deprecate` takes a RANGE, and a range is the dangerous part: `npm deprecate pkg "<1.0.0"` is one
+// command that can warn every version a project ever shipped, and the undo is another command per
+// version. So no range reaches npm from here. The versions are enumerated, compared one at a time, and
+// deprecated one at a time, which is slower and is the point.
+//
+// THE NAMED STABLE IS NEVER TOUCHED, nor is anything above it. A message telling a reader to upgrade to
+// the version they are already on is worse than no message: it reads as a defect in the version they
+// just chose.
+//
+// ALREADY-DEPRECATED VERSIONS ARE LEFT ALONE. Re-deprecating replaces one message with another, and the
+// existing one may be more specific than this one — a security note, say.
+//
+// ── THE READ-BACK IS PER VERSION, AND THAT IS NOT A STYLE CHOICE ────────────────────────────────────
+//
+// `npm view <pkg> deprecated --json` over a range returns a value whose SHAPE depends on how many
+// versions matched: a string for one, an object keyed by version for several, and nothing at all for
+// none. Reading that as a map is how a verification passes over versions it never checked. So each
+// version is read back on its own, by its own exact spec, and the answer is a string or it is absent.
+import { execFileSync } from "node:child_process";
+
+const PKG = "clearotron";
+
+// NOTHING HAPPENS AT IMPORT. The argument parsing and its refusal used to sit here at the top, so
+// importing this module to test its comparison ran the refusal and exited 2 before a single arm ran. A
+// CLI module that does work when required is the same defect this repository has met with a top-level
+// await, and the same fix: the body belongs in `main`, and `main` runs only from the entry check.
+
+/** Compare two semver-ish versions. A pre-release sorts BELOW its own release, which is what npm means. */
+export function compareVersions(a, b) {
+  const split = (v) => {
+    const [core, pre = ""] = String(v).split("-");
+    return { nums: core.split(".").map((n) => Number(n) || 0), pre };
+  };
+  const A = split(a), B = split(b);
+  for (let i = 0; i < 3; i++) {
+    if ((A.nums[i] ?? 0) !== (B.nums[i] ?? 0)) return (A.nums[i] ?? 0) < (B.nums[i] ?? 0) ? -1 : 1;
+  }
+  // Same core. No pre-release outranks any pre-release; two pre-releases compare as text, which is
+  // right for `beta.2` against `beta.10` only up to ten — so the identifiers are compared numerically
+  // where they are numbers.
+  if (A.pre === B.pre) return 0;
+  if (!A.pre) return 1;
+  if (!B.pre) return -1;
+  const ap = A.pre.split("."), bp = B.pre.split(".");
+  for (let i = 0; i < Math.max(ap.length, bp.length); i++) {
+    const x = ap[i], y = bp[i];
+    if (x === y) continue;
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    const nx = Number(x), ny = Number(y);
+    if (Number.isInteger(nx) && Number.isInteger(ny)) return nx < ny ? -1 : 1;
+    return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+const npm = (...args) => execFileSync("npm", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+
+/** Every published version, and the deprecation message each carries. Read once, as a list. */
+function published() {
+  const versions = JSON.parse(npm("view", PKG, "versions", "--json"));
+  return Array.isArray(versions) ? versions : [versions];
+}
+
+/** One version's deprecation message, read by its own exact spec. Null when it carries none. */
+function deprecationOf(version) {
+  // `--json` on a field that is absent prints nothing at all, which JSON.parse refuses. An empty read is
+  // "this version carries no message", and it is a different fact from a read that failed — so a failure
+  // throws and a caller decides, rather than being folded into "not deprecated".
+  const out = npm("view", `${PKG}@${version}`, "deprecated", "--json").trim();
+  if (!out) return null;
+  const v = JSON.parse(out);
+  return typeof v === "string" && v.trim() ? v : null;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const at = (flag) => { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : null; };
+  const DRY = argv.includes("--dry-run");
+  const below = at("--below");
+  if (!below) {
+    console.error("deprecate-below: --below <version> is required — the stable everything under it points at.");
+    return 2;
+  }
+  const MESSAGE = `This version is superseded. Please upgrade to ${below} or later: npm install ${PKG}@${below}`;
+
+  const all = published();
+  if (!all.length) {
+    console.error("deprecate-below: the registry listed no versions — refusing rather than reporting zero to deprecate.");
+    return 2;
+  }
+  if (!all.includes(below)) {
+    console.error(`deprecate-below: ${below} is not a published version of ${PKG}. `
+      + "Refusing: pointing readers at a version that does not exist is worse than leaving them unwarned.");
+    return 2;
+  }
+
+  const candidates = all.filter((v) => compareVersions(v, below) < 0);
+  console.log(`deprecate-below: ${all.length} published version(s); ${candidates.length} below ${below}.`);
+
+  let done = 0, skipped = 0, failed = 0;
+  for (const v of candidates) {
+    let existing;
+    try { existing = deprecationOf(v); }
+    catch (e) {
+      console.error(`  ${v}: could NOT be read (${String(e.message).split("\n")[0]}) — left alone.`);
+      failed += 1;
+      continue;
+    }
+    if (existing) { console.log(`  ${v}: already deprecated — left alone ("${existing.slice(0, 60)}")`); skipped += 1; continue; }
+    if (DRY) { console.log(`  ${v}: would deprecate`); done += 1; continue; }
+    try {
+      npm("deprecate", `${PKG}@${v}`, MESSAGE);
+    } catch (e) {
+      console.error(`  ${v}: deprecate FAILED — ${String(e.stderr ?? e.message).split("\n")[0]}`);
+      failed += 1;
+      continue;
+    }
+    // READ BACK, PER VERSION, and report what the registry says rather than that the command exited 0.
+    let now = null;
+    try { now = deprecationOf(v); } catch { now = null; }
+    if (now) { console.log(`  ${v}: deprecated — registry reads back "${now.slice(0, 60)}"`); done += 1; }
+    else { console.error(`  ${v}: deprecate reported success and the registry reads back NOTHING.`); failed += 1; }
+  }
+
+  console.log(`deprecate-below: ${done} deprecated, ${skipped} already carried a message, ${failed} failed.`);
+  return failed ? 1 : 0;
+}
+
+if (process.argv[1] && process.argv[1].endsWith("deprecate-below.mjs")) process.exit(main());

package/scripts/test-run.mjs

@@ -93,6 +93,24 @@ const PREFIX = "ct-testrun-";
 // inside its parent's root, or the parent's cleanup removes a live child's fixtures.
 const REAL_TMP = process.env.CT_TEST_TMP_BASE || tmpdir();
 
+// ── THE MACHINE'S OWN TEMP ROOT, WHICH IS NOT THE SAME QUESTION AS `REAL_TMP` ──────────────────────
+//
+// `REAL_TMP` answers "where does THIS run put its root", and a caller may redirect it — the runner's own
+// tests do, giving each case a sandbox base so they never read or write the real temp directory. That is
+// correct for rooting and wrong for CONTAINMENT: redirecting it also removed the machine's temp
+// directory from the containment list, and a nested run was then refused for being pointed at a sibling
+// temp root that is perfectly contained.
+//
+// IT ONLY EVER WORKED BY WAY OF THE LITERAL `/tmp`. In CI `TMPDIR` is unset, every root is under `/tmp`,
+// and the literal in `PLATFORM_TMP` below covered the sibling. On a box whose temp directory is anywhere
+// else — this one exports `TMPDIR=/mnt/datadisk1/tmp` — nothing in the list covered it, so ten arms that
+// drive the runner recursively failed here and passed in CI on the same commit. The guard was not
+// protecting a differently-rooted box at all; it was refusing it.
+//
+// So this is read ONCE, at the outermost run, before `TMPDIR` is rewritten, and passed down untouched.
+// A caller's sandbox base does not displace it, because it is not answering that caller's question.
+const MACHINE_TMP = String(process.env.CT_TEST_MACHINE_TMP ?? "").trim() || tmpdir();
+
 // A run killed with SIGKILL (or a machine that reboots) never reaches its own cleanup and leaves one
 // directory behind. One per killed run is a tractable number, but it should not accumulate forever, so
 // each run clears the abandoned roots of previous ones. Bounded three ways: the exact prefix we own, an
@@ -372,7 +390,7 @@ const DATA_PLANE_VARS = Object.freeze([
 // or /srv, never a temp filesystem.
 const PLATFORM_TMP = process.platform === "win32" ? [] : ["/tmp"];
 const CONTAINMENT_ROOTS = Object.freeze([...new Set(
-  [REAL_TMP, tmpdir(), ...PLATFORM_TMP].map((p) => resolve(p)),
+  [REAL_TMP, MACHINE_TMP, tmpdir(), ...PLATFORM_TMP].map((p) => resolve(p)),
 )]);
 const isContained = (value) => {
   const p = resolve(value);
@@ -689,6 +707,11 @@ child = spawn(argv[0], argv.slice(1), {
     // the one the top of this file reads before TMPDIR is rewritten, so the chain stays anchored to the
     // real temp directory however deep the nesting goes. A caller's own value wins, as everywhere else.
     CT_TEST_TMP_BASE: String(process.env.CT_TEST_TMP_BASE ?? "").trim() || REAL_TMP,
+    // AND THE MACHINE'S TEMP ROOT, carried down unchanged however deep the nesting goes. Unlike the line
+    // above it this one is NOT a caller's to redirect: a caller redirecting where a run roots itself is
+    // saying nothing about which filesystem locations count as temporary, and conflating the two is what
+    // made a correctly contained sibling read as somebody's live estate.
+    CT_TEST_MACHINE_TMP: MACHINE_TMP,
     TRADEMARK_MCP_AUDIT_LOG: String(process.env.TRADEMARK_MCP_AUDIT_LOG ?? "").trim()
       || join(root, "mcp-access.jsonl"),
     // AND THE PORTAL'S AUDIT LOG, for the same reason and by the same rule as the line above it.

package/shared/connect-clients.mjs

@@ -105,9 +105,11 @@ const BRIEF = "ask it to brief you on your clearances.";
 export const DOOR_KINDS = Object.freeze(["sign-in", "key"]);
 const SIGNIN_HINT = "No key: this connector signs you in through your browser, and the sign-in is the "
   + "authentication your assistant is asking about.";
-const UNKNOWN_DOOR_HINT = "This deployment's connector could not be read just now, so both ways are "
-  + "shown: sign-in is what a hosted connector answers, a key is what a self-hosted one takes. Try the "
-  + "sign-in first — an assistant that needs a key will say so.";
+// THE UNKNOWN DOOR IS THE PAGE'S SENTENCE NOW, NOT A STEP HINT. This hint said "both ways are shown"
+// while one set was drawn — a promise the page could not keep — and it said it in the words that screen
+// is not allowed to show a reader. The panel states it once, above both lists, and the lists make it
+// true. A hint under step one repeating it would be the same sentence twice, the second time in
+// vocabulary the reader did not ask for.
 
 /**
  * Every app we can speak to, and the steps for each route. Adding one is a row.
@@ -159,7 +161,7 @@ export const CONNECT_CLIENTS = Object.freeze([
         ] : [
           // THE SIGN-IN DOOR. No key is minted and no header is set: the warning the old steps told the
           // reader to ignore IS the sign-in, and following it is the whole of the connection.
-          { text: "Copy the address.", copy: "address", hint: door === null ? UNKNOWN_DOOR_HINT : SIGNIN_HINT },
+          { text: "Copy the address.", copy: "address", hint: door === null ? undefined : SIGNIN_HINT },
           { text: "In Claude, open **Settings → Connectors → Add custom connector**." },
           { text: "Paste the address and press **Add**." },
           { text: `Sign in when the browser opens — use ${operator ?? "your work email"}.` },
@@ -185,7 +187,7 @@ export const CONNECT_CLIENTS = Object.freeze([
           { text: `Start Claude Code and ${BRIEF}`, hint: CHECK_HINT },
         ] : [
           // The command carries no header, because a door that signs its reader in never honours one.
-          { text: "Copy this command.", copy: "claude-cli-http-signin", hint: door === null ? UNKNOWN_DOOR_HINT : SIGNIN_HINT },
+          { text: "Copy this command.", copy: "claude-cli-http-signin", hint: door === null ? undefined : SIGNIN_HINT },
           { text: "Paste it into a terminal and press Enter." },
           { text: "Sign in when the browser opens." },
           { text: `Start Claude Code and ${BRIEF}`, hint: CHECK_HINT },
@@ -220,7 +222,7 @@ export const CONNECT_CLIENTS = Object.freeze([
           { text: "Add a custom connector and paste the address." },
           { text: "Give the key as the connector's bearer token — the second line." },
         ] : [
-          { text: "Copy the address.", copy: "address", hint: door === null ? UNKNOWN_DOOR_HINT : undefined },
+          { text: "Copy the address.", copy: "address", hint: undefined },
           { text: "In ChatGPT on the web, turn on **Settings → Security and login → Developer mode**.",
             hint: "Needs a Plus, Pro, Business, Enterprise or Edu plan. On a company plan, your admin may have to allow it." },
           { text: "Add a custom connector and paste the address." },
@@ -252,7 +254,7 @@ export const CONNECT_CLIENTS = Object.freeze([
             hint: "Codex reads the key from there, so it never sits in the settings file." },
           { text: `Restart Codex and ${BRIEF}` },
         ] : [
-          { text: "Copy this.", copy: "codex-toml-http-signin", hint: door === null ? UNKNOWN_DOOR_HINT : SIGNIN_HINT },
+          { text: "Copy this.", copy: "codex-toml-http-signin", hint: door === null ? undefined : SIGNIN_HINT },
           { text: "Open `~/.codex/config.toml` and paste it at the end." },
           // ITS OWN STEP, not a hint on the one before it. The sign-in IS the connection here, and a
           // reader skimming numbered steps does not read the small print under one of them.
@@ -282,7 +284,7 @@ export const CONNECT_CLIENTS = Object.freeze([
           { text: "Paste the address and the key wherever your app adds a custom MCP server.",
             hint: "It may call them “server URL” and “bearer token”." },
         ] : [
-          { text: "Copy the address.", copy: "address", hint: door === null ? UNKNOWN_DOOR_HINT : SIGNIN_HINT },
+          { text: "Copy the address.", copy: "address", hint: door === null ? undefined : SIGNIN_HINT },
           { text: "Paste it wherever your app adds a custom MCP server, and sign in when the browser opens.",
             hint: "It may call the address the “server URL”. There is no token to give it." },
         ]),
@@ -311,14 +313,24 @@ export const offersForWire = (offers) =>
     id: client.id,
     name: client.name,
     ...(client.sub ? { sub: client.sub } : {}),
-    steps: (Array.isArray(steps) ? steps : []).map((s) => ({
-      text: s.text,
-      ...(s.hint ? { hint: s.hint } : {}),
-      ...(s.copy ? { copy: s.copy.kind === "secret"
-        ? { kind: "secret", label: s.copy.label, template: s.copy.template, slot: s.copy.slot }
-        : { kind: "block", text: s.copy.text } } : {}),
-    })),
+    steps: stepsForWire(steps),
     ...rest,
+    // THE ALTERNATIVE TRAVELS, AND SO DOES THE FACT THAT THE DOOR IS UNKNOWN. `...rest` carried neither:
+    // `altSteps` needs the same copy-shape mapping the primary set gets, and `door` was dropped on the
+    // floor, so the page had nothing to branch on and drew one set of steps as though the door had been
+    // read. Both are stated after the spread so a row cannot pass its own raw shape through.
+    ...(Array.isArray(rest.altSteps) ? { altSteps: stepsForWire(rest.altSteps) } : {}),
+    ...(Object.hasOwn(rest, "door") ? { door: rest.door ?? null } : {}),
+  }));
+
+/** One route's steps, in the shape the browser reads. The alternative set gets the same mapping. */
+const stepsForWire = (steps) =>
+  (Array.isArray(steps) ? steps : []).map((s) => ({
+    text: s.text,
+    ...(s.hint ? { hint: s.hint } : {}),
+    ...(s.copy ? { copy: s.copy.kind === "secret"
+      ? { kind: "secret", label: s.copy.label, template: s.copy.template, slot: s.copy.slot }
+      : { kind: "block", text: s.copy.text } } : {}),
   }));
 
 const ALIAS_ROUTE = new Map(CONNECT_CLIENTS.flatMap((c) =>
@@ -395,6 +407,30 @@ export function whatItNeeds(client, have = {}, route = client?.lead) {
   const asked = author.steps({ operator, door: route === "public-http" ? door : null });
   const steps = asked.map((s) => (s.copy ? { ...s, copy: resolve(s.copy) } : { ...s }));
   const resolved = steps.every((s, i) => !asked[i].copy || s.copy);
+
+  // ── WHEN THE DOOR COULD NOT BE READ, BOTH WAYS ARE ACTUALLY SHOWN ────────────────────────────────
+  //
+  // `doorKind` returns null for "not known" and its own contract says the caller offers both rather than
+  // guessing. The steps above already carry the sentence that says so — and it reads "both ways are
+  // shown" while one set was rendered. A page that promises the reader the alternative and then does not
+  // draw it is worse than one that never mentioned it: the reader goes looking for what they were told
+  // is there.
+  //
+  // So the OTHER door's steps are composed here and ride beside them. The sign-in set leads, because
+  // that is what every hosted connector answers and what the hint tells the reader to try first; the key
+  // set is the alternative rather than a second equal choice. Composed by asking the same author with
+  // the other answer, never by a second copy of the steps — one table, one author, as everything else in
+  // this file.
+  const altAsked = route === "public-http" && door === null
+    ? author.steps({ operator, door: "key" })
+    : null;
+  const altSteps = altAsked
+    ? altAsked.map((s) => (s.copy ? { ...s, copy: resolve(s.copy) } : { ...s }))
+    : null;
+  // A step whose copy this deployment cannot produce is not offered at all — the same rule the primary
+  // set follows two lines up. Half an alternative is a reader following steps that stop.
+  const altResolved = !altAsked || altSteps.every((s, i) => !altAsked[i].copy || s.copy);
+  const alt = altResolved && altSteps?.length ? { door: null, altSteps } : { ...(route === "public-http" ? { door } : {}) };
   const evidence = { ...(author.verifiedOn ? { verifiedOn: author.verifiedOn } : {}), ...(author.by ? { by: author.by } : {}) };
 
   if (route === "disk") {
@@ -431,7 +467,7 @@ export function whatItNeeds(client, have = {}, route = client?.lead) {
       fix: "whoever installed it can put it online — it takes about a minute and needs no account",
       operatorFix: "put it online and set CLEAROTRON_CLIENT_MCP_URL to the public URL of this install — INSTALL.md §7 walks the tunnel" };
   }
-  return { client, served: true, route, steps, launch: client.launch ?? null, enables: null, ...evidence,
+  return { client, served: true, route, steps, ...alt, launch: client.launch ?? null, enables: null, ...evidence,
     command: null, stdio: null, address: publicAddress, key: "issued",
     note: "This assistant connects through its maker's service, so it reaches this installation at its web address rather than from your machine." };
 }

package/shared/driver-dir.mjs

@@ -35,7 +35,7 @@
 // its own population needs an exception list — which would rebuild this issue's defect inside its fix:
 //
 //   · `driver/stage-freshness.mjs` creates a CHILD, `join(runDir, "_driver", STAMP_DIR)`.
-//   · `driver/pipeline.mjs:15053` passes a shadow dispatch sandbox under `_experiments/`, not a run
+//   · `driver/pipeline.mjs:15755 shadowDir` passes a shadow dispatch sandbox under `_experiments/`, not a run
 //     directory. It is a run-dir-SHAPED base, which is why the parameter is `base` and not `runDir`.
 //
 // ── WHAT THIS DELIBERATELY DOES NOT DO ────────────────────────────────────────────────────────────

package/shared/grants-edit.mjs

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
-// grants-edit.mjs — the changes a person makes to the grants file: give someone access, and file a new
-// company under its organisation.
+// grants-edit.mjs — the changes a person makes to the grants file: give someone access, take access
+// away, and file a new company under its organisation.
 //
 // PURE. Each function takes the parsed grants object and returns a new one; the caller reads the file,
 // applies the change and writes it atomically. One function per change, shared by every writer — the
@@ -47,6 +47,103 @@ export function withPerson(grants, { email, points = [], switches = {}, setSwitc
   return g;
 }
 
+/**
+ * What a person holds now, read straight out of the file: `{ points, switches, listed }`.
+ *
+ * The form that changes somebody has to open filled in, and "filled in" means the file's own answer, not
+ * the page's copy of it. `points` are the same `[{ tenant, account }]` shape `withPerson` takes, so a
+ * caller can diff what it was handed against what is there and hand each half to the right function.
+ *
+ * ADDRESSES ARE MATCHED WITHOUT REGARD TO CASE, in both places a person can appear. Every writer in this
+ * module lowercases on the way in, but the grants file is one an operator edits by hand, and a file
+ * holding `Dana@x.example` under `people` and `dana@x.example` under a tenant is a file this product
+ * loads and serves. A reader that matched exactly would report half of such a person and miss the half
+ * carrying their permissions.
+ */
+export function personPoints(grants, email) {
+  const e = String(email ?? "").trim().toLowerCase();
+  const g = grants ?? {};
+  const points = [];
+  for (const [tenant, t] of Object.entries(g.tenants ?? {})) {
+    const key = Object.keys(t?.users ?? {}).find((k) => String(k).toLowerCase() === e);
+    if (key === undefined) continue;
+    const held = t.users[key];
+    if (held === "*") { points.push({ tenant, account: null }); continue; }
+    for (const account of Array.isArray(held) ? held : []) points.push({ tenant, account });
+  }
+  const entry = Object.entries(g.people ?? {}).find(([k]) => String(k).toLowerCase() === e)?.[1];
+  return {
+    points,
+    switches: { run: entry?.run === true, manage: entry?.manage === true, everything: entry?.everything === true },
+    listed: entry !== undefined,
+  };
+}
+
+/**
+ * Take access away — the other half of `withPerson`, and deliberately its neighbour: one file decides what
+ * a person IS, so the page and `clearotron grant` cannot drift into two answers.
+ *
+ * Two shapes, and the difference is the whole of the safety here.
+ *
+ * `all: true` removes the person from the install: every tenant's guest list AND their entry under
+ * `people`, which is where their permissions and any access to everything live.
+ *
+ * `points` NARROWS instead, and never touches `people`. That restraint is the point: a manager who holds
+ * one organisation can see only that organisation's half of somebody, so a narrowing they order must not
+ * reach an entry they cannot read. It also means a narrowing CANNOT be honest about a person who holds
+ * everything — that access does not live in any tenant, so striking tenant rows would leave them seeing
+ * exactly what they saw before, under a sentence saying otherwise. That case is refused rather than
+ * warned about: a warning printed after the write is read by whoever is already looking.
+ *
+ * A company inside an organisation the person holds WHOLE is refused too. `"*"` means "this organisation,
+ * including companies added later", and the nearest expressible narrowing — today's list of companies,
+ * minus one — is a different grant wearing the same shape. The caller offers the organisation instead.
+ */
+export function withoutPerson(grants, { email, points = [], all = false }) {
+  const e = String(email ?? "").trim().toLowerCase();
+  if (!e) throw new Error("removing access needs an email address");
+  const g = structuredClone(grants ?? { tenants: {} });
+  g.tenants ??= {};
+  const held = personPoints(g, e);
+  if (!all && !points.length) throw new Error("nothing was named to take away");
+  if (!all && held.switches.everything)
+    throw new Error(`${e} has access to everything on this install, which is not held in any organisation`
+      + " — taking away one organisation would change nothing they can see. Remove them from the install instead.");
+
+  const userKeyIn = (t) => Object.keys(t?.users ?? {}).find((k) => String(k).toLowerCase() === e);
+
+  if (all) {
+    for (const t of Object.values(g.tenants)) {
+      const key = userKeyIn(t);
+      // AN EMPTY `users` MAP IS NOT A DELETED TENANT. The organisation still exists and still holds its
+      // companies; it simply has nobody on its guest list.
+      if (key !== undefined) { t.users = { ...t.users }; delete t.users[key]; }
+    }
+    const peopleKey = Object.keys(g.people ?? {}).find((k) => String(k).toLowerCase() === e);
+    if (peopleKey !== undefined) { g.people = { ...g.people }; delete g.people[peopleKey]; }
+    assertGrantsShape(g, "the grants file after this change");
+    return g;
+  }
+
+  for (const { tenant, account = null } of points) {
+    const t = g.tenants[tenant];
+    if (!t) throw new Error(`there is no organisation "${tenant}"`);
+    const key = userKeyIn(t);
+    if (key === undefined) continue;
+    const have = t.users[key];
+    t.users = { ...t.users };
+    if (account == null) { delete t.users[key]; continue; }
+    if (have === "*")
+      throw new Error(`${e} holds the whole of "${tenant}", including companies added to it later,`
+        + ` so "${account}" cannot be taken away on its own. Take away the organisation instead.`);
+    const left = (Array.isArray(have) ? have : []).filter((a) => a !== account);
+    if (left.length) t.users[key] = left;
+    else delete t.users[key];
+  }
+  assertGrantsShape(g, "the grants file after this change");
+  return g;
+}
+
 /** File a company under the organisation that holds it. A company belongs to exactly one organisation. */
 export function withCompany(grants, { tenant, account }) {
   const g = structuredClone(grants ?? { tenants: {} });