geneseed 3.1.1 → 3.1.2

package/js/{inventory.mjs → inspect/inventory.mjs}

@@ -1,15 +1,17 @@
 /**
- * `rituals/_harness_tui.py`'s CATALOG half — the taxonomy tables, the rendered-laws
+ * The CATALOG surface — the taxonomy tables, the rendered-laws
  * parser, the entity registry, and the render-accurate inventory the TUI, the `status`
  * panel and the web console all read.
  *
  * WHY THIS FILE EXISTS RATHER THAN A THIRD COPY OF THE TABLES. `LAW_CLASS`, `SKILL_CLASS`,
- * `LAW_CLASSES` and `ENTITY_STATUSES` crossed in P5g, inside `js/doctor.mjs`, because
- * doctor's authoring gates are what validate them — and `js/status.mjs`'s docblock said
+ * `LAW_CLASSES` and `ENTITY_STATUSES` crossed in P5g, inside `js/inspect/doctor.mjs`, because
+ * doctor's authoring gates are what validate them — and `js/inspect/status.mjs`'s docblock said
  * flatly that "the taxonomy P7 owns" was not ported, which was true of `_parse_laws` and
  * `entity_status` and had stopped being true of the tables. P6c needs all of it, so the
- * tables move HERE, to the module that mirrors where Python keeps them, and `js/doctor.mjs`
- * imports them. A copy of a value under test silently stops being the value under test.
+ * tables move HERE, to the module that mirrors where Python keeps them, and the doctor's
+ * check modules import them — `checks-authoring.mjs` takes `LAW_CLASS`, `LAW_CLASSES` and
+ * `SKILL_CLASS`, `checks-repo.mjs` takes `ENTITY_STATUSES`. A copy of a value under test
+ * silently stops being the value under test.
  *
  * AND `inventoryCounts` FOLDS BACK INTO `tuiInventory`. P5d shipped a counting-only twin
  * with a docblock warning that the two must not become two classifiers; this is the phase
@@ -21,17 +23,18 @@
  */
 import path from 'node:path';
 
-import { ROOT, SRC, makeCfg, PACK_ORDER } from './checkout.mjs';
-import { firstBlockquote } from './native.mjs';
-import { renderAll } from './render.mjs';
-import { pyResolve } from './hosts.mjs';
-import { parseJson, readText } from './lib/fs.mjs';
+import { ROOT, SRC, makeCfg, PACK_ORDER } from '../build/source.mjs';
+import { firstBlockquote } from '../hosts/native.mjs';
+import { renderAll } from '../build/render.mjs';
+import { resolvePath } from '../hosts/hosts.mjs';
+import { readText } from '../lib/fs.mjs';
+import { parseJson } from '../lib/json.mjs';
 
 /**
  * `_harness_tui.LAW_HEADING_RE` — a heading in the RENDERED laws file, e.g.
  * `### Rule IV — Deletion Is Deliberate`.
  *
- * Not `js/doctor.mjs`'s `LAW_HEADING_RE`, which matches the `{{LAW}}` token in the
+ * Not `js/inspect/checks-authoring.mjs`'s `LAW_HEADING_RE`, which matches the `{{LAW}}` token in the
  * unrendered source. Two patterns, two inputs, two names in Python as well.
  */
 export const LAW_HEADING_RE = /^###\s+\S+\s+([IVXLCDM]+)\s+[—-]\s+(.+?)\s*$/;
