clearotron 0.3.2-beta.8 → 0.3.2-beta.9

package/shared/pre-rename-spellings.mjs

@@ -0,0 +1,53 @@
+// 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
+// pre-rename-spellings.mjs — names the identifier rename moved that an install still carries on disk.
+//
+// The internal identifier `prelim` became `clearance`. Where that identifier is only a name in the code, the
+// rename is complete. Where it names something an install has already WRITTEN — a directory its runs live
+// under, the session-key prefix its fetched records are filed by — the new name finds nothing, and nothing
+// says so. Each such name is read in both spellings here, the old one as the new.
+//
+// ── The studio segment ──
+//
+// THE SEGMENT IS A PLACE ON DISK, NOT A NAME. Every run an install has made — its slug directories, its
+// `archive/`, its queue, its matter ledger — sits under `<workspace>/studio/<segment>/`. The identifier
+// rename changed the segment the code computes from `prelim-search` to `clearance-search`, which moves
+// nothing on disk: it points every reader at an empty directory, and an empty directory reads as "no runs"
+// and "no queued jobs", never as an error. So an install keeps the segment it has: the old spelling
+// wherever that directory exists, and the new one only for an install that has no other.
+//
+// One definition, imported by every site that builds or recognises the path, including the scripts and
+// servers that deliberately do not load the driver's configuration module.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/** The two spellings, the one every pre-rename install wrote under first: it wins wherever it exists. */
+export const STUDIO_SEGMENTS = Object.freeze(["prelim-search", "clearance-search"]);
+
+/** A regex source matching either spelling, for code that recognises a studio path rather than builds one. */
+export const STUDIO_SEGMENT_RE = "(?:prelim|clearance)-search";
+
+/** The segment the install under `workspaceDir` uses. */
+export function studioSegmentFor(workspaceDir) {
+  try { if (existsSync(join(String(workspaceDir ?? ""), "studio", STUDIO_SEGMENTS[0]))) return STUDIO_SEGMENTS[0]; }
+  catch { /* unreadable ⇒ the new spelling, whose read then fails loudly where it happens */ }
+  return STUDIO_SEGMENTS[1];
+}
+
+/** `<workspaceDir>/studio/<segment>`. */
+export const studioDirFor = (workspaceDir) => join(String(workspaceDir ?? ""), "studio", studioSegmentFor(workspaceDir));
+
+// ── The run's session-key prefix ──
+//
+// A run's register calls and fetched record bodies are filed under `<prefix><slug>-<codename>-…`, and the
+// run's own readers filter by that prefix. A run started before the rename and resumed after it has rows
+// under `prelim-` and is now asked about `clearance-`: its records would read as never fetched, and the
+// delivery check fails the run on records it holds.
+/** Every spelling of one run prefix: `[prefix, the same run under the other identifier]`. PURE. */
+export function runPrefixSpellings(runPrefix) {
+  const p = String(runPrefix ?? "");
+  if (p.startsWith("clearance-")) return [p, `prelim-${p.slice("clearance-".length)}`];
+  if (p.startsWith("prelim-")) return [p, `clearance-${p.slice("prelim-".length)}`];
+  return [p];
+}

package/shared/reference-guard-classes.mjs

@@ -32,7 +32,7 @@
 //
 // ── WHAT IS DELIBERATELY NOT HERE ────────────────────────────────────────────────────────────────
 //
-// PRODUCT VOCABULARY. `lane`, `round`, `box`, `ruling`, `prelim`, `knockout`, `seat` and `jx` are this
+// PRODUCT VOCABULARY. `lane`, `round`, `box`, `ruling`, `clearance`, `knockout`, `seat` and `jx` are this
 // product's own nouns. A guard refusing them fires thousands of times, and a guard that fires on
 // correct prose is one whose next reader deletes from the workflow.
 //
