geneseed 3.14.0 → 3.15.0

package/js/maintain/update.mjs

@@ -1,10 +1,8 @@
 /**
  * Self-update: `git pull` the install's own origin, validate, rebuild.
  *
- * The verb this whole port exists for. Every other subcommand can be Python for one more
- * release; `upgrade` is the one operation a "no Python needed" install cannot delegate,
- * because a Node install that shelled out to the Python harness to update itself
- * would have Python as a hard dependency of the only command a user MUST be able to run.
+ * The one operation a user MUST always be able to run: every other verb can be broken by a bad
+ * release, and this is the verb that fetches the fix.
  *
  * WHY THIS MODULE SPAWNS, AND WHY THE ARGUMENT IS NOT THE JOB RUNNER'S. `js/web/jobs.mjs`
  * re-executes this program for ISOLATION — a synchronous verb in the daemon's event loop
@@ -15,21 +13,23 @@
  * the modules this process loaded before the merge — it would validate the old source, pass,
  * and then render the old source into the bundle, reporting success. That is not a slower
  * version of the right answer, it is the wrong one. So `runDoctor`, `rebuildBundle` and
- * `rebuildInstalls` each start a fresh interpreter over the tree as it now is, exactly as the
- * reference does, and `_ALLOWED_SPAWNS` in `tests/test_hook_cli_parity.py` carries the argv.
+ * `rebuildInstalls` each start a fresh interpreter over the tree as it now is, and
+ * `ALLOWED_SPAWNS` in `tests/unit/hook_cli.test.mjs` carries the argv. The same reason is why
+ * the two modules this file reaches lazily (`js/build/generate.mjs`, `js/web/daemon.mjs`) are
+ * loaded BEFORE the pull and not at their call sites: an `import()` after the merge would mix
+ * pulled files with the ones already cached, and a renamed export kills the upgrade mid-way.
  *
  * `git` is the fourth spawn and the plainest: there is no git library in the Node stdlib,
  * and the port will not vendor one. Every git call goes through the `gitRun` seam —
  * which-guarded, credential-redacted, and it never throws.
  *
- * WHAT THE GATE CANNOT SEE, stated rather than implied. `upgrade/*` in
- * `tests/harness_golden.py` runs each arm against a private clone of a bare origin the
- * fixture builds, so no cell can reach a network — which is a safety property and a blind
+ * WHAT THE GATE CANNOT SEE, stated rather than implied. `tests/unit/update_git.test.mjs` and
+ * `tests/unit/update_flow.test.mjs` run each arm against a private clone of a bare origin the
+ * fixture builds, so no test can reach a network — which is a safety property and a blind
  * spot at once: `git fetch --progress` over a local path prints NOTHING, so
  * `fetchStreaming`'s reader, its phase filter and its 15s heartbeat are reachable in every
- * cell and varied in none. The phase filter is gated as a corpus in
- * `tests/test_pure_function_parity.py`; the heartbeat and the hard deadline are gated by
- * neither and are declared in the P8a handoff.
+ * run and varied in none. The phase filter is gated over a recorded transcript in
+ * `tests/unit/update_git.test.mjs`; the heartbeat and the hard deadline are gated by nothing.
  *
  * ALSO HERE, SINCE P8b: `syncSelf`/`cmdSyncSelf` and the bootstrap step runner
  * (`cmdBootstrap`, `bootstrapPlain`) at the bottom of this file. Still NOT here: `main`, the
@@ -47,10 +47,9 @@ import { ROOT } from '../build/source.mjs';
 import { exportImprovements, flushExportNotes } from '../inspect/diff.mjs';
 import { opencodeConfigDir } from '../hosts/hosts.mjs';
 import { appendText, copyFile, printOut, printErr, readText, writeText } from '../lib/fs.mjs';
-import { toPlatformPath, which } from '../lib/paths.mjs';
+import { comparePaths, toPlatformPath, which } from '../lib/paths.mjs';
 import { WHITESPACE, parseIntStrict, stripWhitespace } from '../lib/text.mjs';
 import { NO_WINDOW } from '../lib/proc.mjs';
-import { bounceDaemonIfRunning } from '../web/daemon.mjs';
 
 /**
  * `_CREDS_RE` / `_redact_url_creds` — strip a `user[:token]@` userinfo out of any URL in
@@ -248,8 +247,14 @@ export function countOccurrences(s) {
 export function killTree(child) {
   try {
     if (process.platform !== 'win32') process.kill(-child.pid, 'SIGKILL');
-    else spawnSync('taskkill', ['/F', '/T', '/PID', String(child.pid)],
-      { encoding: 'utf8', timeout: 15000, ...NO_WINDOW });
+    else {
+      // `which`, never a bare name (a bare name resolves against the cwd first on Windows);
+      // no taskkill on PATH falls through to the `child.kill()` below.
+      const taskkill = which('taskkill');
+      if (!taskkill) throw new Error('taskkill not on PATH');
+      spawnSync(taskkill, ['/F', '/T', '/PID', String(child.pid)],
+        { encoding: 'utf8', timeout: 15000, ...NO_WINDOW });
+    }
   } catch {
     try { child.kill(); } catch { /* already gone */ }
   }
