clearotron 0.3.1-beta.3 → 0.3.1

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/release-approve-parked.mjs

@@ -0,0 +1,151 @@
+#!/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
+//
+// release-approve-parked.mjs — approve the version pull request's parked CI run, so a cut does not wait
+// on a person.
+//
+// WHY A PERSON HAS BEEN CLICKING. The version pull request is authored by the repository's own Actions
+// bot, and a run triggered by a bot-authored pull request arrives `action_required`. Measured across the
+// last forty `pull_request` CI runs: every parked one is on the version branch and no human-authored
+// branch parks, so the thing that distinguishes them is the author, not a repository setting. The
+// approval endpoint works on such a run — proved against a live parked run, which moved from
+// `action_required` to `queued` — even though its documentation names fork pull requests only.
+//
+// AND WHY IT NEEDS A TOKEN RATHER THAN THE BUILT-IN ONE. `GITHUB_TOKEN` cannot approve a workflow run;
+// GitHub blocks self-approval deliberately. So this reads a separate token with Actions read and write.
+//
+// WHAT THAT PERMISSION ACTUALLY BUYS, stated because the next person deciding whether to reuse this
+// secret will read this sentence and not the permission page. Actions write is not "approve runs": it
+// also creates workflow_dispatch events, cancels any run in the repository, and deletes run logs. This
+// workflow carries `workflow_dispatch`, so the token can reach a PUBLISH by the same door a person
+// uses. It cannot push code, open or merge a pull request, or authenticate to the registry — the
+// publish credential is minted per run from this workflow's OIDC token and stored nowhere. So the
+// boundary is real but it is not "it can only do what this script does".
+//
+// IT NEVER FAILS THE CUT. No token, no parked run, an API that refuses — each prints what happened and
+// exits 0, because the cut's own wait still ends the way it always did: a person clicks, or the wait
+// expires. A step that could turn a green cut red in order to save a click would be a worse trade than
+// the click.
+//
+// BY SHA, AND ONLY THE CURRENT ONE. Approving a STALE parked run cancels the live one — CI's concurrency
+// is workflow plus ref with cancel-in-progress on non-main refs — so this resolves the version branch's
+// head at the moment it runs and approves only a run whose `head_sha` equals it.
+//
+// THE INTERVAL THAT MATTERS IS BETWEEN THE READ AND THE POST. Filtering the run list by head_sha and
+// re-checking head_sha per row guards a case the API already guarantees; no row can disagree with the
+// value it was queried by. The way this goes wrong is the HEAD going stale: the version step
+// force-pushes that branch whenever it runs, so a push landing between the list and the approval leaves
+// this approving the run on the superseded head — the exact act that cancels the live cut. The head is
+// therefore re-read immediately before each approval, and a move aborts the whole pass rather than
+// skipping one row, because if the branch moved then every id in the list is stale.
+import { argv, env, exit } from "node:process";
+import { pathToFileURL } from "node:url";
+
+const REPO = env.GITHUB_REPOSITORY || "CordilleraSarl/clearotron";
+const BRANCH = arg("--branch") || "changeset-release/main";
+const TOKEN = env.ACTIONS_APPROVE_TOKEN || "";
+
+function arg(name) { const i = argv.indexOf(name); return i === -1 ? null : argv[i + 1]; }
+const say = (s) => process.stdout.write(`release-approve-parked: ${s}\n`);
+
+async function api(path, init = {}) {
+  const r = await fetch(`https://api.github.com${path}`, {
+    ...init,
+    headers: {
+      accept: "application/vnd.github+json",
+      authorization: `Bearer ${TOKEN}`,
+      "x-github-api-version": "2022-11-28",
+      ...(init.headers ?? {}),
+    },
+  });
+  return r;
+}
+
+/**
+ * THE DECISION, SEPARATED FROM THE NETWORK so it can be driven against a table rather than matched as
+ * source text. Given the runs on a head and that head, which run ids should be approved?
+ *
+ * `event` AND `conclusion` both: the dispatched CI run on the same head is not the one the pull
+ * request's rollup reads, and approving it would do nothing while reading as success. PURE.
+ */
+export function runsToApprove(runs, head) {
+  return (Array.isArray(runs) ? runs : [])
+    .filter((r) => r?.event === "pull_request" && r?.conclusion === "action_required" && r?.head_sha === head)
+    .map((r) => r.id);
+}
+
+// The run list is PAGED, and a silent truncation here reads as "nothing parked". 100 is the API maximum;
+// the loop stops when a page comes back short, and says so if it ever hits the cap, because a cut that
+// was not approved because the list was cut off should not look like a cut with nothing to approve.
+async function allRunsOn(head) {
+  const out = [];
+  for (let page = 1; page <= 5; page++) {
+    const r = await api(`/repos/${REPO}/actions/runs?head_sha=${head}&per_page=100&page=${page}`);
+    if (!r.ok) return { ok: false, status: r.status, runs: out };
+    const batch = (await r.json())?.workflow_runs ?? [];
+    out.push(...batch);
+    if (batch.length < 100) return { ok: true, runs: out };
+  }
+  say(`more than 500 runs on this head — reading the first 500 only.`);
+  return { ok: true, runs: out };
+}
+
+// One reading of "where is the version branch now", used twice: once to choose, once immediately before
+// the approval. Null means the question could not be answered, which is never treated as "unchanged".
+async function branchHead() {
+  const br = await api(`/repos/${REPO}/branches/${encodeURIComponent(BRANCH)}`);
+  if (!br.ok) return null;
+  return (await br.json())?.commit?.sha ?? null;
+}
+
+async function main() {
+  // THE ABSENT SECRET IS THE ORDINARY CASE UNTIL THE TOKEN IS MINTED, and it must read as ordinary.
+  if (!TOKEN) {
+    say("no ACTIONS_APPROVE_TOKEN — nothing approved; the version run waits for a person, as before.");
+    return 0;
+  }
+
+  const head = await branchHead();
+  if (!head) { say(`could not read ${BRANCH} — nothing approved.`); return 0; }
+  say(`${BRANCH} is at ${head.slice(0, 7)}`);
+
+  const rr = await allRunsOn(head);
+  if (!rr.ok) { say(`could not list runs for ${head.slice(0, 7)} (${rr.status}) — nothing approved.`); return 0; }
+  const ids = runsToApprove(rr.runs, head);
+  if (!ids.length) {
+    const others = rr.runs.filter((r) => r?.conclusion === "action_required").length;
+    say(`no parked pull_request run on ${head.slice(0, 7)}${others ? ` (${others} parked on another event or head, left alone)` : ""} — nothing to approve.`);
+    return 0;
+  }
+
+  for (const id of ids) {
+    // ── THE INTERVAL THAT MATTERS IS BETWEEN THE READ AND THE POST, NOT INSIDE THE LIST ──────────────
+    //
+    // Filtering the list by head_sha and then re-checking head_sha on each row guards a case the API
+    // already guarantees: no row can disagree with the value it was queried by. What can actually go
+    // wrong is `head` itself going stale — the version step force-pushes this branch whenever it runs,
+    // so a push landing between the list and this POST leaves us approving the run on the SUPERSEDED
+    // head. That is precisely the act that cancels the live cut, because CI's concurrency is workflow
+    // plus ref with cancel-in-progress on non-main refs.
+    //
+    // So the head is re-read immediately before each approval, and a move aborts rather than skips: if
+    // the branch has moved, every id in this list is stale, not just this one.
+    const now = await branchHead();
+    if (now == null) { say(`could not re-read ${BRANCH} before approving — nothing approved.`); return 0; }
+    if (now !== head) {
+      say(`${BRANCH} moved ${head.slice(0, 7)} -> ${now.slice(0, 7)} since the run list was taken — ` +
+        `NOTHING APPROVED. Approving a run on the superseded head would cancel the live one; the cut ` +
+        `waits for a person, or for the next dispatch.`);
+      return 0;
+    }
+    const a = await api(`/repos/${REPO}/actions/runs/${id}/approve`, { method: "POST" });
+    say(a.ok ? `approved run ${id} on ${head.slice(0, 7)}.` : `run ${id} refused approval (${a.status}) — the cut still waits for a person.`);
+  }
+  return 0;
+}
+
+// RUN WHEN INVOKED, whatever the file is called. The old guard compared argv[1] to this file's NAME, so
+// a rename made the step print nothing and exit 0 — a script that never ran, wearing the face of a
+// successful no-op. Comparing the resolved URLs asks the real question instead.
+if (import.meta.url === pathToFileURL(argv[1] ?? "").href) main().then((c) => exit(c)).catch((e) => { say(`could not run (${e?.message ?? e}) — nothing approved.`); exit(0); });

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 ────────────────────────────────────────────────────────────