geneseed 3.1.0 → 3.1.2

package/js/lib/json.mjs

@@ -0,0 +1,344 @@
+/**
+ * Quoting and the parsed-value model — `json.dumps`, `json.loads`, and the `str`/`repr`
+ * rules that decide what a parsed number renders as.
+ *
+ * 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.
+ *
+ * `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
+ * four cannot be separated from it without a cycle.
+ */
+/**
+ * A number as `json.loads` produced it, carrying the literal it was parsed from.
+ *
+ * `json.loads` yields an `int` for `20` and a `float` for `1.0`, and Python's `str()`
+ * renders those as `20` and `1.0`. `JSON.parse` collapses both to the IEEE double `1`,
+ * and `String(1.0)` is `"1"` — so an `agent-overrides.json` carrying `"temperature": 1.0`
+ * emits `temperature: 1.0` from Python and `temperature: 1` from Node.
+ *
+ * That divergence WAS invisible to the golden harness — the emit always writes an EMPTY
+ * overrides stub, so no golden cell ever had an override to render, and mutation M6 stood
+ * ungated for two phases because of it. What holds it now is
+ * `tests/unit/lib_primitives.test.mjs`, which round-trips `{"temperature": 1.0}` and requires
+ * the `1.0` back.
+ */
+class JsonNumber {
+  constructor(value, source) { this.value = value; this.source = source; }
+  valueOf() { return this.value; }
+  toString() { return formatValue(this); }
+
+  /**
+   * Re-serialising parsed JSON must round-trip the way Python's does. Without this,
+   * `JSON.stringify` would walk the wrapper and emit `{"value":1,"source":"1.0"}`.
+   * `JSON.rawJSON` (Node >= 21) writes the text verbatim, and `formatValue` supplies the text
+   * Python would have \u2014 NOT the original literal, because `json.dumps(json.loads('1.50'))`
+   * is `1.5`: Python re-formats through repr rather than echoing the source.
+   */
+  toJSON() { return JSON.rawJSON(formatValue(this)); }
+}
+
+/**
+ * `json.loads(text)`, preserving the int/float distinction (see `JsonNumber`).
+ *
+ * Uses the reviver's `context.source` (Node >= 21). Where it is unavailable the numbers
+ * come back bare and `formatValue` throws rather than formatting them wrongly — a loud failure
+ * on an old runtime beats bytes that differ from Python's only for some values.
+ */
+export function parseJson(text) {
+  return JSON.parse(text, function (key, value, context) {
+    return typeof value === 'number' && context && typeof context.source === 'string'
+      ? new JsonNumber(value, context.source)
+      : value;
+  });
+}
+
+/** `repr(float)` — the half of `formatValue` where the two languages disagree most. */
+function formatFloat(n) {
+  if (Number.isNaN(n)) return 'nan';
+  if (!Number.isFinite(n)) return n > 0 ? 'inf' : '-inf';
+  const a = Math.abs(n);
+  if (a !== 0 && (a >= 1e16 || a < 1e-4)) {
+    // Python leaves positional notation outside [1e-4, 1e16); JS's own thresholds are
+    // 1e-6 and 1e21, and it writes a one-digit exponent where Python pads to two.
+    const [mantissa, exp] = n.toExponential().split('e');
+    return `${mantissa}e${exp[0] === '-' ? '-' : '+'}${exp.slice(1).padStart(2, '0')}`;
+  }
+  // Both engines print the shortest round-tripping decimal, but JS drops the fractional
+  // part of an integral value: `String(1.0)` is '1' where `repr(1.0)` is '1.0'. And
+  // `String(-0)` is '0' where `repr(-0.0)` keeps the sign.
+  const s = Object.is(n, -0) ? '-0' : String(n);
+  return s.includes('.') || s.includes('e') ? s : `${s}.0`;
+}
+
+/**
+ * `str(value)` for a value that came out of `json.loads` — what an f-string interpolates.
+ *
+ * Only the types the generator actually renders are handled. A list, dict or bool reaching
+ * here would print as `[object Object]` / `true` where Python prints `[1, 2]` / `True`, so
+ * it throws instead: an override file with a value nobody has decided the semantics for is
+ * a question to answer, not a byte to guess at.
+ */
+export function formatValue(value) {
+  if (typeof value === 'string') return value;
+  if (value instanceof JsonNumber) {
+    // `json.decoder` picks parse_float for any literal carrying a fraction or an exponent
+    // and parse_int otherwise — so the literal, not the resulting double, is what decides.
+    // Ints are exact in Python at any width; BigInt keeps that (and normalises `-0`).
+    return /[.eE]/.test(value.source) ? formatFloat(value.value) : BigInt(value.source).toString();
+  }
+  if (typeof value === 'number') {
+    throw new TypeError(`formatValue got a bare number (${value}); parse JSON with parseJson so `
+      + `int 1 and float 1.0 stay distinguishable, as they are in Python`);
+  }
+  throw new TypeError(`formatValue has no Python-agreeing rendering for ${typeof value}`);
+}
+
+/**
+ * Python truthiness — `if value:` — for a value that came out of `json.loads`.
+ *
+ * `Boolean()` is not it, and the gap is not academic: a `JsonNumber` is an OBJECT, so
+ * `Boolean(JsonNumber(0))` is `true` where Python's `if 0` is false. In the other direction
+ * `Number('0')` is `0` where Python's `if "0"` is true. Both spellings appear in the
+ * override tests, so neither shortcut is safe.
+ */
+export function isTruthy(value) {
+  if (value === undefined || value === null || value === false) return false;
+  if (typeof value === 'string') return value !== '';
+  if (value instanceof JsonNumber) return value.value !== 0;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === 'object') return Object.keys(value).length > 0;
+  return Boolean(value);
+}
+
+/**
+ * `repr(value)` for the values a theme or an override file can hold.
+ *
+ * Python quotes strings with `'`, switching to `"` only when the string contains a `'`
+ * and no `"`, and spells the three singletons with a capital. Anything else is a
+ * container, whose repr differs structurally; guessing at a rendering would be worse
+ * than failing, so it falls through to `formatValue`.
+ *
+ * Lives here rather than beside its first caller because `formatReprAscii` below is the same
+ * function with one more escaping rule, and two copies of the quote choice would be two
+ * things to keep in agreement.
+ *
+ * Containers ARE rendered, unlike in `formatValue`, and the difference is not an inconsistency.
+ * `formatValue` interpolates into an emitted file, where a shape nobody decided the semantics
+ * for must be a question rather than a guessed byte. `repr` renders a value into a WARNING
+ * about that very value — a list in `.geneseed-srcdirs.json` is precisely what the warning
+ * exists to report, and throwing there would turn "this file is corrupt" into a crash. The
+ * value always came from JSON, so the type set is closed and the rendering is exact.
+ */
+function formatReprImpl(v, ascii) {
+  if (typeof v === 'string') {
+    let body = '';
+    for (const ch of v) {                 // by CODE POINT: `\U########` is one escape
+      const cp = ch.codePointAt(0);
+      if (ch === '\\') body += '\\\\';
+      else if (ch === '\n') body += '\\n';
+      else if (ch === '\r') body += '\\r';
+      else if (ch === '\t') body += '\\t';
+      else if (cp < 0x20 || cp === 0x7f) body += `\\x${cp.toString(16).padStart(2, '0')}`;
+      else if (cp < 0x7f) body += ch;
+      else if (!ascii) body += ch;        // repr() keeps printable non-ASCII verbatim
+      else if (cp <= 0xff) body += `\\x${cp.toString(16).padStart(2, '0')}`;
+      else if (cp <= 0xffff) body += `\\u${cp.toString(16).padStart(4, '0')}`;
+      else body += `\\U${cp.toString(16).padStart(8, '0')}`;
+    }
+    // The quote choice reads the ESCAPED body, which is safe: no escape sequence above
+    // introduces a quote character, so a `'` or `"` in it came from the input.
+    return body.includes("'") && !body.includes('"')
+      ? `"${body}"`
+      : `'${body.replaceAll("'", "\\'")}'`;
+  }
+  if (v === null) return 'None';
+  if (v === true) return 'True';
+  if (v === false) return 'False';
+  if (Array.isArray(v)) return `[${v.map((x) => formatReprImpl(x, ascii)).join(', ')}]`;
+  if (typeof v === 'object' && !(v instanceof JsonNumber)) {
+    // JSON object keys are always strings, so `repr(key)` is the string branch above.
+    return `{${Object.entries(v)
+      .map(([k, x]) => `${formatReprImpl(k, ascii)}: ${formatReprImpl(x, ascii)}`)
+      .join(', ')}}`;
+  }
+  return formatValue(v);
+}
+
+export function formatRepr(v) {
+  return formatReprImpl(v, false);
+}
+
+/**
+ * `ascii(value)` — `repr()` with every non-ASCII character escaped as well.
+ *
+ * Used where a warning quotes a value that came out of a file a user (or another tool)
+ * may have written: `build`'s prune guard names the suspicious dir name it refused to
+ * delete from `.geneseed-srcdirs.json`. Escaping is the point — a dir name carrying a
+ * newline or a right-to-left override must be readable in the warning, not act on the
+ * terminal, and Python already made that choice by spelling it `ascii()` rather than an
+ * f-string.
+ *
+ * The two share ONE implementation on purpose. The first draft gave `formatReprAscii` its own
+ * container and quote handling, and a mutation exposed the consequence immediately:
+ * `formatRepr`'s container branches became unreachable, so half of the code was dead and
+ * neither copy's escaping could drift without the other silently keeping the gate green.
+ */
+export function formatReprAscii(v) {
+  return formatReprImpl(v, true);
+}
+
+/**
+ * Python's `==` for values that came out of `json.loads` \u2014 the operator behind
+ * `group in arr`, `rec in canon_flat` and `arr.remove(group)`.
+ *
+ * `===` is identity for containers, so a naive port of `if group in arr` never matches and
+ * `_merge_claude_settings` re-adds its own hook group on every emit \u2014 the exact defect the
+ * prior-claim pruning exists to prevent, reintroduced by a one-word translation.
+ *
+ * `JsonNumber` compares by its VALUE, which is right: Python's `{"a": 1} == {"a": 1.0}` is
+ * True even though `repr` renders the two differently. The one gap left is Python's
+ * `1 == True`; a settings.json holding a bool where the manifest recorded a number is not
+ * a shape any writer here produces.
+ */
+export function deepEquals(a, b) {
+  const x = a instanceof JsonNumber ? a.value : a;
+  const y = b instanceof JsonNumber ? b.value : b;
+  if (x === null || y === null || typeof x !== 'object' || typeof y !== 'object') {
+    return x === y;
+  }
+  if (Array.isArray(x) !== Array.isArray(y)) return false;
+  if (Array.isArray(x)) {
+    return x.length === y.length && x.every((v, i) => deepEquals(v, y[i]));
+  }
+  const kx = Object.keys(x);
+  const ky = Object.keys(y);
+  return kx.length === ky.length
+    && kx.every((k) => Object.prototype.hasOwnProperty.call(y, k) && deepEquals(x[k], y[k]));
+}
+
+/** `value in list` and `list.index(value)` under `deepEquals` \u2014 Python's `in`, not `includes`. */
+export function indexOfDeepEqual(arr, value) {
+  return arr.findIndex((v) => deepEquals(v, value));
+}
+
+/**
+ * `json.dumps(s)` for a STRING, with Python's default `ensure_ascii=True`.
+ *
+ * Every emitted `description:` line is built this way, and 44-50 of them per theme carry
+ * an em dash today: Python writes `"a — b"`, `JSON.stringify` writes `"a — b"`. The
+ * two agree on everything below U+007F — including the control-character table
+ * (`\b \t \n \f \r`, then lowercase `\u00xx`) — so escaping the rest is the whole delta.
+ * Astral characters fall out correctly without a special case: JS strings are UTF-16, so
+ * the surrogate pair is escaped one code unit at a time, which is exactly what Python
+ * emits (`😀`).
+ *
+ * Strings only, and loudly so — a COMPACT container is the one shape that genuinely
+ * differs: Python's default separators are `(', ', ': ')`, so it writes `{"a": 1, "b": 2}`
+ * where `JSON.stringify` writes `{"a":1,"b":2}`. Indented containers do NOT have that
+ * problem (see `jsonDumpsIndent`), which is why the split is compact-vs-indented rather
+ * than string-vs-container.
+ */
+export function jsonDumps(s) {
+  if (typeof s !== 'string') {
+    throw new TypeError('jsonDumps takes a string; a COMPACT container differs from '
+      + "json.dumps by Python's ', ' / ': ' separators too \u2014 use jsonDumpsIndent or "
+      + 'jsonDumpsCompact');
+  }
+  return escapeNonAscii(JSON.stringify(s));
+}
+
+/**
+ * `ensure_ascii=True`: escape everything Python's encoder does and JS's does not.
+ *
+ * Applied to the SERIALISED text, which is safe because a JSON document can only carry
+ * non-ASCII inside string literals. Spelled with \\u escapes, never literals: a JS source
+ * file carrying a raw U+2028 or U+2029 terminates the line it sits on, and the parse
+ * error points somewhere else entirely.
+ */
+function escapeNonAscii(text) {
+  return text.replace(/[\u007f-\uffff]/g,
+    (c) => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));
+}
+
+/**
+ * `json.dumps(obj, indent=2)` \u2014 and with `{ ensureAscii: false }`, the
+ * `ensure_ascii=False` variant. Those are the only two container shapes the generator
+ * writes; measured across all 27 `json.dumps` call sites.
+ *
+ * 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.
+ */
+export function jsonDumpsIndent(value, { ensureAscii = true } = {}) {
+  const text = JSON.stringify(value, null, 2);
+  return ensureAscii ? escapeNonAscii(text) : text;
+}
+
+/**
+ * `json.dumps(obj)` and `json.dumps(obj, sort_keys=True)` — the COMPACT container form.
+ *
+ * Deferred through three phases because guessing its signature would have been worse than
+ * not having it; `js/hosts/settings.mjs` is the code that finally needs it, and the shapes were
+ * counted with `ast` rather than assumed: four bare `json.dumps(container)` and two
+ * `sort_keys=True`, all inside `_build_settings.py`, none of them `ensure_ascii=False`.
+ *
+ * It cannot delegate to `JSON.stringify` the way `jsonDumpsIndent` does. Without an indent
+ * Python's separators are `(', ', ': ')` — `{"a": 1, "b": [1, 2]}` where `JSON.stringify`
+ * writes `{"a":1,"b":[1,2]}` — and patching the separators back into the serialised text
+ * would corrupt any string containing `,` or `:`. So the walk is written out.
+ *
+ * `sortKeys` sorts with JS's default comparator (UTF-16 code units) where Python sorts by
+ * code point; the two disagree only above the BMP, which no settings.json key reaches. A
+ * non-finite number throws rather than emitting `NaN`/`Infinity`: Python's encoder writes
+ * those bare tokens, which is not valid JSON, and no caller here can produce one.
+ *
+ * `bareInts` admits a BARE JS number, reading it as a Python `int`. `formatValue` refuses one by
+ * default and is right to: a value that came out of `json.loads` carries the int/float
+ * distinction and a bare double has lost it. But the caller it was written for is `sendJson`
+ * in `js/web/handler.mjs`, whose values are COMPUTED — counts, a port, a pid, a unix second
+ * — every one of them an integer, which both languages render identically. The flag is where
+ * that claim is stated. It has two further callers now, and neither is an endpoint:
+ * `js/web/jobs.mjs` writes the job history and `js/web/activity.mjs` the activity record. A
+ * non-integral value still renders through `repr(float)`, which is the honest reading of
+ * `0.5`; only an INTEGRAL float (`1.0` against JS's `1`) is unrepresentable, and it is
+ * unrepresentable whatever this flag says.
+ */
+export function jsonDumpsCompact(value, { sortKeys = false, ensureAscii = true,
+  bareInts = false } = {}) {
+  const text = compactImpl(value, sortKeys, bareInts);
+  return ensureAscii ? escapeNonAscii(text) : text;
+}
+
+function compactImpl(v, sortKeys, bareInts) {
+  if (v === null || v === undefined) return 'null';
+  if (v === true) return 'true';
+  if (v === false) return 'false';
+  if (typeof v === 'string') return JSON.stringify(v);
+  if (v instanceof JsonNumber || typeof v === 'number') {
+    const n = v instanceof JsonNumber ? v.value : v;
+    if (!Number.isFinite(n)) {
+      throw new TypeError(`jsonDumpsCompact got ${n}; Python's encoder writes a bare `
+        + 'NaN/Infinity token there, which is not JSON, and nothing here can produce one');
+    }
+    if (bareInts && typeof v === 'number') {
+      return Number.isSafeInteger(n) ? String(n) : formatFloat(n);
+    }
+    return formatValue(v);
+  }
+  if (Array.isArray(v)) {
+    return `[${v.map((x) => compactImpl(x, sortKeys, bareInts)).join(', ')}]`;
+  }
+  if (typeof v === 'object') {
+    const keys = sortKeys ? Object.keys(v).sort() : Object.keys(v);
+    return `{${keys.map((k) => `${JSON.stringify(k)}: ${compactImpl(v[k], sortKeys, bareInts)}`)
+      .join(', ')}}`;
+  }
+  throw new TypeError(`jsonDumpsCompact has no rendering for ${typeof v}`);
+}
+

