geneseed 3.1.0 → 3.1.2

package/js/{settings.mjs → hosts/settings.mjs}

@@ -7,16 +7,20 @@
  * last is that it is also the unit the RUNTIME drives: eleven of its names have a consumer
  * outside the emit tree, ten of them in `rituals/_harness_mcp.py` (remerge, deactivate,
  * reactivate, uninstall), two in `rituals/_harness_exclude.py`, one in
- * `rituals/_harness_build.py`. Nothing imports this module yet — P3a proves the unit,
- * P3b flips the call sites.
+ * Every emit and every lifecycle verb goes through this module:
+ * `js/build/emit-opencode.mjs` and `js/build/emit-claude.mjs` wire the host config,
+ * `js/maintain/uninstall.mjs` and `js/maintain/migrate.mjs` drive the unwire and the shim
+ * migration, `js/inspect/checks-repo.mjs` reads `shimDeadPaths` for the doctor, and
+ * `js/web/api.mjs` borrows the same readers for the console.
  *
  * THE STDOUT RULE BINDS HARDEST HERE. The hooks this module writes signal their verdict as
  * a JSON object on stdout and return 0 on EVERY path (`|| exit 0` is not what it looks
  * like — see the shim comment below), so a stray byte printed on a hook path does not make
  * noise, it silently disables a gate. Everything printed here is a generator-time message;
- * the streams are compared byte for byte by `tests/test_settings_parity.py`, and the
- * asymmetry between the two (`_warn_commented_jsonc` prints to STDOUT, every other message
- * to stderr) is the Python's own and is reproduced, not tidied.
+ * the split between them is asserted absolutely by `tests/unit/settings_jsonc.test.mjs` and
+ * `tests/unit/settings_integrity.test.mjs`. The asymmetry (`_warn_commented_jsonc` prints to
+ * STDOUT, every other message to stderr) is inherited from `_build_settings.py` and kept
+ * deliberately rather than tidied.
  *
  * HOOKS ARE APPEND-ONLY AND FAIL-CLOSED. Nothing here rewrites a hook group in place:
  * `mergeClaudeSettings` appends what is missing and removes only groups the manifest
@@ -38,10 +42,11 @@ import {
 } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { printErr, readText, writeText } from '../lib/fs.mjs';
 import {
-  jsonDumps, jsonDumpsCompact, jsonDumpsIndent, parseJson, pyEq, pyRepr, indexOfEq,
-  pyPrintErr, readText, writeText,
-} from './lib/fs.mjs';
+  jsonDumps, jsonDumpsCompact, jsonDumpsIndent, parseJson, deepEquals, formatRepr,
+  indexOfDeepEqual,
+} from '../lib/json.mjs';
 
 export const OPENCODE_SCHEMA = 'https://opencode.ai/config.json';
 
@@ -49,7 +54,7 @@ export const OPENCODE_SCHEMA = 'https://opencode.ai/config.json';
  *
  * `loaded[event]` where `event` came out of a manifest hands back `Object.prototype`'s
  * member for `constructor`, `toString` or `valueOf`, where Python's `.get` returns None.
- * The same hazard `js/native.mjs` hit with `overrides[stem]`, on a dict the USER edits. */
+ * The same hazard `js/hosts/native.mjs` hit with `overrides[stem]`, on a dict the USER edits. */
 function get(obj, key) {
   return Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : undefined;
 }