@@ -262,7 +267,7 @@ export function killTree(child) {
  * times and universal-newline decoding turns every `\r` repaint into its own line, so
  * without this a 30-second fetch writes a thousand lines into the install log. No cell can
  * reach it — a local-path fetch prints nothing at all — so
- * `tests/test_pure_function_parity.py` runs it over a recorded fetch transcript instead.
+ * `tests/unit/update_git.test.mjs` runs it over a recorded fetch transcript instead.
  *
  * Returns `[linesToLog, lastPhase]`, splitting the reference's loop from its side effects.
  */
@@ -366,13 +371,19 @@ export async function fetchStreaming(log = null) {
 
 /**
  * `_measure_upstream(log)` — Phase B: fetch (streamed), then classify. Returns
- * `[code, behind, err]` with `code` ∈ {ready, fetch_failed, unrelated, diverged, uptodate}.
+ * `[code, behind, err]` with `code` ∈ {ready, fetch_failed, no_upstream, unrelated, diverged,
+ * uptodate}.
+ *
+ * `no_upstream` HERE, AFTER PREFLIGHT SAID THERE WAS ONE: the fetch itself can take it away.
+ * An upstream branch deleted on the remote, fetched with `fetch.prune`, leaves `@{u}` naming
+ * nothing — both counts then fail, and read as two zeros they said "already up to date".
  */
 export async function measureUpstream(log = null) {
   const [rc, err] = await fetchStreaming(log);
   if (rc !== 0) return ['fetch_failed', 0, err];
-  const [, aheadRaw] = gitRun(['rev-list', '--count', '@{u}..HEAD']);
-  const [, behindRaw] = gitRun(['rev-list', '--count', 'HEAD..@{u}']);
+  const [arc, aheadRaw] = gitRun(['rev-list', '--count', '@{u}..HEAD']);
+  const [brc, behindRaw] = gitRun(['rev-list', '--count', 'HEAD..@{u}']);
+  if (arc !== 0 || brc !== 0) return ['no_upstream', 0, ''];
   const ahead = countOccurrences(aheadRaw);
   const behind = countOccurrences(behindRaw);
   if (ahead > 0) {
@@ -419,16 +430,31 @@ export function runDoctor(cand) {
   return [r.status === 0, universal(r.stdout) + universal(r.stderr)];
 }
 
-/** `_pull_and_validate(log)` — fast-forward to `@{u}`, then doctor-gate with exact rollback. */
+/**
+ * `_pull_and_validate(log)` — fast-forward to `@{u}`, then doctor-gate with exact rollback.
+ *
+ * `collision` ONLY WHEN GIT SAYS SO. A fast-forward can fail for other reasons — a lock file, a
+ * permission, a merge refused outright — and calling every one an untracked-file collision
+ * sent the user hunting for a file that is not there, with an info exit (3) over an error.
+ *
+ * THE ROLLBACK IS `reset --keep`, NEVER `--hard`. The doctor window lasts up to 300 s, and an
+ * edit made in the checkout meanwhile is a tracked edit `--hard` would destroy without a word.
+ * `--keep` refuses instead when such an edit touches a file the rollback must change; that
+ * refusal is reported as itself — the user is left on the pulled commit, with the command to
+ * finish the rollback — rather than as a rollback that did not happen.
+ */
 export function pullAndValidate(log) {
   const [rc0, old] = gitRun(['rev-parse', 'HEAD']);
   if (rc0 !== 0 || !old) return [false, 'not_git', 'could not read HEAD'];
   log('[geneseed] fast-forwarding to upstream ...');
   const [rc1, , err] = gitRun(['merge', '--ff-only', '@{u}'], { timeout: 60 });
   if (rc1 !== 0) {
-    return [false, 'collision',
-      'Update blocked — a new upstream file collides with a local untracked '
-      + 'file. Move or remove it, then update.\n' + err];
+    if (/would be overwritten/.test(err)) {
+      return [false, 'collision',
+        'Update blocked — a new upstream file collides with a local untracked '
+        + 'file. Move or remove it, then update.\n' + err];
+    }
+    return [false, 'merge_failed', `Update failed — could not fast-forward to upstream.\n${err}`];
   }
   const [rc2, pulled] = gitRun(['log', '--oneline', '--no-decorate', '-20', `${old}..HEAD`]);
   if (rc2 === 0 && pulled) {
@@ -439,8 +465,15 @@ export function pullAndValidate(log) {
   const [passed, output] = runDoctor(ROOT);
   log(output.replace(/\n+$/, ''));
   if (!passed) {
-    gitRun(['reset', '--hard', old], { timeout: 60 });
+    const [rc3, , rerr] = gitRun(['reset', '--keep', old], { timeout: 60 });
     for (const line of DOCTOR_LEGEND) log(line);
+    if (rc3 !== 0) {
+      return [false, 'doctor_fail',
+        'the pulled source FAILS validation, and the rollback was REFUSED — a file it must '
+        + 'restore was edited while the doctor ran, and those edits were kept. You are still '
+        + `on the pulled commit; save your edits, then roll back with: git reset --keep ${old}\n`
+        + rerr];
+    }
     return [false, 'doctor_fail',
       'the pulled source FAILS validation — rolled back to the previous commit. '
       + 'Fix the problems listed above.'];
@@ -505,8 +538,9 @@ export function markerTheme(cfg, out) {
 }
 
 /**
- * `_config_theme(here)` — the theme the LOCAL `harness.config.json` asks for, captured
- * before SYNC overwrites it with upstream's. Fallback only; a bundle marker still wins.
+ * `_config_theme(here)` — the theme the checkout's `harness.config.json` asks for. Fallback
+ * only; a bundle marker still wins. Read before the pull, but nothing local is at stake: the
+ * file is tracked and `preflight` refuses a dirty tree, so the value read is the committed one.
  */
 export function configTheme(here) {
   try {
@@ -518,11 +552,16 @@ export function configTheme(here) {
 /**
  * `_migrate_stray_bundle` — move host state (context.json, memory/) from an OLD in-folder
  * bundle to the canonical sibling `out` BEFORE rebuilding, then drop the stray.
+ *
+ * "IS `out` THE STRAY ITSELF?" IS A PATH COMPARISON, NOT A STRING ONE. `GENESEED_OUT` is typed
+ * by a user, so on Windows `c:\x\Geneseed\harness` is the same directory as the stray and was a
+ * different string: the rescue was skipped as "nothing to move into", and the `rmSync` at the
+ * bottom then deleted the LIVE bundle — memory/ and context.json with it.
  */
 export function migrateStrayBundle(here, out, log) {
   const stray = path.join(String(here), 'Harness');
   const outStr = String(out);
-  if (outStr === stray) return;
+  if (comparePaths(path.resolve(outStr), path.resolve(stray)) === 0) return;
   try { if (!statSync(stray).isDirectory()) return; } catch { return; }
   mkdirSync(outStr, { recursive: true });
   const ctx = path.join(stray, 'context.json');
@@ -559,15 +598,40 @@ async function drainStdout() {
   await new Promise((resolve) => { process.stdout.write('', resolve); });
 }
 
+/**
+ * The flags that re-emit the install at `dir` on its OWN axes — footprint, posture, mode,
+ * trust, doctrine packs, excluded rules — or `[]` when no build ever wrote a marker there.
+ *
+ * WITHOUT THEM THE REBUILD RESETS THE INSTALL. The generator's defaults are not the install's:
+ * a missing `--footprint` is `lean`, and posture, mode, packs and excluded rules come from
+ * `harness.config.json`. So a `full`, mentor, narrowed or rule-excluded install was re-emitted
+ * as the config default — markers included — and `rebuild-all` right after reads those
+ * rewritten markers back through `installProfile`, so the loss stuck. `installProfile` is the
+ * one reader of an install's axes; this takes its answer rather than growing a second one.
+ *
+ * Only the TAIL of the argv is kept: theme and emit are `upgrade`'s to decide (a theme argument
+ * may override the marker), and `setupBuildArgs` opens with exactly those four tokens when it
+ * is given no out and no root.
+ */
+export async function installAxes(dir, { installProfile, setupBuildArgs }) {
+  if (!existsSync(path.join(String(dir), '.geneseed-emit'))) return [];
+  const p = installProfile('opencode', 'global', String(dir));
+  return setupBuildArgs('', 'files', null, null, p.footprint, p.posture, p.mode, p.doctrines,
+    undefined, p.excludeRules, p.trust).slice(4);
+}
+
 /**
  * `_rebuild_bundle` — render the bundle from the (already-updated) source and bounce a
- * running web daemon. Returns the build subprocess returncode (0 = ok).
+ * running web daemon. Returns the build subprocess returncode (0 = ok). `axes` is
+ * `installAxes` of the target, read before the pull; `bounce` is the daemon module's
+ * `bounceDaemonIfRunning`, loaded before the pull for the reason the file header gives.
  */
-export async function rebuildBundle(here, out, theme, emit, rootDir, log) {
+export async function rebuildBundle(here, out, theme, emit, rootDir, log, axes, bounce) {
   const buildArgs = ['--out', String(out)];
   if (theme) buildArgs.push('--theme', theme);
   if (emit === 'opencode') buildArgs.push('--emit', 'opencode', '--root', String(rootDir));
   else if (emit === 'opencode-global') buildArgs.push('--emit', 'opencode-global');
+  buildArgs.push(...axes);
   log(`[geneseed] rebuilding bundle -> ${out} (theme: ${theme || 'config default'}, emit: ${emit}) ...`);
   await drainStdout();
   // THE GENERATOR, RE-EXECUTED. `js/build/generate.mjs`'s `cmdBuild` calls `driverMain` in-process
@@ -580,7 +644,7 @@ export async function rebuildBundle(here, out, theme, emit, rootDir, log) {
   // If a web daemon is running, bounce it so the new source and the freshly rebuilt web/dist
   // take effect — otherwise the open PWA keeps hitting the old code. The web-job exception
   // (`upgrade/the-web-job-marker-...` gates it) lives with the helper.
-  await bounceDaemonIfRunning(theme, log);
+  await bounce(theme, log);
   return 0;
 }
 
@@ -636,6 +700,12 @@ export async function upgrade(ref = null, themeArg = null) {
     return p.kind === 'info' ? 3 : 1;
   }
 
+  // Loaded and read BEFORE the pull — see the file header for why the imports cannot wait, and
+  // `installAxes` for why the target's own axes must be carried into the rebuild.
+  const [generate, { bounceDaemonIfRunning }] = await Promise.all([
+    import('../build/generate.mjs'), import('../web/daemon.mjs')]);
+  const axes = await installAxes(emit === 'opencode-global' ? cfg : out, generate);
+
   log(`[geneseed] fetching from origin (git: ${which('git') || 'git'}, `
     + `timeout: ${fetchTimeout()}s) ...`);
   const [code, behind, err] = await measureUpstream(log);
@@ -647,6 +717,10 @@ export async function upgrade(ref = null, themeArg = null) {
       + 'Kerberos credentials). Restart it from that terminal: `geneseed web restart`.');
     return 1;
   }
+  if (code === 'no_upstream') {
+    log(`[geneseed] ${PRE_MSG.no_upstream[1]}`);
+    return 3;
+  }
   if (code === 'unrelated') {
     log('[geneseed] Upstream history was rewritten; back up local work, then re-clone '
       + 'or `git reset --hard @{u}`.');
@@ -676,7 +750,8 @@ export async function upgrade(ref = null, themeArg = null) {
   } catch (e) {
     log(`[geneseed] ⚠️  could not migrate the old in-folder bundle (${e && e.message ? e.message : e}) — continuing.`);
   }
-  let rc = await rebuildBundle(here, out, theme, emit, rootDir, log);
+  let rc = await rebuildBundle(here, out, theme, emit, rootDir, log, axes,
+    bounceDaemonIfRunning);
   if (rc !== 0) {
     log(`[geneseed][E-BUILD] ✗ the bundle build FAILED (theme: ${theme || 'default'}, emit: ${emit}).`);
     return 1;
@@ -886,13 +961,19 @@ function reexec(argv) {
  * `flushExportNotes()` runs BEFORE the handoff, deliberately: the re-exec replaces this process
  * and the update step's own improvements notice has scrolled past (or, under the reference's
  * curses arm, died with the alternate screen).
+ *
+ * A FAILED UPDATE STILL EXITS 1 AFTER THE HANDOFF. `setup` still runs — the user asked for it,
+ * and it can repair what the update could not — but its exit code used to become bootstrap's,
+ * so a script saw 0 over an update that never happened. `handoff` is the seam a test needs:
+ * the real `setup` exits 1 off a terminal, which would make the two answers indistinguishable.
  */
-export async function cmdBootstrap(args) {
+export async function cmdBootstrap(args, { handoff = reexec } = {}) {
   const failed = await bootstrapPlain();
   flushExportNotes();
   if (!args.noSetup) {
-    return reexec([process.execPath,
+    const rc = handoff([process.execPath,
       path.join(String(ROOT), 'bin', 'geneseed-cli.mjs'), 'setup']);
+    return failed ? 1 : rc;
   }
   // Scripted `bootstrap --no-setup` must not exit 0 over a failed update.
   return failed ? 1 : 0;

package/js/ui/anim.mjs

@@ -3,8 +3,8 @@
  *
  * P7c, and the one leftover of that phase that is NOT the declared curses panel. P5i ported
  * `_setup_lines` and left this out with a note — "belongs to P7 with the rest of the terminal
- * layer" — and the rest of the terminal layer turned out to be the panel, which stays
- * declared (`tests/test_tui_boundary.py` says why, and asserts it). This module is the part
+ * layer" — and the rest of the terminal layer turned out to be the panel, which was rejected
+ * (`tests/unit/no_panel.test.mjs` asserts it stays gone). This module is the part
  * that has nothing to do with curses: it draws on the ORDINARY terminal, with cursor-up
  * escapes and a sleep, and its only caller is a function that already crossed.
  *
@@ -23,16 +23,12 @@
  * needed — which is fortunate, because it is a `child_process` spawn and this port is barred
  * from those. The consequence is that the reference's `except Exception: return False` arm
  * around it has no counterpart here. That arm needs `cmd.exe` to be unlaunchable on a machine
- * that has already reached an interactive wizard, and `anim_ok` is compared over ten
- * environments in `tests/test_pure_function_parity.py` — none of which can produce it on
- * either side.
+ * that has already reached an interactive wizard.
  *
- * WHAT GATES IT. `tests/__snapshots__/primitives/{posix,win32}.json`, replayed by
- * `tests/snapshot/pure_snapshot.test.mjs`: `art_for` over every key plus the prototype-chain
- * names, `_place`/`_tile`/`_height` over their arithmetic, `anim_ok` over its whole decision
- * table, and `play_line` itself over 24 environments — captured on the reference side through
- * a real `TextIOWrapper`, so the CRLF translation is inside the recording rather than outside
- * it. There is no recorder left, so a red run means these functions moved, never the corpus.
+ * WHAT GATES IT. Little, now: the recorded snapshot corpus that replayed `art_for`, `_place`,
+ * `_tile`, `_height`, `anim_ok` and `play_line` is gone with the reference.
+ * `tests/unit/wizard.test.mjs` asserts the wizard still plays the animation, and in the right
+ * place; `tests/unit/no_panel.test.mjs` that this file is the one allowed its cursor escapes.
  */
 import { printOut } from '../lib/fs.mjs';
 import { parseIntStrict, codePointLength, padEndToWidth } from '../lib/text.mjs';
@@ -235,7 +231,7 @@ export function place(row, x, width) {
  * Python turns into an empty string and `String.repeat` turns into a RangeError, hence the
  * clamp. And `phase % len(tile)` is non-negative in Python for a positive divisor while
  * JavaScript keeps the sign of the dividend, so a negative phase indexes off the front of the
- * string instead of wrapping to the end. `_spin` had the same trap in P7b.
+ * string instead of wrapping to the end.
  */
 export function tile(tileStr, width, phase = 0) {
   if (!tileStr) return '';

package/js/ui/cli.mjs

@@ -10,7 +10,7 @@
  * copy in it.
  *
  * P10c's answer was to make the metadata DATA — generated into `cli.json` at the repo root by
- * `tests/gen_cli_reference.py` and read by both sides. P2 finishes the thought: the table is
+ * a since-deleted Python script and read by both sides. P2 finishes the thought: the table is
  * no longer GENERATED from anything, it is the OWNED document, and it lives here on a product
  * path because that is where a document npm ships belongs. `package.json`'s `files[]` already
  * carries `js/`, so it needs no row of its own, and nothing has to import out of `tests/`.
@@ -31,13 +31,9 @@
  * a file filtered for the page breaks the CLI, and a file in `cliSpec`'s shape cannot render
  * the docs. It stays exactly what the argparse walk produced.
  *
- * WHAT USED TO GUARD IT, AND WHAT DOES NOW. While the parser existed, `cliReferenceProblems()`
- * hashed `rituals/harness.py` and doctor reported drift on both binaries. That digest was over
- * a file this migration deletes, so it is gone; `tests/test_cli_reference.py` holds the
- * argparse-vs-table comparison, and it can only ever cover the rows argparse HAS: `catalog`,
- * `mcp` and `memory` never had a subparser and are outside it by construction. The successor
- * that checks the WHOLE table, and outlives the parser, is `tests/unit/cli_table.test.mjs`;
- * after that the table is simply the source of truth and is edited directly.
+ * WHAT GUARDS IT. The Python parser it was walked from is gone, and with it every comparison
+ * against argparse; the table is now simply the source of truth and is edited directly.
+ * `tests/unit/cli_table.test.mjs` checks the WHOLE table.
  *
  * THE COST, NAMED: this entry cannot parse anything without this file. `js/build/source.mjs`
  * already reads `harness.config.json` at import for every render, so a tracked data document
@@ -48,6 +44,7 @@ import { readFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { ROOT } from '../build/source.mjs';
+import { printOut } from '../lib/fs.mjs';
 import { parseIntStrict, stripWhitespace } from '../lib/text.mjs';
 
 const CLI_JSON = path.join(ROOT, 'js', 'cli-table.json');
@@ -156,8 +153,8 @@ function actionInvocation(a, positional) {
 // hyphenated word into two chunks, so it can break a line inside `back-compat` where a
 // space-only wrap cannot. Measured before deciding: every help string then in the table disagreed
 // with a greedy wrap at some width, the widest at 175 — so "the branch is dead" was simply
-// false, and `test_the_ports_line_breaker_is_textwrap_at_every_width` said so on the run that
-// first asserted it. The rules are transcribed instead.
+// false, and the former Python suite's every-width comparison against `textwrap` said so on
+// the run that first asserted it. The rules are transcribed instead.
 //
 // Python's classes, spelled for a `u`-flagged JavaScript regex: `\w` is letters, numbers and
 // underscore; `[^\d\W]` is that minus the DECIMAL digits, which leaves the letter-ish half
@@ -181,9 +178,8 @@ const WORDSEP = new RegExp(
  * `drop_whitespace`, `break_long_words` and `break_on_hyphens` all on, and the text already
  * whitespace-collapsed and stripped by the caller.
  *
- * ponytail: lives here rather than in `js/lib/` because `formatHelp` is its only consumer.
- * `rituals/_harness_tui*.py` calls `textwrap.wrap` in seven places and is declared unported;
- * move this when that changes, not before.
+ * ponytail: lives here rather than in `js/lib/` because `formatHelp` is its only consumer;
+ * move it when a second one appears, not before.
  */
 export function wrapText(text, width) {
   const chunks = text.split(WORDSEP).filter(Boolean).reverse();
@@ -310,7 +306,7 @@ function formatAction(a, positional, helpPosition, width) {
  * `parser.format_help()` for one subcommand, byte for byte with argparse.
  *
  * WHY THE PORT RENDERS THIS AT ALL. Task 10 compared the two implementations' `--help` for the
- * first time — `tests/harness_golden.py` has zero `--help` cells — and found the port answering
+ * first time — the former Python CLI matrix had zero `--help` cells — and found the port answering
  * `geneseed: error: unrecognized arguments: --help`, exit 2, on all 26 verbs. That is not the
  * declared wording divergence `parse`'s docblock reserves for argparse's ERROR text: it is the
  * absence of the surface, on the binary that survives the reference's deletion.
@@ -318,19 +314,19 @@ function formatAction(a, positional, helpPosition, width) {
  * `prog` IS AN ARGUMENT AND THAT IS THE ONE DELIBERATE DIVERGENCE. The reference names itself
  * `harness`, after the Python file this migration deletes; a user who typed `geneseed status
  * --help` is shown `usage: geneseed status`, which is also how every error this entry prints
- * already spells itself (`die`). `tests/__snapshots__/help/` freezes the reference's answers
- * and `tests/snapshot/cli_help.test.mjs` replays them through here with `prog` set to the reference's
- * own — so the layout is gated byte for byte and the rename is the only thing that moves.
+ * already spells itself (`die`). The former Python suite replayed the reference's recorded
+ * answers through here with `prog` set to the reference's own, so the layout was gated byte for
+ * byte and the rename was the only thing that moved. That corpus is gone; the layout is now
+ * pinned by the written-out `formatHelp` rows in `tests/unit/text_layout.test.mjs`.
  *
- * NOT EVERY VERB HAS A RECORDED ANSWER, AND THREE NEVER CAN. `catalog`, `mcp` and `memory` had
- * no subparser for the recorder to render from, so the corpus covers the verbs argparse
- * answered to and those three are held ABSOLUTELY instead — `tests/snapshot/cli_help.test.mjs` names
- * both populations (`RECORDED`, `NATIVE`) and fails a verb that falls into neither, which is
- * what keeps "no recorded text" from meaning "no gate".
+ * NOT EVERY VERB HAD A RECORDED ANSWER, AND THREE NEVER COULD. `catalog`, `mcp` and `memory` had
+ * no subparser for the recorder to render from, so they were held ABSOLUTELY instead — and
+ * `tests/unit/hook_cli.test.mjs`'s `NATIVE` list still names that population and fails a verb
+ * that falls into neither, which is what keeps "no recorded text" from meaning "no gate".
  *
  * The alias rides on the same argument: argparse gives `update` the parser object it built for
- * `upgrade`, so `harness.py update --help` prints `usage: harness upgrade`. The recorded prog
- * map reproduces that; the shipped call passes `geneseed update`, which is what the user typed.
+ * `upgrade`, so `harness.py update --help` printed `usage: harness upgrade`. The recorded prog
+ * map reproduced that; the shipped call passes `geneseed update`, which is what the user typed.
  *
  * `width` is argparse's `shutil.get_terminal_size().columns - 2`, passed in rather than read,
  * because a recorded help text whose wrap column came from the recorder's terminal is a corpus
@@ -407,12 +403,13 @@ export function formatHelp(cmd, prog, width) {
  *
  * `parseIntStrict`, NOT `Number.parseInt`, and the tree already owned it. `get_terminal_size` spells
  * this `int(os.environ['COLUMNS'])` inside `except (KeyError, ValueError)`, and `int` is not
- * `parseInt`. Measured against the reference over a corpus of `$COLUMNS` values
- * (`test_the_ports_help_width_is_shutil_get_terminal_size`): `COLUMNS=1_0` is 10 to Python and
+ * `parseInt`. Measured against the reference over a corpus of `$COLUMNS` values in the former
+ * Python suite (`tests/unit/cli_table.test.mjs`'s 'the help width is the terminal width less
+ * two, and COLUMNS wins' keeps a written-out part of it): `COLUMNS=1_0` is 10 to Python and
  * 1 to `parseInt`, `COLUMNS=٣` is 3 and NaN, `COLUMNS=' 80 '` is 80 and NaN. `COLUMNS=80abc`
  * is a ValueError to Python and 80 to `parseInt` — the same answer down a PIPE, where the
  * fallback is 80 either way, and a different one on any terminal that is not 80 wide, which is
- * why the corpus is the gate rather than a cell. A non-positive value falls through on both
+ * why a unit test is the gate rather than a cell. A non-positive value falls through on both
  * sides, which is Python's `if columns <= 0` and was already right here.
  *
  * `stripWhitespace` because THIS is the caller `parseIntStrict`'s docblock did not have: its other two
@@ -443,8 +440,7 @@ export function printVerbList(prog, verbs, extra = {}) {
     `A bare \`${prog}\` runs \`home\`. \`${prog} <command> --help\` describes one command.`, '',
     'commands:'];
   for (const n of names) lines.push(`  ${n.padEnd(pad)}${helpOf.get(n) || ''}`.trimEnd());
-  const text = `${lines.join('\n')}\n`;
-  process.stdout.write(process.platform === 'win32' ? text.replaceAll('\n', '\r\n') : text);
+  printOut(`${lines.join('\n')}\n`);
   return 0;
 }
 
@@ -453,18 +449,16 @@ export function printVerbList(prog, verbs, extra = {}) {
  * describe — the caller already owns that refusal and its message.
  *
  * ONE OWNER FOR TWO ENTRIES. `bin/geneseed-hook.mjs` carries the four hook verbs and
- * `bin/geneseed-cli.mjs` the rest of the table, and
- * `test_the_two_entry_points_carry_disjoint_verb_sets` keeps them from learning each other's
+ * `bin/geneseed-cli.mjs` the rest of the table, and `tests/unit/hook_cli.test.mjs`'s
+ * "the two entry points carry disjoint verb sets" keeps them from learning each other's
  * tables — so the help each prints has to come from here rather than from a copy in each.
  *
- * CRLF ON WINDOWS for `die`'s reason: argparse writes through a Python text stream, which
- * translates, and this text lands in the same terminals and the same pipes as that one.
+ * CRLF ON WINDOWS through `printOut`, the one funnel every CLI print takes.
  */
 export function printHelp(prog, verb) {
   const cmd = cliCommand(verb);
   if (cmd === null) return null;
-  const text = formatHelp(cmd, `${prog} ${verb}`, helpWidth());
-  process.stdout.write(process.platform === 'win32' ? text.replaceAll('\n', '\r\n') : text);
+  printOut(formatHelp(cmd, `${prog} ${verb}`, helpWidth()));
   return 0;
 }
 

package/js/ui/menu.mjs

@@ -22,8 +22,8 @@
  * still the right shape; only its explanation moved. The alternative that was considered and
  * refused: building a numbered line-menu out of `js/maintain/setup.mjs`'s `askChoice`. That is not a
  * port of `_main_menu` — it is a THIRD user interface, differing from the reference on every
- * screen, unreachable from every cell (no cell has a TTY), and it would have to be deleted
- * the day P7c lands the real panel. The fallback is the reference's own contract for "no
+ * screen, unreachable from every cell (no cell has a TTY), for a panel that was rejected
+ * outright rather than deferred. The fallback is the reference's own contract for "no
  * full-screen menu available here"; a new UI would not be.
  *
  * `cmd_home` is the default for a bare `geneseed`, and it crosses WHOLE. Its two arms are
@@ -32,10 +32,9 @@
  *
  * `_web_first_ok`'s FIVE REFUSALS ARE THE PAYLOAD, and only two of them are reachable from a
  * cell: a cell's stdin is a pipe, so `isTTY` is false and everything past it is dead. The
- * other three (SSH, the Linux display server, the browser) are gated by the corpus in
- * `tests/test_pure_function_parity.py`, which drives this function with `isTTY` FAKED — the
- * one input no cell can vary. See that file's P7a section for what it reaches and what it
- * declares.
+ * other three (SSH, the Linux display server, the browser) are gated by
+ * `tests/unit/web_first.test.mjs`, which drives this function through
+ * `tests/fixtures/pure_probe.mjs` with `isTTY` FAKED — the one input no cell can vary.
  */
 import { printOut, printErr } from '../lib/fs.mjs';
 import { which } from '../lib/paths.mjs';
@@ -93,13 +92,8 @@ export function cmdMenu() {
   // The reference's own `except Exception` arm, with a reason that is permanent here rather
   // than machine-dependent. stderr, and CRLF on Windows, because `sys.stderr.write` does.
   //
-  // P7b CORRECTED THE REASON RATHER THAN THE ARM. This module's header said the fallback was
-  // reached because "`import curses` fails on stock Windows Python", and P7b measured that
-  // to be false where it matters: `rituals/_harness_core.py` installs `rituals/_winterm.py`
-  // as `sys.modules["curses"]` when the stdlib module is missing, so the reference opens its
-  // panel on this machine and `tests/test_tui_boundary.py` drives it doing so. What is
-  // missing is on THIS side — there is no window implementation in the port — and that is
-  // what the message now says.
+  // The reason is on THIS side: there is no window implementation, by decision, and that is
+  // what the message says (`tests/unit/no_panel.test.mjs` keeps it so).
   // NOTHING TO POINT AT ANY MORE. The message used to end by sending the reader at the
   // Python panel, and P2 took the pointer out rather than re-aiming it: the panel it named
   // is the Python this migration deletes, and a refusal that sends a user to a file which