@@ -173,7 +176,7 @@ export function parseDoctrines(text) {
  *
  * `id` is the slugified title, and it is an ADDRESS: `#/item/law/ont:telos` is how the console
  * deep-links a section, so it has to survive a theme change. It does, because the four titles
- * come from `STRUCTURE` in `js/render.mjs` and not from any theme file — the same reason a
+ * come from `STRUCTURE` in `js/build/render.mjs` and not from any theme file — the same reason a
  * citation can spell itself `({{ONTOLOGY}}: {{ONT_TELOS}})` with a token on both sides.
  *
  * The preamble above the first `####` is dropped, as in the two parsers above. It is the
@@ -202,7 +205,7 @@ export function parseOntology(text) {
  *
  * Deliberately forgiving on BOTH failure modes, as the reference is: a missing file and a
  * corrupt one both yield `{}`, which reads every badge as "unknown" rather than breaking
- * the browser. `registryProblems` in `js/doctor.mjs` is the loud reader of the same file
+ * the browser. `registryProblems` in `js/inspect/checks-repo.mjs` is the loud reader of the same file
  * and stays separate — the two answer different questions.
  */
 export function loadRegistry() {
@@ -265,7 +268,7 @@ export function tuiInventory(themeName, doctrines = null, excluded = []) {
     const name = two ? parts[1].slice(0, -3) : null;
     if (two && (parts[0] === 'agents' || parts[0] === 'skills')) {
       const entry = { name, desc: firstBlockquote(text), body: text,
-        source: pyResolve(src), status: entityStatus(registry, `${parts[0]}/${name}`) };
+        source: resolvePath(src), status: entityStatus(registry, `${parts[0]}/${name}`) };
       if (parts[0] === 'agents') agents.push(entry);
       else {
         entry.klass = has(SKILL_CLASS, name) ? SKILL_CLASS[name] : 'build';
@@ -279,12 +282,12 @@ export function tuiInventory(themeName, doctrines = null, excluded = []) {
     if (two && parts[0] === 'doctrines') {
       const lead = text.split('\n').map((l) => PACK_LEAD_RE.exec(l)).find(Boolean);
       packs.set(name, { pack: name, title: lead ? lead[1] : name, desc: lead ? lead[2] : '',
-        source: pyResolve(src), rules: parseDoctrines(text) });
+        source: resolvePath(src), rules: parseDoctrines(text) });
     }
     // Scoped to the laws dir, not matched on the basename: `src/ontology/universal.md`
     // shares the name, sorts after `laws/`, and would clobber the parse with `[]` —
     // `LAW_HEADING_RE` wants `###` and the ontology uses `####`. Same spelling as the
-    // already-scoped sites at `js/render.mjs`'s `rel === 'laws/universal.md'`.
+    // already-scoped sites at `js/build/render.mjs`'s `rel === 'laws/universal.md'`.
     if (parts.join('/') === 'laws/universal.md') laws = parseLaws(text);
     if (parts.join('/') === 'ontology/universal.md') ontology = parseOntology(text);
   }
@@ -294,7 +297,7 @@ export function tuiInventory(themeName, doctrines = null, excluded = []) {
   // ⚠ `PACK_ORDER` IS THE SINGLE OWNER OF THE SET, and of its order. Filtering the order by
   // what was found — rather than publishing what was found — is what keeps `README.md` and any
   // other stray `.md` in that directory out of the catalogue, and it is the same membership
-  // rule `js/render.mjs` refuses the build over, so a fifth pack cannot be silently dropped
+  // rule `js/build/render.mjs` refuses the build over, so a fifth pack cannot be silently dropped
   // here either. Order because `sortedSourceFiles` walks alphabetically, which puts `ops`
   // second: the narrative order is the reading order, and it is what the marker line, the
   // wizard and the rendered section all use.

package/js/{registry.mjs → inspect/registry.mjs}

@@ -1,15 +1,15 @@
 /**
  * `_install_registry.py` — the persistent list of folders a harness was deployed into.
  *
- * MOVED OUT OF `bin/geneseed.mjs` IN P5f, for the third time the same arithmetic has decided
+ * MOVED OUT OF `bin/build-driver.mjs` IN P5f, for the third time the same arithmetic has decided
  * a module boundary in this port (P5c took the host resolvers, P5d the checkout paths). The
  * driver WRITES the registry, one row per per-repo emit; `harness rebuild-all` READS it to
  * find every install it must re-emit, and `bin/geneseed-cli.mjs` may not reach into a driver
- * for a reader. `js/generate.mjs` importing `main` from `bin/geneseed.mjs` is not a
+ * for a reader. `js/build/generate.mjs` importing `main` from `bin/build-driver.mjs` is not a
  * precedent for it either: `harness build` IS the driver, and a registry reader is not.
  *
- * The move is licensed the same way the two before it were: `tests/golden.py` drives
- * `bin/geneseed.mjs` over 259 cells with `$XDG_CONFIG_HOME` redirected into the sandbox and
+ * The move is licensed the same way the two before it were: `tests/golden.mjs` drives
+ * `bin/build-driver.mjs` over 259 cells with `$XDG_CONFIG_HOME` redirected into the sandbox and
  * compares `installs.json` byte-for-byte, so a changed path or a dropped prune fails cells
  * rather than passing quietly.
  */
@@ -17,8 +17,10 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync
 import path from 'node:path';
 import os from 'node:os';
 
-import { expanduser } from './hosts.mjs';
-import { writeText, parseJson, jsonDumpsIndent, pyPathStr } from './lib/fs.mjs';
+import { expanduser } from '../hosts/hosts.mjs';
+import { writeText } from '../lib/fs.mjs';
+import { parseJson, jsonDumpsIndent } from '../lib/json.mjs';
+import { toPlatformPath } from '../lib/paths.mjs';
 
 const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
 const isFile = (p) => { try { return statSync(p).isFile(); } catch { return false; } };
@@ -53,7 +55,7 @@ export function registrySave(items) {
  *
  * `realpathSync` rather than `path.resolve`, because Python's `Path.resolve()` returns the
  * filesystem's own casing and follows links; `path.resolve` only makes a path absolute. The
- * registry is compared byte-for-byte by `tests/golden.py` (XDG is redirected into the
+ * registry is compared byte-for-byte by `tests/golden.mjs` (XDG is redirected into the
  * sandbox), so a differently-cased entry is a failing cell.
  */
 export function registryRecord(dir) {
@@ -80,20 +82,20 @@ export function registryRoots() {
   const kept = [];
   const seen = new Set();
   for (const s of original) {
-    // `Path(s).expanduser()`, and `pyPathStr` is the `str()` around it — which is where the
+    // `Path(s).expanduser()`, and `toPlatformPath` is the `str()` around it — which is where the
     // NORMALISATION happens. Python turns `C:/x/other` into `C:\x\other` before it is
     // compared, kept, returned and printed, so a registry entry spelled with forward slashes
     // (routine: every tool that writes one from Git Bash) makes Python rewrite the file and
     // print a backslash path while a raw `expanduser` prints the entry verbatim and leaves
     // installs.json alone. Invisible to every cell before P5h, because `rebuild-all`'s
     // registry cells seed native spellings; `uninstall`'s inventory prints the root.
-    // `expanduser` now REFUSES a `~user` entry (js/hosts.mjs's docblock) instead of passing
+    // `expanduser` now REFUSES a `~user` entry (js/hosts/hosts.mjs's docblock) instead of passing
     // it through. This loop scans STORED registry rows, not a fresh CLI argument — a single
     // bad row (hand-edited, or written before this refusal existed) must not abort the scan
     // for every other install, so it is dropped exactly like any other dead row rather than
     // propagated. `rebuild-all`'s contract is "one broken install never blocks the rest".
     let root;
-    try { root = pyPathStr(expanduser(s)); } catch { continue; }
+    try { root = toPlatformPath(expanduser(s)); } catch { continue; }
     let key;
     try { key = existsSync(root) ? realpathSync.native(root) : root; } catch { key = root; }
     if (seen.has(key)) continue;

package/js/inspect/scan.mjs

@@ -0,0 +1,125 @@
+/**
+ * `_harness_core`'s scanning primitives — what every doctor check reads the tree with.
+ *
+ * Split out of `doctor.mjs` because all three check modules need them and none of the three
+ * owns them. Nothing here decides anything: these walk, sort, strip and test, and the
+ * judgement lives in `checks-build.mjs`, `checks-repo.mjs` and `checks-authoring.mjs`.
+ *
+ * `NOTE` and `isDoctorNote` sit here for the same reason — a check in any of the three
+ * marks an advisory line with the prefix, and the driver in `doctor.mjs` reads it back.
+ */
+import os from 'node:os';
+import path from 'node:path';
+import { SRC } from '../build/source.mjs';
+import { comparePaths, normcase } from '../lib/paths.mjs';
+import { mkdtempSync, readdirSync, rmSync, statSync } from 'node:fs';
+
+// --------------------------------------------------------------------------------------
+// _harness_core's scanning primitives
+// --------------------------------------------------------------------------------------
+
+/** `_harness_core.TOKEN_RE` / `LINK_RE` / `ABS_LINK_RE`. `g` where `findall` is used. */
+// Must stay in step with `js/build/render.mjs`'s TOKEN_RE: a token the renderer substitutes but this
+// scan cannot see is an unresolved-token gate that silently stops gating. Digits are legal after
+// the first character for `DOC_<PACK>_<n>`; a leading digit is still not a token.
+export const TOKEN_RE = /\{\{[A-Z_][A-Z0-9_]*\}\}/g;
+export const LINK_RE = /\]\((?!https?:\/\/|#)([^)]+)\)/g;
+export const ABS_LINK_RE = /^([A-Za-z]:[\\/]|\/|~)/;
+const FENCE_RE = /```[\s\S]*?```/g;
+const INLINE_CODE_RE = /`[^`]*`/g;
+const COMMENT_RE = /<!--[\s\S]*?-->/g;
+
+/** `_harness_core.strip_code` — fenced blocks, inline code and HTML comments, in that order. */
+export function stripCode(text) {
+  return text.replace(FENCE_RE, '').replace(COMMENT_RE, '').replace(INLINE_CODE_RE, '');
+}
+
+/**
+ * `_harness_core._within` — `child.relative_to(parent)` without the exception.
+ *
+ * Segment-wise and through `normcase`, because that is what `PurePath` comparison does: a
+ * bundle at `C:\Temp\X` contains `c:\temp\x\a.md` on Windows and does not on Linux. A
+ * `startsWith` on the raw strings would additionally call `/tmp/bundle2` a child of
+ * `/tmp/bundle`, which is the classic version of this bug.
+ */
+export function within(child, parent) {
+  const c = normcase(child).split(/[\\/]/);
+  const p = normcase(parent).split(/[\\/]/);
+  return p.length <= c.length && p.every((seg, i) => c[i] === seg);
+}
+
+export const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+export const isFile = (p) => { try { return statSync(p).isFile(); } catch { return false; } };
+
+/** `sorted(d.glob(pat))`, or `[]` for a directory that is not there. */
+export function globSorted(dir, filter) {
+  let names;
+  try { names = readdirSync(dir); } catch { return []; }
+  return names.filter(filter).map((n) => path.join(dir, n)).sort(comparePaths);
+}
+
+/** `Path.rglob('*')` — every entry under `dir`, sorted as `sorted()` sorts paths. */
+export function rglob(dir) {
+  const out = [];
+  const walk = (d) => {
+    let entries;
+    try { entries = readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries.map((x) => x.name).sort(comparePaths)) {
+      const p = path.join(d, e);
+      out.push(p);
+      if (isDir(p)) walk(p);
+    }
+  };
+  walk(dir);
+  return out.sort(comparePaths);
+}
+
+// `withDiscardableStderr` was defined here while `renderedProblems` was its only caller.
+// `js/hosts/hooks.mjs` became the second and third when the hook started CATCHING `expanduser`'s
+// refusal, so it moved beside `printErr` in `js/lib/fs.mjs` — the writes it intercepts —
+// and its docblock carries the "not for silencing noise" warning with it.
+
+/** `Path.stem` — the basename with its last suffix removed. */
+export const stemOf = (p) => path.basename(p, path.extname(p));
+
+/** `sorted(set)` over strings, the ordering every problem list is emitted in. */
+export const sortedUnique = (xs) => [...new Set(xs)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+/** `sorted(probs)` — SORTED, not deduped, which is what `_ran` fills a group with. */
+export const sortedProblems = (xs) => [...xs].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+
+/**
+ * `k in d` for a Python dict — OWN keys only.
+ *
+ * Every membership test in this file reads a key that came out of a JSON document or a source
+ * filename, and a bare `k in obj` would answer true for `constructor`, `toString` and the rest
+ * of `Object.prototype`. A theme defining a `toString` voice token, or a skill file named
+ * `valueOf.md`, would then be reported as missing by the reference and not by this port — a
+ * divergence no cell can reach and no reviewer would look for.
+ */
+export const has = (obj, k) => Object.prototype.hasOwnProperty.call(obj, k);
+
+/** `_harness_build._src_stems` — spec stems under `src/<folder>`, minus `_`-scaffolds. */
+export function srcStems(folder) {
+  const d = path.join(SRC, folder);
+  if (!isDir(d)) return new Set();
+  return new Set(globSorted(d, (n) => n.endsWith('.md') && !n.startsWith('_')).map(stemOf));
+}
+
+/**
+ * A line reported by the doctor that is NOT a failure — `[note] …` rather than `[authoring] …`.
+ *
+ * ⚠ ONE PRODUCER, AND IT IS THE ONLY THING THAT NEEDED A SECOND CHANNEL. A build with a
+ * doctrine pack off is LEGAL, and it leaves body prose citing rules that pack owns. That state
+ * has to be visible — a silent dangling citation is how prose and boundary drift apart — but
+ * reporting it as a problem would make `doctor` exit 1 over a configuration its owner chose.
+ * So `cmdDoctor` prints notes and does not count them.
+ */
+export const NOTE = '[note] ';
+export const isDoctorNote = (p) => p.startsWith(NOTE);
+
+/** `tempfile.TemporaryDirectory()` — created, handed to `fn`, removed whatever happens. */
+export function withTempDir(fn, prefix = 'geneseed-doctor-') {
+  const tmp = mkdtempSync(path.join(os.tmpdir(), prefix));
+  try { return fn(tmp); } finally { rmSync(tmp, { recursive: true, force: true }); }
+}
+

package/js/{status.mjs → inspect/status.mjs}

@@ -30,7 +30,7 @@
  *
  * WHERE THE DETECTORS WENT. `themeOfDir`, `footprintOfDir`, `installedDefaults`,
  * `manifestIsClaude` and the configured defaults were written here in P5d because `status`
- * was their only caller. `js/installs.mjs` owns them since P5f, when `diff` and `rebuild-all`
+ * was their only caller. `js/hosts/installs.mjs` owns them since P5f, when `diff` and `rebuild-all`
  * became the second and third. Nothing about them changed in the move — the 166-cell
  * acceptance matrix is what licensed attempting it, `status`'s own eleven cells among them.
  *
@@ -41,10 +41,11 @@
  * know), `accentFor`'s cyan fallback (an unknown theme is refused upstream by
  * `effectiveTheme`), and the whole ANSI half of `statusLines` (`_color_enabled` is
  * `sys.stdout.isatty()`, and every harness captures stdout through a pipe). All three are
- * PURE FUNCTIONS of their arguments, so all three are gated as a corpus in
- * `tests/test_pure_function_parity.py` instead — which is a third answer to the colour
- * question the P5c handoff posed as a choice between shipping it ungated and not shipping
- * it.
+ * PURE FUNCTIONS of their arguments, so all three are gated as a corpus instead:
+ * `tests/fixtures/pure_probe.mjs` calls them and `tests/snapshot/pure_snapshot.test.mjs`
+ * replays that against `tests/__snapshots__/primitives/`. That was a third answer to the
+ * colour question, which had been posed as a choice between shipping it ungated and not
+ * shipping it.
  *
  * `manifestIsClaude` was a FOURTH until wave 2 of the P0/P1 review: it is only reached for
  * a candidate with no known host, and `ROOT/"Harness"` was ordered ahead of the sandbox's
@@ -56,13 +57,13 @@
 import { existsSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 
-import { THEMES, ROOT, makeCfg } from './checkout.mjs';
+import { THEMES, ROOT, makeCfg } from '../build/source.mjs';
 import { tuiInventory } from './inventory.mjs';
-import { readVersion, sourceFingerprint } from './emit.mjs';
+import { readVersion, sourceFingerprint } from '../build/version.mjs';
 import {
-  claudeConfigDir, bobConfigDir, copilotConfigDir, opencodeConfigDir, pyResolve,
+  claudeConfigDir, bobConfigDir, copilotConfigDir, opencodeConfigDir, resolvePath,
   resolveMemoryDir,
-} from './hosts.mjs';
+} from '../hosts/hosts.mjs';
 // P5f moved the install DETECTORS out of this file — `diff` renders its expected copy in the
 // deployed theme and footprint, and `rebuild-all` re-emits in the deployed everything, so
 // three verbs now read them. `defaultTheme`, `manifestIsClaude` and `installedDefaults` are
@@ -70,8 +71,9 @@ import {
 // and a corpus that followed the code to its new file would stop testing the caller's view.
 import {
   defaultTheme, installedDefaults, manifestIsClaude, readJsonMaybe, readMaybe,
-} from './installs.mjs';
-import { pyLen, pyLjust, pyPrint } from './lib/fs.mjs';
+} from '../hosts/installs.mjs';
+import { printOut } from '../lib/fs.mjs';
+import { codePointLength, padEndToWidth } from '../lib/text.mjs';
 
 export { defaultTheme, manifestIsClaude };
 
@@ -91,9 +93,9 @@ export function versionVerdict(installed, current) {
 export function cmdVersion(args) {
   const cfg = makeCfg();
   const current = sourceFingerprint(cfg);
-  // `Path(args.target).expanduser().resolve()` — `pyResolve` already expands, so the tilde
+  // `Path(args.target).expanduser().resolve()` — `resolvePath` already expands, so the tilde
   // is handled once rather than twice.
-  let target = args.target ? pyResolve(args.target) : opencodeConfigDir();
+  let target = args.target ? resolvePath(args.target) : opencodeConfigDir();
   let installed = readVersion(target);
   if (installed === null) {
     // A claude/bob/copilot-only machine must not report "no install detected". The bundle
@@ -104,10 +106,10 @@ export function cmdVersion(args) {
       if (v) { installed = v; target = base; break; }
     }
   }
-  pyPrint(`[version] source:    ${current}   (${ROOT})\n`);
-  pyPrint(`[version] installed: ${installed || '(none found)'}`
+  printOut(`[version] source:    ${current}   (${ROOT})\n`);
+  printOut(`[version] installed: ${installed || '(none found)'}`
     + (installed ? `   (${target})` : '') + '\n');
-  pyPrint(`[version] ${versionVerdict(installed, current)}\n`);
+  printOut(`[version] ${versionVerdict(installed, current)}\n`);
   return 0;
 }
 
@@ -121,7 +123,7 @@ export function cmdVersion(args) {
  * and porting them to produce three integers would have been absurd — with a docblock
  * warning that the two must not become two classifiers. `api_catalog` consumes exactly the
  * fields the count threw away, so P6c is the phase that would have made them two. It did
- * not: `tuiInventory` in `js/inventory.mjs` is the one walk, this is three `length`s off
+ * not: `tuiInventory` in `js/inspect/inventory.mjs` is the one walk, this is three `length`s off
  * it, and the eleven `status` cells and the catalog cells now gate the same classifier
  * from opposite ends.
  */
@@ -294,29 +296,29 @@ export function statusLines(d, color = false) {
       `${d.agent_md}  (${d.agent_md_present ? 'present' : 'MISSING'})`]);
   }
 
-  const labelW = Math.max(...rows.map(([k]) => pyLen(k)));
-  const body = rows.map(([k, v]) => `  ${pyLjust(k, labelW)}   ${v}`);
+  const labelW = Math.max(...rows.map(([k]) => codePointLength(k)));
+  const body = rows.map(([k, v]) => `  ${padEndToWidth(k, labelW)}   ${v}`);
   const verdict = `  ${mark} ${d.version_verdict}`;
   const title = ` ${badge} Geneseed ${emdash} status `;
-  const width = Math.max(...body.map(pyLen), pyLen(verdict), pyLen(title) + 2);
+  const width = Math.max(...body.map(codePointLength), codePointLength(verdict), codePointLength(title) + 2);
 
   const ac = ANSI_CODES[d.accent] ?? '36';
   const c = (s, code) => (color ? `\x1b[${code}m${s}\x1b[0m` : s);
 
   const top = color
-    ? c(TL + H, ac) + c(title, `${ac};1`) + c(H.repeat(width - pyLen(title) - 1) + TR, ac)
-    : TL + H + title + H.repeat(width - pyLen(title) - 1) + TR;
+    ? c(TL + H, ac) + c(title, `${ac};1`) + c(H.repeat(width - codePointLength(title) - 1) + TR, ac)
+    : TL + H + title + H.repeat(width - codePointLength(title) - 1) + TR;
   const edge = c(V, ac);
   const lines = [top];
-  for (const b of body) lines.push(edge + pyLjust(b, width) + edge);
+  for (const b of body) lines.push(edge + padEndToWidth(b, width) + edge);
   lines.push(c(LT + H.repeat(width) + RT, ac));
-  lines.push(edge + c(pyLjust(verdict, width), vcode) + edge);
+  lines.push(edge + c(padEndToWidth(verdict, width), vcode) + edge);
   lines.push(c(BL + H.repeat(width) + BR, ac));
   return lines;
 }
 
 /** `_harness_status.cmd_status`. */
 export function cmdStatus() {
-  for (const line of statusLines(statusData(), colorEnabled())) pyPrint(`${line}\n`);
+  for (const line of statusLines(statusData(), colorEnabled())) printOut(`${line}\n`);
   return 0;
 }

package/js/inspect/validate.mjs

@@ -0,0 +1,199 @@
+/**
+ * `validate` — the generator's old `--validate-only`, on this binary because it runs the
+ * doctor's scans over a sandbox it renders first.
+ *
+ * Split out of `doctor.mjs`, where it already sat behind a banner of its own. It is a
+ * separate VERB with a separate exit contract, and it is the one verb no recorded cell ever
+ * reached — see its row in `tests/ported.json`.
+ */
+import path from 'node:path';
+import { buildInto, emitGlobalInto, emitProjectInto } from '../../bin/build-driver.mjs';
+import { resolvePath } from '../hosts/hosts.mjs';
+import { validateIsVendored } from '../hosts/native.mjs';
+import { printOut, printErr, readText } from '../lib/fs.mjs';
+import { comparePaths } from '../lib/paths.mjs';
+import { stripWhitespace } from '../lib/text.mjs';
+import { linkProblems } from './checks-build.mjs';
+import { cmdDoctor } from './doctor.mjs';
+import { TOKEN_RE, isDir, isFile, rglob, sortedUnique, withTempDir, within } from './scan.mjs';
+
+// --------------------------------------------------------------------------------------
+// validate  —  the generator's `--validate-only`, on this binary because it runs the doctor
+// --------------------------------------------------------------------------------------
+
+/**
+ * `build._validate_sandbox_problems` — the unresolved-token / dead-link / non-hermetic-link
+ * scan over an already-rendered sandbox tree.
+ *
+ * A NEAR-TWIN OF `checkBuild` ABOVE, AND DELIBERATELY NOT IT, because the reference is two
+ * functions and they differ in three observable ways: the token list is `sorted(set(...))`
+ * here and bare `set(...)` there, the message carries no `[theme]` prefix (the caller adds
+ * `[emit]` instead), and an unreadable file is SKIPPED rather than raised. Python duplicates
+ * the loop because `build.py` cannot import the harness tree; here the two live in one file
+ * and the two now sit one file apart (`checkBuild` is in `checks-build.mjs`); the
+ * duplication is eight lines — every primitive underneath (`rglob`, `stripCode`,
+ * `linkProblems`, `readText`) is the shared one, which is the half that could actually drift.
+ */
+export function validateSandboxProblems(sandbox) {
+  const out = resolvePath(sandbox);
+  const problems = [];
+  for (const md of rglob(out)) {
+    if (!md.endsWith('.md') || !isFile(md)) continue;
+    const rel = path.relative(out, md);
+    if (validateIsVendored(rel)) continue;
+    let text;
+    // `except (OSError, UnicodeDecodeError): continue` — binary or unreadable, nothing here.
+    try { text = readText(md); } catch { continue; }
+    for (const tok of sortedUnique(text.match(TOKEN_RE) ?? [])) {
+      problems.push(`unresolved token ${tok} in ${rel}`);
+    }
+    problems.push(...linkProblems(md, text, out, rel));
+  }
+  return problems;
+}
+
+/**
+ * `subprocess.run(..., capture_output=True, text=True)` around an IN-PROCESS call.
+ *
+ * The reference shells to `harness.py doctor`; this calls `cmdDoctor` directly, and the
+ * difference has to be undone in one place: a child's `capture_output` hands the parent
+ * UNIVERSAL-NEWLINE text, so `r.stdout` holds `\n` on Windows even though the child wrote
+ * `\r\n`. `printOut` inside `cmdDoctor` writes `\r\n`. Without the fold, the `.strip()` below
+ * would leave every interior line CRLF and the re-print would double the translation.
+ */
+function captureStreams(fn) {
+  const chunks = { out: [], err: [] };
+  const realOut = process.stdout.write.bind(process.stdout);
+  const realErr = process.stderr.write.bind(process.stderr);
+  process.stdout.write = (c) => { chunks.out.push(String(c)); return true; };
+  process.stderr.write = (c) => { chunks.err.push(String(c)); return true; };
+  let code;
+  try {
+    code = fn();
+  } finally {
+    process.stdout.write = realOut;
+    process.stderr.write = realErr;
+  }
+  const decode = (xs) => xs.join('').replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+  return { code, out: decode(chunks.out), err: decode(chunks.err) };
+}
+
+/**
+ * `build._validate_only` — render + emit the requested target into a throwaway sandbox, run
+ * every validation a real build would gate on, print what WOULD have been written, and return
+ * the exit code. Nothing under the sandbox survives, and no marker, manifest or registry row
+ * is ever written for real.
+ *
+ * WHY IT IS HERE AND NOT ON THE GENERATOR DRIVER, which is where its flag lives. The
+ * source-tree half of the check IS the doctor, and this module starts a process (`node --check`
+ * over the OpenCode plugins). `bin/build-driver.mjs` is under a transitive ban on reaching any
+ * module that can, gated by `tests/unit/hook_cli.test.mjs`, which walks the driver's TRANSITIVE
+ * imports rather than grepping its own source — a source grep walks straight past an
+ * `import … from './x.mjs'` that reaches child_process. Siting the tool on the CLI
+ * binary, which already carries the doctor, crosses it with neither gate amended and without
+ * the dynamic `import()` that would evade the walk.
+ *
+ * THE MARKER GUARANTEE COMES FREE, and that is why `emitProjectInto`/`emitGlobalInto`/
+ * `buildInto` are used rather than `driverMain(['--emit', …])`: the driver writes
+ * `.geneseed-emit`/`.geneseed-footprint` and records an install-registry row AFTER the
+ * dispatch, so routing through it would register a temp directory that is deleted a
+ * millisecond later. The reference calls the emit functions directly for the same reason.
+ *
+ * THE EMIT'S OWN STDOUT IS NOT SWALLOWED. `globalEmitProblems` above wraps its call in
+ * `swallowStdout` and this deliberately does not: `_validate_only` has no `redirect_stdout`,
+ * so the ~200 lines of emit summary ARE part of what a dry run shows the operator.
+ *
+ * NO CELL REACHES THIS. The recorded corpus's argv never emitted `--validate-only`, so the
+ * flag was ungated across implementations for the whole port. What holds it now is
+ * `tests/unit/generate.test.mjs`, which drives `cmdValidate` directly and asserts its exit
+ * contract absolutely — this verb is deliberately outside the verb table, so nothing else does.
+ */
+export function cmdValidate(args) {
+  const problems = [];
+  const scan = withTempDir((tmpRaw) => {
+    // `.resolve()` mirrors `_check_build`'s: on Windows a temp dir can come back in 8.3
+    // short form (`RUNNER~1`) while every link TARGET below is resolved long-form, and
+    // `within` then rejects every relative link rather than only the escaping ones.
+    const tmp = resolvePath(tmpRaw);
+    // With a distinct `--root` the per-repo emits split their output — the bundle under
+    // `out`, the native layer under `root` — so the sandbox bundle nests INSIDE the sandbox
+    // root and the scan covers both layers.
+    const root = args.root ? path.join(tmp, 'root') : path.join(tmp, 'out');
+    const sandbox = args.root ? path.join(root, 'bundle') : root;
+    const cfgDir = path.join(tmp, 'cfg');
+    const emit = args.emit;
+    const opts = { theme: args.theme, footprint: args.footprint };
+    let scanDirs;
+    try {
+      if (emit.endsWith('-global')) {
+        emitGlobalInto(emit.slice(0, -'-global'.length), { ...opts, out: sandbox, cfgDir });
+        scanDirs = [cfgDir];
+      } else if (emit === 'files') {
+        buildInto({ ...opts, out: sandbox });
+        scanDirs = [sandbox];
+      } else {
+        emitProjectInto(emit, { ...opts, out: sandbox, root });
+        scanDirs = [root];
+      }
+    } catch (e) {
+      // `except SystemExit as e` — a DELIBERATE refusal from the render (an unknown theme,
+      // an incomplete source), interpolated as `{e}`.
+      //
+      // THE EXIT CODE AND NOT THE MESSAGE, measured rather than assumed: the reference's
+      // render half is ALREADY this port. `_build_render.build` calls `_build_core.run_node`,
+      // which ends `raise SystemExit(res.get("exit", 1))` — an INTEGER — so every refusal
+      // that crosses the seam arrives here as `SystemExit(1)` and `str(e)` is `'1'`, not the
+      // sentence `load_theme` wrote on stderr on the way out. A port that printed `e.message`
+      // says `unknown theme 'x'` where the reference says `1`. The corpus in
+      // `tests/test_maintainer_tools_parity.py` is what found it; nothing else could.
+      if (e && e.exitCode !== undefined) {
+        printOut(`[validate-only] render/emit FAILED for theme '${args.theme}' `
+          + `emit '${emit}': ${e.exitCode}\n`);
+        return null;
+      }
+      throw e;
+    }
+
+    const written = scanDirs.filter(isDir).flatMap((d) => rglob(d)).filter(isFile)
+      .sort(comparePaths);
+    printOut(`[validate-only] theme=${args.theme} emit=${emit} `
+      + `footprint=${args.footprint}\n`);
+    printOut(`[validate-only] would write ${written.length} file(s) under ${args.out}`
+      + (args.root ? ` (root ${args.root})` : '')
+      + ' — nothing was actually written (sandboxed).\n');
+    if (args.verbose) {
+      let base = scanDirs[0];
+      for (const p of written) {
+        for (const d of scanDirs) {
+          if (within(p, d)) { base = d; break; }
+        }
+        printOut(`  would write: ${path.relative(base, p)}\n`);
+      }
+    }
+    for (const d of scanDirs) {
+      for (const p of validateSandboxProblems(d)) problems.push(`[${emit}] ${p}`);
+    }
+    return scanDirs;
+  }, 'geneseed-validate-');
+  if (scan === null) return 1;
+
+  // The source-tree-wide checks (theme parity, authoring gates, AGENT.md table parity,
+  // colour themes) do not depend on --out/--root/--emit at all and already live fully tested
+  // in the doctor, so they run through it rather than being re-derived. The reference SHELLS
+  // to `harness.py doctor --theme T --no-bundle`; one process is what this port has.
+  const doctor = captureStreams(() => cmdDoctor({ theme: args.theme, noBundle: true }));
+  if (stripWhitespace(doctor.out)) printOut(`${stripWhitespace(doctor.out)}\n`);
+  if (stripWhitespace(doctor.err)) printErr(`${stripWhitespace(doctor.err)}\n`);
+  if (doctor.code !== 0) {
+    problems.push(`[doctor] source-tree validation failed for theme '${args.theme}' `
+      + '(see output above)');
+  }
+
+  if (problems.length) {
+    printOut(`[validate-only] ${problems.length} problem(s):\n`);
+    for (const p of problems) printOut(`  - ${p}\n`);
+    return 1;
+  }
+  printOut('[validate-only] ok — would render and emit cleanly, no problems found.\n');
+  return 0;
+}