@@ -79,6 +84,23 @@ function isDict(v) {
  */
 const processPackOn = (d) => !Array.isArray(d) || d.includes('process');
 
+/**
+ * The address of the rule the git gate IS. Not a pack any more — a rule.
+ *
+ * ⚠ THE GATE MOVED FROM THE PACK TO THE RULE, and the reason is that the pack stopped being
+ * the unit a user toggles. With per-rule exclusion an install can keep every other `process`
+ * rule and drop this one; keying the boundary on `d.includes('process')` would then leave the
+ * hook wired for a rule the carrier no longer states — prompt and boundary disagreeing, which
+ * is the single thing this design forbids in either direction.
+ *
+ * `excluded` defaults to `[]` for the same fail-closed reason `excludedRulesOfDir` does: a
+ * caller that has not learned about the second axis excludes nothing, so the gate stays. Every
+ * pre-existing call site keeps its exact behaviour without being touched.
+ */
+const CONSENT_RULE = 'process.5';
+const consentRuleOn = (d, excluded = []) =>
+  processPackOn(d) && !(Array.isArray(excluded) && excluded.includes(CONSENT_RULE));
+
 /**
  * `_build_settings._default_permission`.
  *
@@ -92,9 +114,9 @@ const processPackOn = (d) => !Array.isArray(d) || d.includes('process');
  * Law IV's territory — an always-on invariant — not the process pack's, and the guard
  * plugin's own force-push arm is unconditional for the same reason.
  */
-export function defaultPermission(doctrines = null) {
+export function defaultPermission(doctrines = null, excluded = []) {
   const bash = { 'rm -rf *': 'ask' };
-  if (processPackOn(doctrines)) {
+  if (consentRuleOn(doctrines, excluded)) {
     bash['git commit*'] = 'ask';
     bash['git push*'] = 'ask';
   }
@@ -146,7 +168,7 @@ const OWNED_BASH = ['rm -rf *', 'git commit*', 'git push*', 'git push --force*',
  * FAIL-CLOSED direction — the boundary asks for a confirmation the constitution no longer
  * compels, exactly as the commit skill's own consent step does with the pack off. The unsafe
  * direction, a rule with no gate behind it, cannot occur here. A FRESH file is unaffected:
- * `mergeOpencodeJson` writes `defaultPermission(doctrines)` whole, so a new pack-off install
+ * `mergeOpencodeJson` writes `defaultPermission(doctrines, excluded)` whole, so a new pack-off install
  * has no git gate at all.
  *
  * ⚠ KEY ORDER IS NOT RECONCILED, DELIBERATELY. `defaultPermission` emits its keys in a fixed
@@ -284,7 +306,7 @@ export function readJsonc(text) {
  * `'add'`, which is what the boolean callers this replaced meant.
  */
 export function warnCommentedJsonc(target, agentPath, permission,
-  includeLsp = false, prefix = 'geneseed', doctrines = null) {
+  includeLsp = false, prefix = 'geneseed', doctrines = null, excluded = []) {
   process.stdout.write(`[${prefix}] ${path.basename(target)} has comments — not rewriting `
     + 'it (your edits are kept). Add this to its "instructions" array by hand:\n');
   process.stdout.write(`[${prefix}]     ${jsonDumps(agentPath)}\n`);
@@ -293,7 +315,7 @@ export function warnCommentedJsonc(target, agentPath, permission,
       ? `[${prefix}] and its "permission".bash is missing gates this build wires — `
         + 'reconcile it by hand against:\n'
       : `[${prefix}] and, for Geneseed's default ask-gates, a "permission" key:\n`);
-    for (const line of jsonDumpsIndent(defaultPermission(doctrines)).split('\n')) {
+    for (const line of jsonDumpsIndent(defaultPermission(doctrines, excluded)).split('\n')) {
       process.stdout.write(`[${prefix}]     ${line}\n`);
     }
   }
@@ -322,7 +344,7 @@ export function atomicWriteJson(p, config) {
  * re-implements the inverse itself rather than inherit this one's permission/lsp side
  * effects, so the only crossings are the two emit-tree ones (`_build_emit.emit_opencode`,
  * `_build_global.emit_opencode_global`). */
-export function mergeOpencodeJson(p, agentPath, doctrines = null) {
+export function mergeOpencodeJson(p, agentPath, doctrines = null, excluded = []) {
   const target = opencodeTarget(p);
   let config = { $schema: OPENCODE_SCHEMA, instructions: [] };
   let hadComments = false;
@@ -332,7 +354,7 @@ export function mergeOpencodeJson(p, agentPath, doctrines = null) {
       raw = readText(target);
     } catch (e) {
       if (!isOsError(e)) throw e;
-      process.stderr.write(`[geneseed] WARN: could not read ${target} (${pyOsError(e)}) `
+      process.stderr.write(`[geneseed] WARN: could not read ${target} (${asOsError(e)}) `
         + `— NOT touching it. Add ${jsonDumps(agentPath)} to its "instructions" array by `
         + "hand once it's readable again.\n");
       return target;
@@ -350,7 +372,7 @@ export function mergeOpencodeJson(p, agentPath, doctrines = null) {
   if (!has(config, '$schema')) config.$schema = OPENCODE_SCHEMA;
   let instr = get(config, 'instructions');
   if (!Array.isArray(instr)) instr = [];
-  const addInstr = indexOfEq(instr, agentPath) < 0;
+  const addInstr = indexOfDeepEqual(instr, agentPath) < 0;
   if (addInstr) instr.push(agentPath);
   config.instructions = instr;
   // Absent ⇒ write the whole block; present ⇒ reconcile Geneseed's own git keys. Adding is
@@ -361,10 +383,10 @@ export function mergeOpencodeJson(p, agentPath, doctrines = null) {
   let permChanged = addPerm;
   let stranded = [];
   let opaque = null;
-  if (addPerm) config.permission = defaultPermission(doctrines);
+  if (addPerm) config.permission = defaultPermission(doctrines, excluded);
   else {
     [permChanged, stranded, opaque] = reconcileOpencodePermission(get(config, 'permission'),
-      defaultPermission(doctrines));
+      defaultPermission(doctrines, excluded));
   }
   // The shape said no. This is the direction the residue warning above is NOT — a rule stated
   // in AGENT.md with nothing behind it — and it used to pass in silence, because a blanket
@@ -374,7 +396,7 @@ export function mergeOpencodeJson(p, agentPath, doctrines = null) {
   if (opaque) {
     process.stderr.write(`[geneseed] WARN: "permission" in ${path.basename(target)} `
       + `${opaque}, so Geneseed cannot wire its own gates into it — including `
-      + `${OWNED_BASH.filter((k) => has(defaultPermission(doctrines).bash, k))
+      + `${OWNED_BASH.filter((k) => has(defaultPermission(doctrines, excluded).bash, k))
         .map((k) => jsonDumps(k)).join(', ')}. Your policy is left exactly as written; the `
       + 'harness states those rules but nothing enforces them at this boundary.\n');
   }
@@ -404,14 +426,14 @@ export function mergeOpencodeJson(p, agentPath, doctrines = null) {
     // block to paste, split by which of the two situations the reader is actually in. It is
     // stdout, not stderr, because on this path the paste-in IS the output.
     warnCommentedJsonc(target, agentPath, addPerm ? 'add' : (permChanged && 'reconcile'),
-      addLsp, 'geneseed', doctrines);
+      addLsp, 'geneseed', doctrines, excluded);
     return target;
   }
   try {
     atomicWriteJson(target, config);
   } catch (e) {
     if (!isOsError(e)) throw e;
-    process.stderr.write(`[geneseed] WARN: could not write ${target} (${pyOsError(e)}) — `
+    process.stderr.write(`[geneseed] WARN: could not write ${target} (${asOsError(e)}) — `
       + `the harness will NOT auto-load until this is fixed. Add ${jsonDumps(agentPath)} `
       + 'to its "instructions" array by hand.\n');
   }
@@ -427,7 +449,7 @@ export function mergeOpencodeJson(p, agentPath, doctrines = null) {
  * with an injectable failure instead and compares everything except the OS's own wording.
  * Named here so the gap is a decision rather than a surprise at GA.
  */
-function pyOsError(e) {
+function asOsError(e) {
   return e.message;
 }
 
@@ -458,7 +480,7 @@ export const SHIM_ARGV = new Set(['$@', '%*']);
  * Every quoted token in a shim body that names a path which is not there — empty is healthy.
  *
  * ONE OWNER, because the rule has two consumers now and a second copy is a second place for the
- * `"$@"` defect above to come back: `js/doctor.mjs` turns this into the `[shim] … does not
+ * `"$@"` defect above to come back: `js/inspect/checks-repo.mjs` turns this into the `[shim] … does not
  * exist` report, and `hookPrefix` reads it to decide whether the shim already on disk is worth
  * protecting from a checkout that will not outlive the emit.
  */
@@ -484,7 +506,7 @@ export function shimHome() {
 }
 
 /**
- * `Path(x).expanduser()` — private twin of `js/hosts.mjs`'s `expanduser`, same guard.
+ * `Path(x).expanduser()` — private twin of `js/hosts/hosts.mjs`'s `expanduser`, same guard.
  *
  * `GENESEED_HOME` is user-set, same as any config-dir env var there, so a `~user` value here
  * has the identical failure mode (a hook shim written under a literal `~user` directory) and
@@ -497,7 +519,7 @@ function expanduser(p) {
   if (p.startsWith('~')) {
     const msg = `refusing '${p}': a '~user' path is not expanded by this port; pass an `
       + 'absolute path, or "~" / "~/…" for your own home directory';
-    pyPrintErr(`${msg}\n`);
+    printErr(`${msg}\n`);
     const e = new Error(msg);
     e.exitCode = 1;
     throw e;
@@ -519,12 +541,12 @@ export function hookShimPath(platform = process.platform) {
  * refuses to compare the emitted shim for that reason (`_SHIM_GLOB`) and asserts
  * `_shim_health` instead.
  *
- * So the parity gate's answer here is NOT "skip it". Taking `runner` and `entry` as
- * arguments makes the BODY a pure function of three inputs, and the gate feeds Node the
- * same two values Python computed — which makes every byte of it comparable: the `@echo
- * off`, the CRLF, `exit /b` vs `exec`, the quoting that keeps `--root "<cfg>"` intact. What
- * the gate does not prove is WHICH values a Node driver will pass, and that is a one-line
- * decision at P3b's call site rather than anything in this body.
+ * So the answer here is NOT "skip it". Taking `runner`, `entry` and `platform` as arguments
+ * makes the BODY a pure function of three inputs, which is what lets
+ * `tests/unit/hook_form.test.mjs` assert BOTH platform shapes absolutely in one run on
+ * whichever host it happens to be on: the `@echo off`, the CRLF, `exit /b` vs `exec`, the
+ * quoting that keeps `--root "<cfg>"` intact. What it does not prove is WHICH values the
+ * driver passes — that is `bin/build-driver.mjs`'s `hookRunnerEntry()`, gated separately.
  */
 export function hookShimBody(runner, entry, platform = process.platform) {
   if (platform === 'win32') {
@@ -698,7 +720,7 @@ export function hookPrefix({ runner, entry, platform = process.platform } = {})
  * belongs in — the user's call — not how work is run, so it is not the process pack's to
  * remove. `default` here means unknown, and unknown keeps the gate (see `processPackOn`).
  */
-export function claudeHookGroups(cfg, hookOpts, doctrines = null) {
+export function claudeHookGroups(cfg, hookOpts, doctrines = null, excluded = []) {
   const run = hookPrefix(hookOpts);
   const mem = `--memory "${path.join(cfg, 'memory')}"`;
   // --root carries the install's own dir so a GLOBAL hook can stand down when a project
@@ -709,7 +731,7 @@ export function claudeHookGroups(cfg, hookOpts, doctrines = null) {
   const learn = `${run} learn ${mem} || exit 0`;
   return {
     PreToolUse: [
-      ...(processPackOn(doctrines)
+      ...(consentRuleOn(doctrines, excluded)
         ? [{ matcher: 'Bash', hooks: [{ type: 'command', command: gate }] }] : []),
       {
         matcher: 'Write|Edit|MultiEdit|NotebookEdit',
@@ -740,8 +762,8 @@ export function claudeHookGroups(cfg, hookOpts, doctrines = null) {
  *
  * `scope` is accepted and unused, exactly as in the Python.
  */
-export function mergeClaudeSettings(p, scope = 'global', priorHooks = null, hookOpts = {},
-  doctrines = null) {
+export function mergeClaudeSettings(p, _scope = 'global', priorHooks = null, hookOpts = {},
+  doctrines = null, excluded = []) {
   const prior = (priorHooks || []).filter(isDict);
   let config = {};
   let hadComments = false;
@@ -761,19 +783,19 @@ export function mergeClaudeSettings(p, scope = 'global', priorHooks = null, hook
   }
   let hooks = get(config, 'hooks');
   if (!isDict(hooks)) hooks = {};
-  const canonical = claudeHookGroups(path.dirname(p), hookOpts, doctrines);
+  const canonical = claudeHookGroups(path.dirname(p), hookOpts, doctrines, excluded);
   const canonFlat = [];
   for (const [event, groups] of Object.entries(canonical)) {
     for (const g of groups) canonFlat.push({ event, group: g });
   }
   let pruned = false;
   for (const rec of prior) {
-    if (indexOfEq(canonFlat, rec) >= 0) continue;
+    if (indexOfDeepEqual(canonFlat, rec) >= 0) continue;
     const event = get(rec, 'event');
     const group = get(rec, 'group');
     const arr = get(hooks, event);
     if (Array.isArray(arr)) {
-      const at = indexOfEq(arr, group);
+      const at = indexOfDeepEqual(arr, group);
       if (at >= 0) {
         arr.splice(at, 1);
         pruned = true;
@@ -786,14 +808,14 @@ export function mergeClaudeSettings(p, scope = 'global', priorHooks = null, hook
     let arr = get(hooks, event);
     if (!Array.isArray(arr)) arr = [];
     for (const g of newGroups) {
-      if (indexOfEq(arr, g) >= 0) continue;
+      if (indexOfDeepEqual(arr, g) >= 0) continue;
       arr.push(g);
       added.push({ event, group: g });
     }
     hooks[event] = arr;
   }
-  const survivors = prior.filter((r) => indexOfEq(canonFlat, r) >= 0);
-  const managedNow = survivors.concat(added.filter((a) => indexOfEq(survivors, a) < 0));
+  const survivors = prior.filter((r) => indexOfDeepEqual(canonFlat, r) >= 0);
+  const managedNow = survivors.concat(added.filter((a) => indexOfDeepEqual(survivors, a) < 0));
   if (!added.length && !pruned) return [p, managedNow];
   if (hadComments) {
     process.stderr.write(`[geneseed] ${path.basename(p)} has comments — not rewriting it `
@@ -805,8 +827,10 @@ export function mergeClaudeSettings(p, scope = 'global', priorHooks = null, hook
   // carries four events, so by the time control reaches here `hooks` is never empty. A
   // mutation keeping the empty block instead of deleting it is the one of thirty-three that
   // stays green, and it stays green because there is nothing to detect — recorded the way
-  // `themed_rel` and `lstripNewlines` are, so "the gate cannot see it" and "there is
-  // nothing to see" keep their distance.
+  // `themed_rel` is, so "the gate cannot see it" and "there is nothing to see" keep their
+  // distance. NOT the way `lstripNewlines` is: that one looked unobservable for two phases
+  // and turned out to be mutation M7, killed by `golden.mjs --idempotent` through
+  // `managedBlockWrite`'s `updated` branch, which only a RE-emit reaches.
   if (Object.keys(hooks).length) config.hooks = hooks;
   else delete config.hooks;
   mkdirSync(path.dirname(p), { recursive: true });
@@ -838,7 +862,7 @@ export function unwireClaudeSettings(p, added) {
     const group = get(rec, 'group');
     let arr = get(hooks, event);
     if (Array.isArray(arr)) {
-      const at = indexOfEq(arr, group);
+      const at = indexOfDeepEqual(arr, group);
       if (at >= 0) arr.splice(at, 1);
     }
     arr = get(hooks, event);
@@ -879,7 +903,7 @@ export function wireClaudeExcludes(p, excludes) {
   }
   let cur = get(config, 'claudeMdExcludes');
   if (!Array.isArray(cur)) cur = [];
-  const added = want.filter((e) => indexOfEq(cur, e) < 0);
+  const added = want.filter((e) => indexOfDeepEqual(cur, e) < 0);
   if (!added.length) return [];
   if (hadComments) {
     process.stderr.write(`[geneseed] ${path.basename(p)} has comments — not rewriting it `
@@ -894,7 +918,7 @@ export function wireClaudeExcludes(p, excludes) {
     atomicWriteJson(p, config);
   } catch (e) {
     if (!isOsError(e)) throw e;
-    process.stderr.write(`[geneseed] WARN: could not write ${p} (${pyOsError(e)}) — `
+    process.stderr.write(`[geneseed] WARN: could not write ${p} (${asOsError(e)}) — `
       + 'claudeMdExcludes were not wired. Add to its "claudeMdExcludes" array by hand: '
       + `${jsonDumpsCompact(added)}\n`);
     return [];
@@ -917,7 +941,7 @@ export function unwireClaudeExcludes(p, excludes) {
   const cur = get(loaded, 'claudeMdExcludes');
   if (!Array.isArray(cur)) return;
   for (const e of excludes) {
-    const at = indexOfEq(cur, e);
+    const at = indexOfDeepEqual(cur, e);
     if (at >= 0) cur.splice(at, 1);
   }
   if (cur.length) loaded.claudeMdExcludes = cur;
@@ -954,8 +978,9 @@ export const SHIM_ENTRY_MARK = 'geneseed-hook.mjs';
 /**
  * `_build_settings._migrate_shape` — 'legacy' | 'current' | 'none'.
  *
- * PURE, so `tests/test_settings_parity.py` runs it over a corpus of real config text no cell
- * can seed. 'none' is not a fault: a Copilot install wires no hooks, and a user's own
+ * PURE — and currently reached only END TO END, by the `migrate/a-node-baked-shim-reads-as-current`
+ * cell. No unit corpus drives it directly, which is worth knowing before trusting it.
+ * 'none' is not a fault: a Copilot install wires no hooks, and a user's own
  * settings.json may carry three hand-written hooks and no Geneseed entry. Both must read as
  * "nothing to migrate" rather than "unrecognised", or `migrate` refuses on the commonest
  * config on any machine.
@@ -1043,7 +1068,7 @@ export function settingsIntegrityCheck(p, managed, expect = 'present') {
     [loaded] = readJsonc(readText(p));
   } catch (e) {
     if (!isOsError(e)) throw e;
-    problems.push(`${p}: could not read the file (${pyOsError(e)})`);
+    problems.push(`${p}: could not read the file (${asOsError(e)})`);
     return flush();
   }
   if (!isDict(loaded)) {
@@ -1060,25 +1085,25 @@ export function settingsIntegrityCheck(p, managed, expect = 'present') {
   for (const rec of recordedHooks) {
     const event = get(rec, 'event');
     const group = get(rec, 'group');
-    const hit = presentGroups.some(([e, g]) => pyEq(e, event) && pyEq(g, group));
+    const hit = presentGroups.some(([e, g]) => deepEquals(e, event) && deepEquals(g, group));
     if (expect === 'present' && !hit) {
-      problems.push(`${p}: recorded hook group missing — event=${pyRepr(event ?? null)} `
+      problems.push(`${p}: recorded hook group missing — event=${formatRepr(event ?? null)} `
         + `group=${jsonDumpsCompact(group ?? null)}`);
     } else if (expect === 'absent' && hit) {
       problems.push(`${p}: recorded hook group still present after unwire — `
-        + `event=${pyRepr(event ?? null)} group=${jsonDumpsCompact(group ?? null)}`);
+        + `event=${formatRepr(event ?? null)} group=${jsonDumpsCompact(group ?? null)}`);
     }
   }
 
   let exclCur = get(loaded, 'claudeMdExcludes');
   exclCur = Array.isArray(exclCur) ? exclCur : [];
   for (const entry of (get(m, 'settings_excludes') || [])) {
-    const hit = indexOfEq(exclCur, entry) >= 0;
+    const hit = indexOfDeepEqual(exclCur, entry) >= 0;
     if (expect === 'present' && !hit) {
-      problems.push(`${p}: recorded claudeMdExcludes entry missing: ${pyRepr(entry)}`);
+      problems.push(`${p}: recorded claudeMdExcludes entry missing: ${formatRepr(entry)}`);
     } else if (expect === 'absent' && hit) {
       problems.push(`${p}: recorded claudeMdExcludes entry still present after unwire: `
-        + `${pyRepr(entry)}`);
+        + `${formatRepr(entry)}`);
     }
   }
 
@@ -1086,17 +1111,17 @@ export function settingsIntegrityCheck(p, managed, expect = 'present') {
   // auto-delete (they may be user-authored, or a claim this run legitimately did not
   // inherit).
   const recordedSet = new Set(recordedHooks.map(
-    (r) => `${pyRepr(get(r, 'event') ?? null)}\u0000`
+    (r) => `${formatRepr(get(r, 'event') ?? null)}\u0000`
       + `${jsonDumpsCompact(get(r, 'group') ?? null, { sortKeys: true })}`));
   for (const [event, group] of presentGroups) {
-    const key = `${pyRepr(event)}\u0000${jsonDumpsCompact(group, { sortKeys: true })}`;
+    const key = `${formatRepr(event)}\u0000${jsonDumpsCompact(group, { sortKeys: true })}`;
     if (recordedSet.has(key)) continue;
     const cmds = (get(group, 'hooks') || []).filter(isDict)
       .map((h) => (has(h, 'command') ? h.command : ''));
     if (cmds.some((c) => typeof c === 'string'
       && GENESEED_HOOK_SNIFF.some((mk) => c.includes(mk)))) {
       problems.push(`${p}: Geneseed-pattern hook present but NOT recorded in the manifest `
-        + `(event=${pyRepr(event)}) — possibly user-authored; left alone`);
+        + `(event=${formatRepr(event)}) — possibly user-authored; left alone`);
     }
   }
 
@@ -1116,7 +1141,7 @@ function delimiters(blockId) {
  */
 export function managedBlockWrite(p, content, blockId = 'GENESEED') {
   const [begin, end] = delimiters(blockId);
-  const block = `${begin}\n${pyRstrip(content)}\n${end}\n`;
+  const block = `${begin}\n${stripEnd(content)}\n${end}\n`;
   if (!existsSync(p)) {
     mkdirSync(path.dirname(p), { recursive: true });
     writeText(p, block);
@@ -1146,7 +1171,7 @@ export function managedBlockRemove(p, blockId = 'GENESEED', whole = false) {
   if (!existing.includes(begin) || !existing.includes(end)) return;
   const pre = existing.split(begin)[0];
   const post = existing.slice(existing.indexOf(end) + end.length);
-  const rest = pyStrip(`${pyRstripNewlines(pre)}\n${lstripNewlines(post)}`);
+  const rest = stripEnds(`${stripTrailingNewlines(pre)}\n${lstripNewlines(post)}`);
   if (rest) writeText(p, `${rest}\n`);
   else unlinkSync(p);
 }
@@ -1166,17 +1191,17 @@ export function managedBlockRead(p, blockId = 'GENESEED') {
 // U+001C–U+001F, which `trim()` leaves. A managed block is user-editable prose in a file
 // Geneseed shares with the user, so the set is spelled out rather than approximated — and
 // spelled with escapes, never literals: a raw U+2028 in a JS source file ends the line.
-const PY_SPACE = '[\t\n\v\f\r\x1c-\x1f \x85\xa0\u1680\u2000-\u200a'
+const WHITESPACE = '[\t\n\v\f\r\x1c-\x1f \x85\xa0\u1680\u2000-\u200a'
   + '\u2028\u2029\u202f\u205f\u3000]';
 
-const RSTRIP_RE = new RegExp(`${PY_SPACE}+$`);
-const LSTRIP_RE = new RegExp(`^${PY_SPACE}+`);
+const RSTRIP_RE = new RegExp(`${WHITESPACE}+$`);
+const LSTRIP_RE = new RegExp(`^${WHITESPACE}+`);
 
-function pyRstrip(s) {
+function stripEnd(s) {
   return s.replace(RSTRIP_RE, '');
 }
 
-function pyStrip(s) {
+function stripEnds(s) {
   return s.replace(LSTRIP_RE, '').replace(RSTRIP_RE, '');
 }
 
@@ -1184,10 +1209,10 @@ function lstripNewlines(s) {
   return s.replace(/^\n+/, '');
 }
 
-function pyRstripNewlines(s) {
+function stripTrailingNewlines(s) {
   return s.replace(/\n+$/, '');
 }
 
 function stripNewlines(s) {
-  return lstripNewlines(pyRstripNewlines(s));
+  return lstripNewlines(stripTrailingNewlines(s));
 }