geneseed 3.13.0 → 3.15.0

package/js/lib/fs.mjs

@@ -4,9 +4,11 @@
  * These are definitions, not an adaptation of somebody else's. Every rule below was
  * originally MEASURED against CPython, because the generator these functions serve had to
  * emit bytes indistinguishable from a Python one; that second party is gone and the rules
- * are not. What holds them now is the recorded corpora under `tests/__snapshots__/`, which
- * compare this module's output byte for byte and can never be re-recorded — so a rule here
- * is a frozen fact about what this tool emits, and changing one is a product change.
+ * are not. The recorded corpora that compared this module's output byte for byte went with
+ * the former Python suite; what holds the rules now is `tests/unit/lib_primitives.test.mjs`
+ * (`isFile`/`isDir`), `tests/unit/hook_cli.test.mjs`'s platform-newline count (the stream
+ * funnels), and for the rest only the per-function provenance below. A rule here is still a
+ * frozen fact about what this tool emits, and changing one is a product change.
  *
  * ⚠ NONE OF THESE IS THE NODE DEFAULT, AND THAT IS THE ONE THING TO KNOW BEFORE EDITING ONE.
  * Each is a deliberate divergence from the obvious one-liner, and the obvious one-liner is
@@ -107,10 +109,10 @@ export function copyFile(src, dest) {
  * its caller different BYTES than the Python one: measured at 176 vs 171 for one `context`
  * run before this existed.
  *
- * `harness_golden.py` structurally cannot see the difference — `subprocess` decodes with
- * universal newlines on the way back, folding both shapes to `\n` before any cell compares
- * them, the same shape as the shim's exclusion from `golden.py`. So the gate for it is
- * `test_the_two_entry_points_agree_on_stdout_BYTES`, which captures raw bytes. Moved here
+ * The CLI matrix structurally cannot see the difference — every cell decodes stdout with
+ * universal newlines, folding both shapes to `\n` before anything compares them. So the gate
+ * for it is `tests/unit/hook_cli.test.mjs`'s `every newline the entry points write is the
+ * platform's`, which counts raw bytes. Moved here
  * from `js/hosts/hooks.mjs` in P5c, when `js/inspect/excludes.mjs` became the second caller: a translation
  * that exists twice is a translation that can be fixed once.
  */
@@ -167,10 +169,9 @@ export function withDiscardableStderr(fn) {
  * `emitGlobalInto`.
  *
  * The item it closes: a plain `--emit files` handed its caller 104 bytes where `python
- * build.py` handed over 105, and `tests/golden.py`'s `text=True` capture folds both to the
- * same string. `test_the_two_entry_points_agree_on_stdout_BYTES` grew a `build` row (through
- * `harness build`, which calls this `main` in-process) and a `rebuild-all` row, and those are
- * what can see it.
+ * build.py` handed over 105, and a `text=True` capture folds both to the same string.
+ * `tests/unit/hook_cli.test.mjs`'s newline test carries a `build` row (through `geneseed
+ * build`, which calls this `main` in-process), and that is what can see it.
  *
  * A Buffer chunk passes through untouched: `writeText` owns file bytes and nothing on this
  * path writes binary to a stream, so translating one would be corrupting data rather than

package/js/lib/json.mjs

@@ -5,8 +5,8 @@
  * These are definitions, not an adaptation of somebody else's; see `fs.mjs` for why the
  * measurements against CPython are recorded per function, and why NONE of these is the Node
  * default — the warning the retired `py` prefix used to carry now lives in each docblock.
- * A rule here is a frozen fact about what this tool emits — the corpora under
- * `tests/__snapshots__/` compare it byte for byte and can never be re-recorded.
+ * A rule here is a frozen fact about what this tool emits — the written-out tables in
+ * `tests/unit/lib_primitives.test.mjs` and `tests/unit/settings_jsonc.test.mjs` pin it.
  *
  * `JsonNumber` is why this module holds both the parser and the renderers: the wrapper is
  * created by `parseJson` and read by `formatValue`, `formatRepr`, `isTruthy` and `deepEquals`, so the
@@ -305,8 +305,8 @@ function escapeNonAscii(text) {
  * Indentation is what makes this tractable: passing `indent` switches Python's
  * separators from `(', ', ': ')` to `(',', ': ')`, which is exactly what
  * `JSON.stringify(v, null, 2)` emits. Verified rather than argued \u2014
- * `tests/test_opencode_extras_parity.py` compares both variants against Python over a
- * corpus of container shapes.
+ * the former Python suite compared both variants against Python over a corpus of container
+ * shapes; `tests/unit/lib_primitives.test.mjs` now pins only this writer's number spellings.
  */
 export function jsonDumpsIndent(value, { ensureAscii = true } = {}) {
   const text = JSON.stringify(value, null, 2);

package/js/lib/paths.mjs

@@ -22,7 +22,7 @@ const { X_OK } = constants;
  * BMP), and `str.lower()` is not `toLowerCase()` for a handful of characters.
  *
  * THE SEPARATOR CONVERSION IS NOT OPTIONAL, and it was missing until the byte-bearing
- * corpus in `tests/test_pure_function_parity.py` asked. `ntpath.normcase` is
+ * corpus in the former Python parity suite asked. `ntpath.normcase` is
  * `s.replace('/', '\\').lower()`, and `PurePath._str_normcase` gets the same conversion for
  * free because `Path` has already done it — so BOTH readings of the reference fold slashes
  * and this did not. Every sort call site feeds it `path.join` output or a bare `readdir`
@@ -50,7 +50,7 @@ export const normcase = process.platform === 'win32'
  * a directory depth, and `golden.py` compared CONTENT rather than order. It became visible
  * the first time a full path list was PRINTED \u2014 `geneseed validate -v` \u2014 against a real
  * skills tree that happens to contain both `skills/geneseed/` and `skills/geneseed-code-review/`.
- * `tests/test_maintainer_tools_parity.py` found it and died with the reference it compared
+ * The former Python maintainer-tools test found it and died with the reference it compared
  * against. What HOLDS it now is `tests/unit/maintainer_tools.test.mjs`, and specifically its
  * `theme files are visited in THIS platform's Path collation order` test: it re-derives Python's
  * `sorted(Path)` order for the running platform instead of replaying a recording, so it cannot
@@ -73,10 +73,14 @@ export function comparePaths(a, b) {
  * `_install_move_list` in `js/maintain/uninstall.mjs` \u2014 a CLI-level module that must not import the
  * web tree to reach it. Beside `normcase`, which is the thing it is actually about.
  * `js/web/api.mjs` re-exports it so its existing importers are unchanged.
+ *
+ * TRAILING SEPARATORS ARE STRIPPED FROM `parent` FIRST. A root is the one path whose canonical
+ * spelling ends in one — `D:\` and `/` — and splitting it leaves an empty last segment that no
+ * child's segment equals, so nothing was ever `within` a drive root or `/`.
  */
 export function within(child, parent) {
   const c = normcase(child).split(/[\\/]/);
-  const p = normcase(parent).split(/[\\/]/);
+  const p = normcase(parent).replace(/[\\/]+$/, '').split(/[\\/]/);
   return p.length <= c.length && p.every((seg, i) => c[i] === seg);
 }
 
@@ -86,7 +90,7 @@ export function within(child, parent) {
  * `Path` is `WindowsPath` on Windows and `PosixPath` everywhere else, and the two parsers
  * disagree about the two things below. A body that is right on one host is therefore wrong
  * on the other, which is exactly how this one passed a whole Windows suite and failed two
- * cases on the first Linux run of `tests/test_pure_function_parity.py`:
+ * cases on the first Linux run of the former Python pure-function parity suite:
  *
  *   * SEPARATORS. `ntpath` treats `\` and `/` alike; `posixpath` treats `\` as an ordinary
  *     filename character. `str(PurePosixPath('C:\\x\\bin\\'))` is that string VERBATIM —
@@ -100,8 +104,8 @@ export function within(child, parent) {
  * NOT reproduced, and named here rather than left as a gap nobody wrote down: `//` and
  * `///x` on WINDOWS, where `PureWindowsPath` answers `\\` and `\\\x` and this answers `\`
  * and `\x`. Those are incomplete UNC prefixes and matching them needs ntpath's share-name
- * parsing; both inputs are kept OUT of the corpus in `tests/test_pure_function_parity.py`
- * instead of sitting in it wrong.
+ * parsing; both inputs were kept OUT of the retired parity corpus instead of sitting in it
+ * wrong.
  *
  * The root's separators are still rewritten ONE AT A TIME, never `replace(/[\\/]+/g, sep)`:
  * a UNC root's leading pair is part of it, so collapsing runs turns `//server/share/x` into
@@ -143,7 +147,8 @@ export function toPlatformPath(s) {
  * `context` cell varies it, and changing it in this phase would be an ungated edit to a verb
  * that crossed three phases ago. Recorded in the spec's "Still owed" with this reproduction.
  *
- * Gated by a corpus in `tests/test_pure_function_parity.py`: no cell can vary the shape.
+ * It was gated by a corpus in the retired Python pure-function parity suite; nothing has
+ * replaced it, and no CLI test can vary the shape.
  */
 export function isAbsolutePath(s) {
   if (process.platform !== 'win32') return s.startsWith('/');
@@ -166,27 +171,21 @@ export function isAbsolutePath(s) {
  * PATH-removal refutation is aimed at, and the reason this is a real lookup rather than one
  * line of "we are node, we know where node is".
  *
- * The Windows half is the part with behaviour in it, and three of its four rules were
- * MEASURED against CPython 3.13 rather than assumed. `PATHEXT` supplies the suffixes, and the
+ * The Windows half is the part with behaviour in it, and its suffix rules were MEASURED
+ * against CPython 3.13 rather than assumed. `PATHEXT` supplies the suffixes, and the
  * returned path carries PATHEXT's OWN SPELLING of the extension rather than the file's
  * (`zzcmd.CMD` for a `zzcmd.cmd` on disk). An extension already in that set means the command
- * is spelled in full. An EMPTY PATH entry is not skipped either: `join('', cmd)` is a
- * relative path, and Python answers with one.
- *
- * THE FOURTH RULE IS THE CURRENT DIRECTORY, and it was measured on a machine that could not
- * see it. `shutil.which` prepends `os.curdir` to the search — even to a `path=` given
- * explicitly — when `_winapi.NeedCurrentDirectoryForExePath` says so, and that Win32 call
- * answers TRUE unless `NoDefaultCurrentDirectoryInExePath` is DEFINED in the environment.
- * Git Bash and this repo's developer machine both define it, so the reference answered None
- * there and the first draft's "the current directory is NOT prepended — it was until 3.12"
- * described an environment variable it had mistaken for a version change. GitHub's Windows
- * runner does not define it: the reference answered `.\\geneseed.CMD` for a `geneseed` looked
- * up beside the repo root, this returned null, and the parity corpus said so on the first CI
- * run. The variable is an INPUT, so it is read here rather than baked, and
- * `test_the_curdir_rule_agrees_in_both_environment_states` runs the corpus with it both ways.
- *
- * Gated as a pure function over a seeded directory in `tests/test_pure_function_parity.py`:
- * a cell can only ever observe the one answer this machine's PATH gives.
+ * is spelled in full.
+ *
+ * THE CURRENT DIRECTORY IS NEVER SEARCHED IMPLICITLY, and here this departs from
+ * `shutil.which` on purpose. The reference prepends `os.curdir` on Windows unless
+ * `NoDefaultCurrentDirectoryInExePath` is defined, and answers an EMPTY PATH entry (a
+ * trailing `;` is routine) with a cwd-relative path. Every caller SPAWNS what this returns —
+ * `git` from `upgrade`, `java` from `setup`, `node` from the doctor, `npm` from the web server
+ * — from whatever directory the user is in, so a `git.exe` committed to an untrusted clone ran
+ * the moment `geneseed upgrade` was typed inside it. Both routes are closed; a `.` the user
+ * wrote into PATH themselves is still honoured, because that is their choice and not ours.
+ * Gated in `tests/unit/lib_primitives.test.mjs`.
  */
 export function which(cmd, searchPath = null) {
   const win = process.platform === 'win32';
@@ -209,14 +208,9 @@ export function which(cmd, searchPath = null) {
   // then spawns. Measured: the corpus case with a posix-spelled directory was the one that
   // differed, and `path.join` had rewritten the whole path rather than appending to it.
   const joinRaw = (dir, name) => (
-    dir === '' || /[\\/]$/.test(dir) || (win && dir.endsWith(':'))
+    /[\\/]$/.test(dir) || (win && dir.endsWith(':'))
       ? dir + name : dir + path.sep + name);
-  const dirs = (searchPath ?? process.env.PATH ?? '').split(path.delimiter);
-  // `NeedCurrentDirectoryForExePath(cmd)`: TRUE — so `.` goes in FRONT — unless the variable
-  // is defined. Only reachable with a separator-free `cmd`, which is the only way execution
-  // gets this far. Inserted before the dedupe, exactly where `shutil.which` inserts it, so a
-  // PATH that already names `.` is searched once.
-  if (win && process.env.NoDefaultCurrentDirectoryInExePath === undefined) dirs.unshift('.');
+  const dirs = (searchPath ?? process.env.PATH ?? '').split(path.delimiter).filter(Boolean);
   const seen = new Set();
   for (const dir of dirs) {
     const key = win ? dir.toLowerCase() : dir;

package/js/lib/proc.mjs

@@ -11,9 +11,9 @@
  * that module and six of its spawns used it, so the four spawn sites in `js/inspect/checks-authoring.mjs`,
  * `js/hosts/hooks.mjs`, `js/maintain/setup.mjs` and `js/hosts/link.mjs` each had to remember the flag on their
  * own. Two of them did not — and the miss is BYTE-INVISIBLE: a console window is not
- * something the CLI prints, so every recorded cell under `tests/__snapshots__/` stays green
- * while the windows pop. The property under test never reaches the comparison, which is why
- * a recorded corpus cannot be the gate here. A shared constant plus
+ * something the CLI prints, so every cell of `tests/golden.mjs --cli` stays green while the
+ * windows pop. The property under test never reaches the comparison, which is why a byte
+ * comparison cannot be the gate here. A shared constant plus
  * `tests/unit/spawn_hygiene.test.mjs` is what makes the next spawn site inherit the answer
  * instead of re-deciding it.
  *

package/js/lib/prompt.mjs

@@ -0,0 +1,132 @@
+/**
+ * The line-mode stdin readers — `ask`, `promptLine`, `confirm`, `askChoice` over one `readLine`.
+ *
+ * MOVED OUT OF `js/maintain/setup.mjs`, which is where the Python's own owner (`_harness_setup`)
+ * put them, because two callers that are not the wizard need them: `uninstall`'s `confirm` and
+ * the web server's npm prompt. Importing them from `setup.mjs` dragged the whole wizard closure
+ * — the driver, the doctor, the diff exporter — into `uninstall` and `web` for four functions
+ * whose only dependencies are fd 0, `printOut` and `parseIntStrict`.
+ */
+import { readSync } from 'node:fs';
+
+import { printOut } from './fs.mjs';
+import { parseIntStrict } from './text.mjs';
+
+/**
+ * `_harness_setup._ask` — `input(f"{prompt}{suffix}: ").strip()`, or the default at EOF.
+ *
+ * WHY IT READS A BYTE AT A TIME. Node has no synchronous line read: `readFileSync(0)` blocks
+ * until EOF rather than until Enter, so a wizard built on it would hang on a real terminal
+ * until the user pressed Ctrl-D. Reading fd 0 one byte at a time to the first `\n` is what
+ * `input()` does, and it is the only synchronous shape that stops where Enter stops. The
+ * body arrived in P5h inside `js/maintain/uninstall.mjs`'s `confirm`, moved to `setup` when that
+ * became the second caller, and lives here now that the callers outnumber the wizard;
+ * `confirm` is built on it exactly as `_confirm` is built on `_ask` in the Python.
+ *
+ * The EOF branch is the one a piped caller sees, and it agrees with Python by two different
+ * routes that happen to produce one answer: `input()` RAISES `EOFError` and the `except`
+ * returns the default, while a zero-length read here leaves `line` empty and `|| dflt` does
+ * the same. A partial line with no trailing newline is not EOF to either — Python returns
+ * the characters and so does this.
+ *
+ * `.trim()` is `str.strip()` in every case but U+FEFF, which JS counts as whitespace and
+ * Python does not; that is a standing item of this port and not this function's to settle.
+ */
+export function ask(prompt, dflt = '') {
+  const suffix = dflt ? ` [${dflt}]` : '';
+  // `input()` writes its prompt to stdout with no newline — nothing for `printOut` to
+  // translate, and it must NOT gain one.
+  process.stdout.write(`${prompt}${suffix}: `);
+  // `?? ''` because `readLine` reports EOF-with-nothing-read as null since P6h; `_ask`
+  // catches `EOFError` and returns the default, which is what the empty string produces
+  // here through `|| dflt`. The two routes to one answer are the docblock's own point.
+  const ans = (readLine() ?? '').trim();
+  return ans || dflt;
+}
+
+/**
+ * `input(prompt)` with EOF told apart from an empty line — `null` where Python RAISES.
+ *
+ * `ask` above cannot express that difference and does not need to: its EOF and its empty
+ * answer both mean "take the default". `_web_server.serve`'s npm prompt is the first
+ * caller where they differ, and they differ dangerously — `""` is in its accepted set, so
+ * a port that read EOF as an empty line would answer YES to "run npm install now?" on
+ * every non-interactive run. The reference catches `(EOFError, KeyboardInterrupt)` and
+ * answers "n"; this returns null so the caller can.
+ *
+ * No `.trim()`: `input()` does not strip, and both callers strip for themselves.
+ */
+export function promptLine(prompt) {
+  process.stdout.write(prompt);
+  return readLine();
+}
+
+/**
+ * Fd 0 to the first `\n`, dropping a `\r` before it — the CRLF a Windows console sends.
+ *
+ * THE BYTES ARE COLLECTED AND DECODED ONCE, and that is a fix rather than a style. The
+ * version this arrived as decoded EACH BYTE on its own — `buf.toString('utf8', 0, n)` inside
+ * the loop — which turns every multi-byte character into two or three U+FFFD. It was
+ * invisible for a phase because its only caller was `confirm`, whose answer is `y` or `n`;
+ * the wizard's first non-ASCII answer is what exposed it, and the corpus caught it on the
+ * first run. Scanning for the terminators a byte at a time is still correct: `\n` and `\r`
+ * are ASCII, and no continuation byte of a UTF-8 sequence is below 0x80.
+ */
+function readLine() {
+  const buf = Buffer.alloc(1);
+  const bytes = [];
+  let eof = false;
+  for (;;) {
+    let n = 0;
+    try { n = readSync(0, buf, 0, 1, null); } catch { eof = true; break; }
+    if (n === 0) { eof = true; break; }
+    if (buf[0] === 0x0a) break;
+    if (buf[0] !== 0x0d) bytes.push(buf[0]);
+  }
+  // NULL ONLY FOR THE EMPTY EOF, which is the one case `input()` raises on. A partial line
+  // with no trailing newline is not EOF to Python — it returns the characters — and the
+  // `bytes.length` test is what keeps that arm returning a string here too.
+  if (eof && bytes.length === 0) return null;
+  return Buffer.from(bytes).toString('utf8');
+}
+
+/** `_harness_setup._confirm` — `_ask` with a Y/n suffix; the default on an empty answer. */
+export function confirm(prompt, dflt = true) {
+  const ans = ask(`${prompt} (${dflt ? 'Y/n' : 'y/N'})`).toLowerCase();
+  return ans === '' ? dflt : ans[0] === 'y';
+}
+
+/**
+ * `_harness_setup._ask_choice` — a numbered menu; the chosen KEY, or the default.
+ *
+ * THREE THINGS ABOUT THE FALLBACK ORDER, all of them observable and none of them obvious:
+ *
+ *   * The key match lives in Python's `except ValueError`, so an answer that PARSES as an
+ *     integer never reaches it. `99` against a five-option menu returns the default; it does
+ *     not go looking for an option literally named `99`.
+ *   * An in-range index wins, a parsed out-of-range index falls to the default, and only an
+ *     UNPARSEABLE answer is matched against the keys. `parseIntStrict` is what separates the second
+ *     case from the third, and it is not `Number()` — see its own docblock.
+ *   * A default that is NOT in `options` falls back to option 1. It is reachable — a deployed
+ *     `.geneseed-theme` can name a theme this checkout no longer ships — and it used to throw,
+ *     mirroring the Python reference's `StopIteration`, which crashed `geneseed setup` before
+ *     its first question. The reference is gone, so there is nothing left to fail in step
+ *     with, and returning a key that is not on the menu would hand the build a stale value.
+ */
+export function askChoice(prompt, options, dflt) {
+  if (!options.some(([k]) => k === dflt)) dflt = options[0][0];
+  printOut(`\n${prompt}:\n`);
+  options.forEach(([key, desc], i) => {
+    const label = desc ? `${key} — ${desc}` : key;
+    printOut(`  ${i + 1}) ${label}${key === dflt ? '   (default)' : ''}\n`);
+  });
+  const defaultIdx = options.findIndex(([k]) => k === dflt);
+  const raw = ask('Choose', String(defaultIdx + 1));
+  const idx = parseIntStrict(raw);
+  if (idx !== null) {
+    if (idx >= 1 && idx <= options.length) return options[idx - 1][0];
+  } else {
+    for (const [key] of options) if (raw === key) return key;
+  }
+  return dflt;
+}

package/js/lib/text.mjs

@@ -9,6 +9,8 @@
  * set than `String.trim`'s, `parseIntStrict` accepts what `Number()` does not and rejects what
  * it does, and `percentDecode` leaves a bad escape alone where `decodeURIComponent` throws.
  */
+import path from 'node:path';
+
 /**
  * `len(s)` — CODE POINTS, where `String.length` counts UTF-16 units.
  *
@@ -50,8 +52,10 @@ export const padEndToWidth = (s, width) => s + ' '.repeat(Math.max(0, width - co
  * raw environment value do it — `js/ui/cli.mjs`'s `helpWidth` and `js/web/activity.mjs` wrap
  * the argument in `stripWhitespace` first.
  *
- * Gated by a corpus in `tests/test_pure_function_parity.py` — a primitive reproduction gets
- * one owner and a corpus, never a cell (P5c).
+ * Its own corpus retired with the Python suite — a primitive reproduction gets one owner and
+ * a corpus, never a cell (P5c) — so what reaches it now is only its callers' gates:
+ * `tests/unit/wizard.test.mjs`'s choice corpus and `tests/unit/web_daemon.test.mjs`'s
+ * non-integer port.
  */
 export function parseIntStrict(s) {
   if (typeof s !== 'string' || s === '') return null;
@@ -146,8 +150,8 @@ export function stripWhitespaceEnd(s) {
  * `Buffer.toString('utf-8')` substitutes U+FFFD for an undecodable sequence, which is
  * `errors='replace'`. The two decoders can disagree on HOW MANY replacement characters a
  * truncated multi-byte sequence yields — Python's maximal-subpart rule against WHATWG's —
- * and the corpus in `tests/test_pure_function_parity.py` is where that is measured rather
- * than assumed.
+ * and the former Python corpus is where that was measured rather than assumed; nothing
+ * measures it now.
  */
 const HEX_PAIR = /^[0-9A-Fa-f]{2}$/;
 
@@ -179,3 +183,13 @@ export function percentDecode(s) {
   return res;
 }
 
+/**
+ * `Path.relative_to(base).as_posix()` — `target` relative to `base`, always `/`-separated.
+ *
+ * Here, not in `js/build/emit-common.mjs`, because the hook path (`js/hosts/hooks-context.mjs`)
+ * needs it too and must not pay for the render module to get it; this module imports nothing
+ * but `node:path`. It had been defined four times.
+ */
+export function relPosix(base, target) {
+  return path.relative(base, target).split(path.sep).join('/');
+}

package/js/lib/udiff.mjs

@@ -4,8 +4,9 @@
  * WHY A HAND-WRITTEN MATCHER RATHER THAN A LIBRARY. The diff is the ENTIRE user-visible
  * payload of `geneseed diff`: the hunks in `--full` and in the exported improvements file
  * are this file's output and nothing else's. A generic JS diff would produce a CORRECT diff
- * and a DIFFERENT one, and `tests/__snapshots__/primitives/` compares the hunks character
- * for character, so "also a valid diff" fails every cell. The alignment below IS the
+ * and a DIFFERENT one, and the former Python suite's corpus compared the hunks character for
+ * character, so "also a valid diff" failed every case (today only the `diff/--full-…` CLI cell
+ * compares hunks, and only one; see `js/inspect/diff.mjs`). The alignment below IS the
  * specification of what this tool prints, and three of its choices are choices no other
  * algorithm makes:
  *

package/js/loop/catalog.mjs

@@ -19,7 +19,7 @@ import { readdirSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { readText, isFile, isDir } from '../lib/fs.mjs';
-import { frontmatter } from '../hosts/hooks.mjs';
+import { frontmatter } from '../hosts/memory-files.mjs';
 import { SRC } from '../build/source.mjs';
 import { checkGraph } from './graph.mjs';
 
@@ -117,8 +117,10 @@ export function loadCatalog({
   return { bricks, templates, problems, overridden: overridden.sort() };
 }
 
-export function catalogProblems(opts = {}) {
-  const { bricks, templates, problems } = loadCatalog(opts);
+/** `catalog`: an already-loaded `loadCatalog(opts)`, for a caller that needs the catalogue
+ * itself too — passing it saves reading every brick and template twice. */
+export function catalogProblems(opts = {}, catalog = loadCatalog(opts)) {
+  const { bricks, templates, problems } = catalog;
   const out = [...problems];
   for (const [name, graph] of [...templates].sort(([a], [b]) => (a < b ? -1 : 1))) {
     out.push(...checkGraph(graph, bricks).map((p) => `loops/${name}: ${p}`));

package/js/loop/cli.mjs

@@ -5,7 +5,9 @@
  *
  * NO SPAWN. The CLI's closure may not start processes, so git is the model's job: it pipes
  * `git diff --cached --numstat` into `score --diff` and `git status --porcelain` into `record`.
- * stdin is read only when it is not a TTY — a hand-run `geneseed loop record` must not hang.
+ * stdin is read only when it is not a TTY — a hand-run `geneseed loop record` must not hang —
+ * and a TTY reads as `null`, "no porcelain given", never as `''`: an empty pipe is a CLEAN
+ * tree, and a clean tree is exactly the snapshot a read brick's check must compare against.
  *
  * NO `--file`. `state.mjs`'s `LOOP_FILE` constant is the ROOT-RELATIVE path the engine filters
  * out of every diff and porcelain check, so LOOP.md has to live at the git root of the worktree
@@ -27,7 +29,7 @@ import {
 import { recordLoop } from './registry.mjs';
 
 const emit = (obj) => { printOut(`${JSON.stringify(obj)}\n`); return obj.error || obj.ok === false ? 1 : 0; };
-const stdin = () => (process.stdin.isTTY ? '' : readFileSync(0, 'utf8'));
+const stdin = () => (process.stdin.isTTY ? null : readFileSync(0, 'utf8'));
 const list = (s) => (s ? String(s).split(',').map((x) => x.trim()).filter(Boolean) : null);
 
 function requireRoot() {
@@ -58,14 +60,17 @@ function writeCommitMessage(root, gitdir, result) {
   return { ...result, message_file: file.replaceAll('\\', '/') };
 }
 
-function withState(fn) {
+/** `write: false` for a read-only action (`next`): rewriting LOOP.md there would change
+ * nothing, and would race the Active tab's preset picker (`registry.mjs`'s `setLoopPreset`) —
+ * a preset it saved between this read and the rewrite would be silently undone. */
+function withState(fn, { write = true } = {}) {
   const root = requireRoot();
   const file = path.join(root, LOOP_FILE);
   if (!isFile(file)) throw new Error(`${file} does not exist — run \`geneseed loop init\` first`);
   const state = parseLoopFile(readText(file));
   const { bricks } = loadCatalog({ projectRoot: root });
   const result = fn(state, bricks);
-  writeLoopFile(file, state);
+  if (write) writeLoopFile(file, state);
   return result;
 }
 
@@ -79,26 +84,30 @@ function resolveGraph(spec, catalog) {
 
 const ACTIONS = {
   check(args) {
+    // The project level of the catalogue is `<git root>/.geneseed/`, as for `init` and `next`,
+    // so a check run from a subdirectory sees the same bricks and templates they will.
+    const root = gitRootOf(process.cwd()) ?? process.cwd();
     if (args.brick) {
       const { problems } = parseBrick(readText(path.resolve(args.brick)), 'checked');
       return { ok: !problems.length, problems };
     }
     if (args.graph) {
-      const catalog = loadCatalog({ projectRoot: process.cwd() });
+      const catalog = loadCatalog({ projectRoot: root });
       const problems = checkGraph(resolveGraph(args.graph, catalog), catalog.bricks);
       return { ok: !problems.length, problems };
     }
     // The bare check doubles as the catalogue LISTING the loop skill composes a free graph
     // from — frontmatter only: a brick's body reaches the model through `next`, for the node
     // the engine chose, never as a menu.
-    const problems = catalogProblems({ projectRoot: process.cwd() });
-    const { bricks, templates, overridden } = loadCatalog({ projectRoot: process.cwd() });
+    const catalog = loadCatalog({ projectRoot: root });
+    const problems = catalogProblems({ projectRoot: root }, catalog);
+    const { bricks, templates, overridden } = catalog;
     const byName = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
     return {
       ok: !problems.length, problems,
       templates: [...templates.keys()].sort(byName),
       bricks: [...bricks.values()].sort((a, b) => byName(a.name, b.name))
-        .map(({ body, available, reason, ...b }) => ({ ...b, available, ...(reason ? { reason } : {}) })),
+        .map(({ body, reason, ...b }) => ({ ...b, ...(reason ? { reason } : {}) })),
       overridden,
     };
   },
@@ -121,14 +130,14 @@ const ACTIONS = {
     recordLoop({ root, branch: currentBranch(root), title: args.title });
     return { file, graph: graph.name, preset: state.preset, status: state.status };
   },
-  next: () => withState((s, b) => nextStep(s, b)),
+  next: () => withState((s, b) => nextStep(s, b), { write: false }),
   score(args) {
     if (args.diff) {
       // X6: resolve (and validate) the gitdir BEFORE withState runs the state change, so a
       // malformed `.git` file errors without advancing the loop.
       const root = requireRoot();
       const gitdir = gitDirOf(root);
-      return writeCommitMessage(root, gitdir, withState((s) => scoreDiff(s, parseNumstat(stdin()))));
+      return writeCommitMessage(root, gitdir, withState((s) => scoreDiff(s, parseNumstat(stdin() ?? ''))));
     }
     if (!args.declared) throw new Error('score needs --declared or --diff');
     return withState((s) => scoreDeclared(s, {
@@ -150,10 +159,15 @@ const ACTIONS = {
       }
       note = raw.replace(/\r\n/g, '\n').trimEnd();
     }
-    const card = args.card ? JSON.parse(args.card) : null;
+    let card = null;
+    if (args.card) {
+      try { card = JSON.parse(args.card); } catch (e) {
+        throw new Error(`--card is not valid JSON: ${e.message}`, { cause: e });
+      }
+    }
     const porcelain = stdin();
     return withState((s, b) => recordOutcome(s, b, args.outcome, {
-      card, porcelain: porcelain ? porcelain.replace(/\r\n/g, '\n').trimEnd() : null, note,
+      card, porcelain: porcelain === null ? null : porcelain.replace(/\r\n/g, '\n').trimEnd(), note,
     }));
   },
   decide(args) {

package/js/loop/graph.mjs

@@ -21,7 +21,7 @@
  */
 import { WEIGHTS } from './score.mjs';
 
-export const TERMINALS = new Set(['$close', '$stop']);
+const TERMINALS = new Set(['$close', '$stop']);
 export const ENGINE_MAX_ITERATIONS = 20;
 /** A template's optional `category`, in the order the console's Loops list shows them. */
 export const CATEGORIES = ['architecture', 'tests', 'development', 'refactoring', 'day-to-day'];

package/js/loop/registry.mjs

@@ -7,7 +7,8 @@
  * WRITER CONVENTIONS, mirrored from `js/inspect/registry.mjs` (`installs.json`'s own registry)
  * on purpose rather than invented fresh: `jsonDumpsIndent` because these rows are absolute
  * paths and a username carrying an accent writes one here (ensure_ascii matters); a
- * `<file>.tmp` + `renameSync` so a crash mid-write cannot leave `loops.json` half-written where
+ * `<file>.tmp` + `renameWithRetry` (LOOP.md's own atomic rename, retried on a transient Windows
+ * lock) so a crash mid-write cannot leave `loops.json` half-written where
  * the NEXT read would see valid-but-truncated JSON instead of either the old file or the new
  * one; and every public function swallows its own errors — a registry hiccup must never fail
  * `loop init`, and a corrupt `loops.json` must read back as empty rather than throw. The one
@@ -28,20 +29,20 @@
  * re-`init`ed) clears it, so a stale finished-window never survives into a loop that is running
  * again.
  *
- * `recordLoop` and `activeLoops`/`setLoopPreset` never call each other's normalisation by
- * accident: both resolve a root through `realpathSync.native` (falling back to `path.resolve`
- * for a root that no longer exists) and compare with `normcase` — the same case-folding
- * `js/lib/paths.mjs` uses everywhere a Windows path is compared — so a loop launched from a
- * differently-cased spelling of the same worktree is still one row, not two.
+ * `recordLoop` and `setLoopPreset` resolve the root they are given the same way — `normalize`:
+ * `realpathSync.native`, falling back to `path.resolve` for a root that no longer exists — and
+ * compare it with `normcase`, the same case-folding `js/lib/paths.mjs` uses everywhere a Windows
+ * path is compared, so a loop launched from a differently-cased spelling of the same worktree is
+ * still one row, not two. `activeLoops` compares nothing: it reads each row's root as stored.
  */
-import { readFileSync, mkdirSync, realpathSync, renameSync } from 'node:fs';
+import { readFileSync, mkdirSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 
 import { userLoopsDir } from './catalog.mjs';
 import { writeText, readText, isDir, isFile } from '../lib/fs.mjs';
 import { parseJson, jsonDumpsIndent } from '../lib/json.mjs';
 import { normcase } from '../lib/paths.mjs';
-import { parseLoopFile, writeLoopFile, LOOP_FILE } from './state.mjs';
+import { parseLoopFile, writeLoopFile, renameWithRetry, reviewOf, LOOP_FILE } from './state.mjs';
 import { PRESETS } from './score.mjs';
 
 const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
@@ -65,7 +66,7 @@ function save(loops) {
     mkdirSync(path.dirname(file), { recursive: true });
     const tmp = `${file}.tmp`;
     writeText(tmp, `${jsonDumpsIndent({ loops })}\n`);
-    renameSync(tmp, file);
+    renameWithRetry(tmp, file);
   } catch {
     /* best-effort: a registry hiccup must never fail init or a read */
   }
@@ -77,12 +78,6 @@ function normalize(dir) {
 
 const sameRoot = (a, b) => normcase(a) === normcase(b);
 
-/** The soft-decision iterations of `state.history` — the same shape `state.mjs`'s own
- * end-of-run `summary()` reports, so a card and a finished-loop review read the same fields. */
-function reviewOf(state) {
-  return state.history.filter((h) => h.decision === 'soft').map((h) => ({ iteration: h.iteration, intent: h.intent }));
-}
-
 function runningRow(entry, state) {
   return {
     root: entry.root, branch: entry.branch, title: entry.title, started: entry.started,

package/js/loop/score.mjs

@@ -29,7 +29,7 @@ export const PRESETS = Object.freeze({
 export const DEFAULT_PRESET = 'balanced';
 
 /** More deleted lines than this in one iteration counts as a code deletion. */
-export const DELETION_LINES = 20;
+const DELETION_LINES = 20;
 
 const RANK = { silent: 0, soft: 1, blocking: 2 };