package/js/lib/paths.mjs

@@ -0,0 +1,242 @@
+/**
+ * Comparing and locating — how a path is case-folded, ordered, contained, spelled and found.
+ *
+ * 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.
+ * Path semantics are the most PLATFORM-SHAPED rules in the tool — several of these have a
+ * different right answer on Windows and on POSIX, and each says which.
+ */
+import { accessSync, constants, statSync } from 'node:fs';
+import path from 'node:path';
+
+const { X_OK } = constants;
+/**
+ * `PurePath._str_normcase` \u2014 Windows compares and sorts paths case-folded, POSIX does
+ * not. This is what makes `sorted(SRC.rglob('*'))` and `sorted(d.glob('*.json'))`
+ * platform-dependent, and the order is observable: the prompt emitter embeds items in
+ * order, and each emit's written list becomes the ownership manifest the prune diffs.
+ *
+ * Two residual differences, both unreachable with this repo's ASCII filenames: Python
+ * compares by code point where JS compares by UTF-16 code unit (differs only above the
+ * 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
+ * `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`
+ * name, which is why no emitted byte ever moved; `fnTranslate(normcase(pattern))` in
+ * `js/hosts/hooks.mjs` is where it was reachable, because an exclude pattern is USER-WRITTEN and
+ * `memory/*` never matched a native `memory\x` the way `fnmatch` does.
+ */
+export const normcase = process.platform === 'win32'
+  ? (s) => s.replaceAll('/', '\\').toLowerCase()
+  : (s) => s;
+
+/**
+ * `sorted()` over paths \u2014 one owner, so two call sites cannot drift apart.
+ *
+ * COMPONENT-WISE, and that was a flat string compare until P2 measured it. `PurePath.__lt__`
+ * compares `_parts_normcase` \u2014 a TUPLE of path components \u2014 so the separator never takes part
+ * in the comparison, and the two readings disagree in BOTH directions:
+ *
+ *     sorted    : skills/geneseed/SKILL.md  <  skills/geneseed-code-review/SKILL.md
+ *     flat cmp  : the reverse, because '-' (0x2d) sorts before the separator '\\' (0x5c)
+ *     sorted    : x/a/b.md  <  x/a.md          (component 'a' < 'a.md')
+ *     flat cmp  : the reverse again
+ *
+ * Nothing in the emitted tree could see it: `js/build/render.mjs` sorts a list whose members share
+ * 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
+ * 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
+ * agree with a drift \u2014 and it is the measured killer of this function's mutation (M3).
+ */
+export function comparePaths(a, b) {
+  const A = normcase(a).split(/[\\/]/);
+  const B = normcase(b).split(/[\\/]/);
+  for (let i = 0; i < Math.min(A.length, B.length); i += 1) {
+    if (A[i] !== B[i]) return A[i] < B[i] ? -1 : 1;
+  }
+  return A.length - B.length;
+}
+
+/**
+ * `_harness_core._within` \u2014 containment through `normcase`, segment-wise.
+ *
+ * MOVED HERE IN P6i, from `js/web/api.mjs` where P6b first needed it. The Python is a harness
+ * CORE primitive (`child.relative_to(parent)` in a try/except), and its second caller is
+ * `_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.
+ */
+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);
+}
+
+/**
+ * `str(PurePath(s))` — separators normalised to the platform's, `.` components dropped,
+ * duplicate separators collapsed, a trailing one removed.
+ *
+ * `path.normalize` is NOT this: it also collapses `a/../b` to `b`, and `PurePath` keeps the
+ * `..` because a symlinked `a` makes those two different directories. The distinction is
+ * live in `js/inspect/excludes.mjs`, where a hand-edited `excludes.json` entry is compared against a
+ * RESOLVED repo path — Python never matches a `..` entry there, and a normalising port would
+ * match it and unwire a file the reference would have left alone.
+ */
+/**
+ * `str(Path(x))` — and it is PLATFORM-SHAPED, because `Path` is.
+ *
+ * `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`:
+ *
+ *   * SEPARATORS. `ntpath` treats `\` and `/` alike; `posixpath` treats `\` as an ordinary
+ *     filename character. `str(PurePosixPath('C:\\x\\bin\\'))` is that string VERBATIM —
+ *     one component, trailing backslash and all — where splitting on both answered
+ *     `C:/x/bin`. A backslash is legal in a Linux filename, so this is not academic.
+ *   * THE DOUBLE-SLASH ROOT. POSIX gives EXACTLY two leading slashes an
+ *     implementation-defined meaning and `PurePosixPath` preserves them; three or more
+ *     collapse to one. `path.posix.parse` reports a one-character root for every case, so
+ *     `//server/share` came back as `/server/share`.
+ *
+ * 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.
+ *
+ * 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
+ * `\server\share\x`.
+ */
+export function toPlatformPath(s) {
+  const win = path.sep === '\\';
+  let raw = path.parse(s).root;
+  if (!win && raw && /^\/\/(?!\/)/.test(s)) raw = '//';
+  const root = raw.replace(/[\\/]/g, path.sep);
+  const seps = win ? /[\\/]+/ : /\/+/;
+  const parts = s.slice(raw.length).split(seps).filter((p) => p !== '' && p !== '.');
+  const tail = parts.join(path.sep);
+  if (!root) return tail || '.';
+  return root + tail;
+}
+
+/**
+ * `pathlib.Path(s).is_absolute()`, which is NOT `path.isAbsolute(s)` on Windows.
+ *
+ * MEASURED against CPython 3.13, and the two disagree on exactly one shape: a ROOTLESS
+ * absolute path. `/x/AGENT.md` and `\x\AGENT.md` are `True` to `path.isAbsolute` and `False`
+ * to Python, which requires a DRIVE (`C:/x`) or a UNC root (`//server/share/x`) before it
+ * calls a Windows path absolute. `C:x/AGENT.md` — a drive-RELATIVE path — is False to both.
+ * On POSIX the two rules coincide and this is `s.startsWith('/')`.
+ *
+ * Written in P5h for `installAgentEntry`, which filters an OpenCode config's `instructions`
+ * for the entries that are NOT absolute in order to tell a project install's relative
+ * `…/AGENT.md` from a global install's absolute one. A hand-edited config naming
+ * `/repo/AGENT.md` is the reachable input: Python keeps that entry and Node would have
+ * skipped it and fallen through to the literal `AGENT.md`, unwiring nothing.
+ *
+ * ONE OWNER, and the five pre-existing `path.isAbsolute` calls in `js/` were READ rather than
+ * assumed to be copies. Three cannot reach the divergence — `js/inspect/doctor.mjs` and
+ * `bin/build-driver.mjs` test the output of `path.relative`, which is never rootless-absolute,
+ * and `js/build/bundle.mjs`'s `safePriorDirName` is `&&`-guarded by `basename(p) === p` immediately
+ * after. The two in `js/hosts/hooks.mjs` (a context entry's `path`) DO carry the same hazard and
+ * are deliberately not repointed here: that is the hook entry's shipped behaviour, no
+ * `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.
+ */
+export function isAbsolutePath(s) {
+  if (process.platform !== 'win32') return s.startsWith('/');
+  // Python is absolute iff the path has a DRIVE (or UNC share) *and* a root — `C:x` has the
+  // drive and no root, `/x` has the root and no drive, and neither is absolute. In
+  // `path.parse` terms that is exactly "the root is longer than a bare separator AND ends in
+  // one": `C:` for `C:x`, `\` for `\x`, `C:\` for `C:\x`, `\\srv\share\` for a UNC path.
+  // The first draft tested `root !== '\\'`, which called `C:x` absolute; the corpus caught
+  // it on the two drive-relative cases and nothing else would have.
+  const root = path.parse(s).root;
+  return root.length > 1 && /[\\/]$/.test(root);
+}
+
+/**
+ * `shutil.which(cmd, path=None)` — the first executable named `cmd` on PATH, or null.
+ *
+ * `doctor` runs `node --check` over the OpenCode plugins and SKIPS the whole check when node
+ * is not on PATH. `process.execPath` is not that: it is always set, so a port that used it
+ * would run the check in a world where the reference silently declines to — the divergence a
+ * 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
+ * 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.
+ */
+export function which(cmd, searchPath = null) {
+  const win = process.platform === 'win32';
+  const isExec = (p) => {
+    try {
+      if (!statSync(p).isFile()) return false;
+      accessSync(p, X_OK);
+      return true;
+    } catch { return false; }
+  };
+  // A command with a directory separator is not looked up at all — Python checks it as given.
+  if (cmd.includes('/') || (win && cmd.includes('\\'))) return isExec(cmd) ? cmd : null;
+  const exts = win
+    ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+    : [];
+  const spelled = win && exts.some((e) => cmd.toLowerCase().endsWith(e.toLowerCase()));
+  // `os.path.join`, which CONCATENATES where `path.join` NORMALISES. The difference shows the
+  // moment a PATH entry is spelled with the other separator — routine on Windows, where Git
+  // Bash and MSYS put forward-slash entries in it — and the answer is the string a caller
+  // 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(':'))
+      ? 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 seen = new Set();
+  for (const dir of dirs) {
+    const key = win ? dir.toLowerCase() : dir;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    for (const ext of (!win || spelled ? [''] : exts)) {
+      const candidate = joinRaw(dir, cmd + ext);
+      if (isExec(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+

package/js/lib/proc.mjs

@@ -7,9 +7,9 @@
  * worst case, running `node --check` once per plugin, and it is what a user actually sees:
  * seven consoles flashing on a dashboard load.
  *
- * WHY IT LIVES HERE AND NOT IN `js/update.mjs`, WHICH DEFINED IT FIRST. It was private to
- * that module and six of its spawns used it, so the four spawn sites in `js/doctor.mjs`,
- * `js/hooks.mjs`, `js/setup.mjs` and `js/link.mjs` each had to remember the flag on their
+ * WHY IT LIVES HERE AND NOT IN `js/maintain/update.mjs`, WHICH DEFINED IT FIRST. It was private to
+ * 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