@@ -378,6 +378,40 @@ export function censusOf(files, read) {
  * @param {string} root
  * @returns {{files: string[], laid: number} | {error: string}}
  */
+/**
+ * A reader that answers with what HEAD PUBLISHES at a path, not with whatever is sitting there.
+ *
+ * `publishedOf` asks whether a PATH is in HEAD and never whose bytes are at it. A laid file at a NEW path
+ * is correctly excluded; a laid file that SHADOWS a published path passes that filter, and the census then
+ * measures the private file as though the public tree carried it. Measured on the beta-8 overlay:
+ * `corpus/scripts/report-print-check.mjs` lays over `scripts/report-print-check.mjs`, the private copy
+ * carries two bare references in its comments and the published file carries none, and the residue census
+ * reported `0 → 2` against the public tree. Three of that run's nine reds were this one cause.
+ *
+ * The same hole swallows an ordinary uncommitted edit: mint a backlog with unsaved work in the tree and it
+ * records what you have not published yet. The path filter cannot see either, because both are a question
+ * about bytes.
+ *
+ * ONLY THE FILES THAT DIFFER ARE FETCHED FROM HEAD. Asking git for every file's blob would spawn a process
+ * per file over the whole corpus; asking which paths differ costs one call, and for the rest the bytes on
+ * disk ARE the published bytes. So the common case stays a plain read and correctness does not depend on
+ * how fast it is.
+ *
+ * A file that differs and cannot be read out of HEAD is not silently read from disk: that is the permissive
+ * answer and the one that reinstates the defect. It throws, and `censusOf` skips a file it cannot read —
+ * which undercounts rather than miscounts, and undercounting a floor is the safe direction.
+ */
+export function publishedReader(root, read) {
+  let differs = new Set();
+  try {
+    differs = new Set(execFileSync("git", ["-C", root, "diff", "--name-only", "HEAD"],
+      { encoding: "utf8", maxBuffer: 1 << 28 }).split("\n").map((s) => s.trim()).filter(Boolean));
+  } catch { differs = new Set(); }
+  return (f) => (differs.has(f)
+    ? execFileSync("git", ["-C", root, "show", `HEAD:${f}`], { encoding: "utf8", maxBuffer: 1 << 28 })
+    : read(f));
+}
+
 export function publishedOf(trackedList, root) {
   let head;
   try {
@@ -389,5 +423,9 @@ export function publishedOf(trackedList, root) {
     return { error: `could not read HEAD in ${root}: ${String(e.message).split("\n")[0]}` };
   }
   const files = trackedList.filter((f) => head.has(f));
-  return { files, laid: trackedList.length - files.length };
+  // THE PATHS, not only how many. A count tells a reader that something was not counted and leaves them
+  // to find out what; every caller that acts on `laid` needs to name them, and deriving the list again at
+  // each call site is three chances to derive it differently.
+  const laidPaths = trackedList.filter((f) => !head.has(f));
+  return { files, laid: laidPaths.length, laidPaths };
 }

package/shared/stdio-connect.mjs

@@ -61,8 +61,15 @@ export function stdioConnectCommand({ installRoot = stableInstallRoot({ installR
  * descriptions of one thing drift into three different promises about what it does.
  */
 export function stdioConnectOffer(opts = {}) {
+  // ASKED OF THE SAME COMPOSER THE PAGE ASKS, so a terminal under WSL offers the two sides the page
+  // offers and neither surface has to know how a launcher is built. `command` is what it has always
+  // been — off WSL the one line, and under WSL the Windows-side one, which is the row that leads there
+  // too — and `variants` is null unless the caller named a WSL target, so no surface grows a second
+  // line because this file changed.
+  const both = stdioConnectFor("claude-cli", opts);
   return {
-    command: stdioConnectCommand(opts),
+    command: both.text,
+    variants: both.variants,
     name: STDIO_SERVER_NAME,
     // Deliberately states the two facts a reader needs to judge it: no network, and it only works from a
     // machine with this install on its disk. Both are why it is offered to staff and not to a client.
@@ -315,13 +322,41 @@ export function remoteConnectFor(shape, { address = null } = {}) {
  * absence is a finding: a row naming a shape nobody implemented should surface as missing, and the
  * table's own arm refuses such a row outright.
  */
+/**
+ * THE TWO SIDES OF A WSL INSTALL, in the product's own words and in ONE place.
+ *
+ * An install inside WSL can be reached by an assistant on the Windows side — Claude Desktop, Claude Code
+ * in PowerShell — through the `wsl.exe` wrapper, and by an assistant running inside the distribution
+ * with the plain `node` line. They are different commands and the reader has to be told which is which;
+ * the owner pasted the Windows one into Claude Code inside WSL and got a closed connection.
+ *
+ * Ruled 2026-09-17: these words exactly, and no other new sentence. They are exported rather than spelled
+ * at each surface so the page and the terminal cannot drift apart — one author, as everything else here.
+ */
+export const WSL_ROW_HEADINGS = Object.freeze({ fromWindows: "From Windows", insideWsl: "Inside WSL" });
+
 export function stdioConnectFor(shape, { installRoot = stableInstallRoot({ installRoot: INSTALL_ROOT }), workDir = null, reportsDir = null, platform = process.platform, wsl = null } = {}) {
   const spec = Object.hasOwn(STDIO_SHAPES, String(shape ?? "")) ? STDIO_SHAPES[shape] : null;
   if (!spec) return null;
   const server = join(installRoot, "mcp-server", "server.mjs");
+  const render = (target) => spec.render({ server, workDir, reportsDir, platform, wsl: target });
+  const base = { shape, kind: spec.kind, where: spec.where, after: spec.after, name: STDIO_SERVER_NAME };
+  // OFF WSL NOTHING CHANGES: one launcher, no variants, and `variants: null` rather than an empty array
+  // so a consumer cannot read "this install has no sides" as "this install has two sides, both missing".
+  if (!wsl) return { ...base, text: render(null), variants: null };
+  // ON WSL, TWO, AND THE SECOND IS NOT WRITTEN TWICE. The inside-WSL launcher is exactly what this shape
+  // renders for an install that is not under WSL at all — the same author, asked with the target taken
+  // away — so it is the line every off-WSL install already offers and every arm already covers, rather
+  // than a second composition that can drift from it.
+  //
+  // `text` stays the Windows-side one. Every consumer that reads a single `text` today keeps the answer
+  // it has always had, and only the surfaces that ask for `variants` draw the pair.
   return {
-    shape, kind: spec.kind, where: spec.where, after: spec.after,
-    text: spec.render({ server, workDir, reportsDir, platform, wsl }),
-    name: STDIO_SERVER_NAME,
+    ...base,
+    text: render(wsl),
+    variants: [
+      { heading: WSL_ROW_HEADINGS.fromWindows, text: render(wsl) },
+      { heading: WSL_ROW_HEADINGS.insideWsl, text: render(null) },
+    ],
   };
 }

package/shared/tree-commit.mjs

@@ -0,0 +1,48 @@
+// 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
+//
+// tree-commit.mjs — the tree a path belongs to, and the commit that tree carries.
+//
+// A CHECKOUT ANSWERS THROUGH GIT; A PACKAGED INSTALL ANSWERS THROUGH ITS build-info.json. An install
+// from the registry is a copy of the package, not a clone: there is no git there and there never will
+// be, so asking git about it fails every time, and a deploy check that treats that failure as a fault
+// reports every packaged box as broken. What a packaged install does carry is `build-info.json`, written
+// by `prepack`, naming the commit it was packed from — read here through the one reader of that file.
+//
+// Git is asked first, and only its failure sends the question to the stamp: a checkout's HEAD is the
+// truth about a checkout, and a stale stamp left in one must not outvote it.
+import { dirname } from "node:path";
+import { execFileSync } from "node:child_process";
+import { packagedBuild } from "./packaged-build.mjs";
+
+/** `git -C <repo> <args>`, keeping git's own sentence when it fails. */
+export function gitTry(repo, ...args) {
+  try {
+    return { ok: true, out: execFileSync("git", ["-C", repo, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim(), err: null };
+  } catch (e) {
+    return { ok: false, out: null, err: String(e?.stderr || e?.message || e).replace(/\s+/g, " ").trim().slice(0, 120) };
+  }
+}
+
+/**
+ * `{ root, head, source, why }` for the tree holding `path`. `source` is "git" or "build-info"; `root`
+ * null means neither could say, and `why` names both failures. Readers are injected so an arm can drive
+ * a packaged install without building one.
+ */
+export function treeOf(path, { git = gitTry, build = packagedBuild } = {}) {
+  const top = git(path, "rev-parse", "--show-toplevel");
+  if (top.ok) {
+    const head = git(top.out, "rev-parse", "HEAD");
+    return { root: top.out, head: head.ok ? head.out : null, source: "git",
+      why: head.ok ? null : `git could not read HEAD in ${top.out}: ${head.err}` };
+  }
+  // WALK UP to the package root: a unit's WorkingDirectory or a running module sits somewhere inside
+  // the installed package, and the stamp is at its top.
+  for (let d = path; ; d = dirname(d)) {
+    const b = build(d);
+    if (b) return { root: d, head: b.commit, source: "build-info", why: null };
+    if (dirname(d) === d) break;
+  }
+  return { root: null, head: null, source: null,
+    why: `git could not read ${path} (${top.err}), and no build-info.json above it names a commit` };
+}