geneseed 2.0.0

package/js/mcp.mjs

@@ -0,0 +1,335 @@
+/**
+ * MCP server presets, state and config I/O — `rituals/_harness_mcp.py`'s MCP block.
+ *
+ * WHAT THE PLAN SAID AND WHAT READING FOUND. The P6f plan scored `api_mcp` + `api_mcp_toggle`
+ * at "~90 new, already in js/: `_mcp_load`/`readJsonc` (P6c), `settings.mjs`'s atomic write".
+ * Measured against `js/`: `readJsonc` had crossed and NOTHING ELSE HAD. `js/web/api.mjs`
+ * carries a five-line `mcpLoad` that is the no-host, comment-tolerant reader P6c needed for
+ * `wiki.jsonc`, which is one arm of one of these thirteen functions. `_MCP_PRESETS`,
+ * `_mcp_servers_key`, `_mcp_preset_block`, `_mcp_apply`, `_mcp_state`, `_mcp_set_enabled`,
+ * `_mcp_load`'s host fork, `_mcp_commented`, `_mcp_save`, `_mcp_config_for`,
+ * `_mcp_install_targets`, `_mcp_known_names` and `_mcp_meta` are 168 lines of Python, all
+ * new. The endpoints on top of them are the small half.
+ *
+ * AND `settings.mjs`'s ATOMIC WRITE IS NOT THIS ONE. `atomicWriteJson` is
+ * `_build_settings._atomic_write_json`; `_mcp_save` is a different function with a different
+ * temp suffix (`.tmp`, not `.geneseed-tmp`) that also creates the parent directory. Reusing
+ * the first would be right until the moment a write fails, which is the moment the temp
+ * file's name becomes the only evidence of what happened.
+ *
+ * THE ROUND TRIP IS THE HAZARD, and it is why every read here goes through `parseJson`.
+ * `_mcp_save` rewrites the WHOLE config, not the servers map — and for a Claude global
+ * install that config is `~/.claude.json`, which holds projects and history far beyond MCP
+ * wiring. A `JSON.parse` would turn every `"temperature": 1.0` in somebody's real file into
+ * `1` on the way back out. `readJsonc` already learned this; the strict-JSON fork has to
+ * learn it separately, because it does not go through `readJsonc` at all.
+ *
+ * A PyNumber IS AN OBJECT TO `typeof`, which is why `isDict` is spelled out rather than
+ * written as `typeof v === 'object'`. Python's `isinstance(x, dict)` is false for a float;
+ * the JS twin has to be false for its wrapper.
+ */
+import { existsSync, mkdirSync, renameSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { bobConfigDir, copilotConfigDir, pyResolve } from './hosts.mjs';
+import { installState, installTargets } from './installs.mjs';
+import { jsonDumpsIndent, parseJson, pyLjust, pyPrint, pyPrintErr, readText, writeText }
+  from './lib/fs.mjs';
+import { opencodeTarget, readJsonc } from './settings.mjs';
+
+/**
+ * `isinstance(x, dict)` for a value that came out of `json.loads`.
+ *
+ * A JSON value is null, a boolean, a string, a NUMBER, an array or an object — and
+ * `parseJson` hands numbers back wrapped, so `typeof v === 'object'` says yes to a float.
+ * `constructor === Object` is the plain-object test, and every object `JSON.parse` builds
+ * is one.
+ */
+const isDict = (v) => v !== null && v !== undefined && typeof v === 'object'
+  && v.constructor === Object;
+
+/** `dict.get(key, default)`. */
+const dget = (obj, key, dflt) => (isDict(obj) && Object.hasOwn(obj, key) ? obj[key] : dflt);
+
+/** The hosts whose MCP config is strict JSON under `mcpServers`, with no `enabled` flag. */
+const FLAGLESS = ['claude', 'bob', 'copilot'];
+
+/**
+ * `_harness_mcp._MCP_PRESETS` — the ready-to-wire servers the MCP screen can toggle.
+ *
+ * The `desc` strings go on the wire verbatim (`api_mcp` returns them), so they are the one
+ * place in this file where a byte matters more than the shape. Insertion order is the
+ * listing order.
+ */
+export const MCP_PRESETS = {
+  markitdown: {
+    label: 'MarkItDown',
+    desc: 'PDF / Office / HTML -> Markdown for the ingest skill. Runs via `uvx` '
+      + '(needs uv; zero-install, fetches on first call). No uv? Switch the command '
+      + 'to ["markitdown-mcp"] after `pipx install markitdown-mcp`. Exposes one '
+      + 'tool: convert_to_markdown(uri).',
+    block: { type: 'local', command: ['uvx', 'markitdown-mcp'], enabled: true },
+  },
+  gitlab: {
+    label: 'GitLab',
+    desc: 'GitLab repo / MR / issue / CI tools via @zereight/mcp-gitlab (npx, no '
+      + 'install). Edit GITLAB_PERSONAL_ACCESS_TOKEN (scopes: api, read_repository) '
+      + 'and GITLAB_API_URL before use. Add a second entry (gitlab-2) for another '
+      + 'instance.',
+    block: {
+      type: 'local',
+      command: ['npx', '-y', '@zereight/mcp-gitlab'],
+      environment: { GITLAB_PERSONAL_ACCESS_TOKEN: '',
+        GITLAB_API_URL: 'https://gitlab.com/api/v4' },
+      enabled: true,
+    },
+  },
+  'gitlab-2': {
+    label: 'GitLab (2nd instance)',
+    desc: 'A second GitLab instance (e.g. a self-hosted server) via the same '
+      + '@zereight/mcp-gitlab command. Point GITLAB_API_URL at the other instance '
+      + "and give it that instance's own token.",
+    block: {
+      type: 'local',
+      command: ['npx', '-y', '@zereight/mcp-gitlab'],
+      environment: { GITLAB_PERSONAL_ACCESS_TOKEN: '',
+        GITLAB_API_URL: 'https://gitlab.example.com/api/v4' },
+      enabled: true,
+    },
+  },
+  filesystem: {
+    label: 'Filesystem',
+    desc: 'Read/write files under explicitly allowed directories via '
+      + '@modelcontextprotocol/server-filesystem (npx, no install). Replace the '
+      + 'trailing path arg(s) with only the dir(s) the agent may touch '
+      + '(least-privilege).',
+    block: {
+      type: 'local',
+      command: ['npx', '-y', '@modelcontextprotocol/server-filesystem',
+        '/path/to/allowed/dir'],
+      enabled: true,
+    },
+  },
+};
+
+/** `_mcp_servers_key` — OpenCode nests servers under `mcp`, the other three `mcpServers`. */
+const serversKey = (host) => (FLAGLESS.includes(host) ? 'mcpServers' : 'mcp');
+
+/** `(config.get(key) or {})` — the servers map, or an empty one. */
+const serversOf = (config, host) => {
+  const s = dget(config, serversKey(host), null);
+  return isDict(s) ? s : {};
+};
+
+/**
+ * `_mcp_preset_block` — the block to WRITE for a preset, shaped for `host`.
+ *
+ * OpenCode takes it verbatim. The flagless three split the command list into `command`
+ * (head) + `args` (tail) and rename `environment` to `env`; Copilot additionally requires
+ * `type` and a `tools` allowlist.
+ */
+export function mcpPresetBlock(name, host = 'opencode') {
+  const block = { ...MCP_PRESETS[name].block };
+  if (!FLAGLESS.includes(host)) return block;
+  const cmd = [...(block.command || [])];
+  const out = { command: cmd.length ? cmd[0] : '', args: cmd.slice(1) };
+  const env = block.environment;
+  if (env) out.env = { ...env };
+  if (host === 'copilot') {
+    out.type = 'local';
+    out.tools = ['*'];
+  }
+  return out;
+}
+
+/**
+ * `_mcp_apply` — a COPY of `config` with server `name` set to `block`, or removed when
+ * `block` is null. Never touches another key; drops an emptied servers map.
+ *
+ * The key ORDER is behaviour, not cosmetics: `setdefault` appends `$schema` at the end of a
+ * fresh dict and leaves an existing one where it is, and `_mcp_save` writes the result out
+ * as the file the user then reads. `{...config}` plus a guarded assignment is the same rule.
+ */
+export function mcpApply(config, name, block, host = 'opencode') {
+  const cfg = { ...config };
+  const key = serversKey(host);
+  if (host === 'opencode' && !Object.hasOwn(cfg, '$schema')) {
+    cfg.$schema = 'https://opencode.ai/config.json';
+  }
+  const servers = { ...serversOf(cfg, host) };
+  if (block === null) delete servers[name];
+  else servers[name] = block;
+  if (Object.keys(servers).length) cfg[key] = servers;
+  else delete cfg[key];
+  return cfg;
+}
+
+/**
+ * `_mcp_state` — 'enabled' | 'disabled' | 'absent'.
+ *
+ * OpenCode: a present server with no explicit `enabled` counts as enabled (its default).
+ * The flagless three have no such key, so present IS enabled and 'disabled' never occurs —
+ * toggling one off removes its entry instead.
+ */
+export function mcpState(config, name, host = 'opencode') {
+  const server = serversOf(config, host)[name];
+  if (!isDict(server)) return 'absent';
+  if (FLAGLESS.includes(host)) return 'enabled';
+  return dget(server, 'enabled', true) ? 'enabled' : 'disabled';
+}
+
+/** `_mcp_set_enabled` — flip a present server's enabled-ness. No-op when it is absent. */
+export function mcpSetEnabled(config, name, enabled, host = 'opencode') {
+  const server = serversOf(config, host)[name];
+  if (!isDict(server)) return config;
+  if (FLAGLESS.includes(host)) {
+    return enabled ? config : mcpApply(config, name, null, host);
+  }
+  return mcpApply(config, name, { ...server, enabled }, host);
+}
+
+/**
+ * `_mcp_load` — a config as a dict; `{}` when missing, unreadable, unparseable or not an
+ * object.
+ *
+ * The host fork is the whole function. OpenCode is read comment-tolerantly because a
+ * hand-maintained `opencode.jsonc` carries `//`; the other three are read STRICTLY, because
+ * the comment stripper's trailing-comma pass is not string-aware and would silently drop a
+ * comma from any string value containing `,]` — in a file that holds projects and history.
+ */
+export function mcpLoad(p, host = 'opencode') {
+  if (!existsSync(p)) return {};
+  let text;
+  try {
+    text = readText(p);
+  } catch {
+    return {};
+  }
+  if (FLAGLESS.includes(host)) {
+    let data;
+    try {
+      data = parseJson(text);
+    } catch {
+      return {};
+    }
+    return isDict(data) ? data : {};
+  }
+  const [data] = readJsonc(text);
+  return isDict(data) ? data : {};
+}
+
+/** `_mcp_commented` — an existing `.jsonc` that carries comments, which must not be rewritten. */
+export function mcpCommented(p) {
+  if (path.extname(p) !== '.jsonc' || !existsSync(p)) return false;
+  try {
+    const [, had] = readJsonc(readText(p));
+    return had;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `_mcp_save` — pretty JSON, written ATOMICALLY through a sibling temp file.
+ *
+ * Not `atomicWriteJson`: that is `_build_settings._atomic_write_json`, whose temp file is
+ * named `.geneseed-tmp` and which does not create the parent directory. Two Python
+ * functions, two twins.
+ */
+export function mcpSave(p, config) {
+  mkdirSync(path.dirname(p), { recursive: true });
+  const tmp = `${p}.tmp`;
+  writeText(tmp, `${jsonDumpsIndent(config)}\n`);
+  renameSync(tmp, p);
+}
+
+/**
+ * `_mcp_config_for` — the file an install writes its MCP servers into, or null for a host
+ * that carries no MCP wiring at that scope.
+ */
+export function mcpConfigFor(host, scope, root) {
+  if (host === 'opencode') return opencodeTarget(path.join(root, 'opencode.json'));
+  if (host === 'claude') {
+    return scope === 'project' ? path.join(root, '.mcp.json')
+      : pyResolve(path.join(os.homedir(), '.claude.json'));
+  }
+  if (host === 'bob') {
+    return scope === 'project' ? path.join(root, '.bob', 'settings.json')
+      : path.join(bobConfigDir(), 'settings.json');
+  }
+  if (host === 'copilot') {
+    // The Copilot CLI reads MCP servers from ~/.copilot/mcp-config.json only — no per-repo
+    // file is documented, so a project install carries no MCP wiring.
+    return scope === 'global' ? path.join(copilotConfigDir(), 'mcp-config.json') : null;
+  }
+  return null;
+}
+
+/** `_mcp_install_targets` — (label, configFile, host, scope, installRoot) per detected install. */
+export function mcpInstallTargets() {
+  const out = [];
+  for (const [host, scope, root] of installTargets()) {
+    const cfg = mcpConfigFor(host, scope, root);
+    if (cfg !== null) out.push([`${scope} config`, cfg, host, scope, root]);
+  }
+  return out;
+}
+
+/** `_mcp_known_names` — the presets first, then any server already in THIS config. */
+export function mcpKnownNames(config, host = 'opencode') {
+  const names = Object.keys(MCP_PRESETS);
+  const present = isDict(config) ? Object.keys(serversOf(config, host)) : [];
+  return names.concat(present.filter((n) => !Object.hasOwn(MCP_PRESETS, n)));
+}
+
+/** `_mcp_meta` — (label, description); the bare name and a generic note for an unknown one. */
+export function mcpMeta(name) {
+  const p = MCP_PRESETS[name];
+  if (p) return [p.label, p.desc];
+  return [name, 'User-defined MCP server (not a Harness preset). It lives in this '
+    + "config already — 'e' enables/disables it, Enter removes it."];
+}
+
+export { isDict };
+
+// ---- the verb ----------------------------------------------------------------------------
+
+/**
+ * `geneseed mcp` — the CLI FACE this library never had.
+ *
+ * Everything above crossed with the web console rather than with a subcommand: the reference
+ * kept it as a preset/state library whose only command was the uninstall path, and the one
+ * way to see which servers an install had wired was to start a server and look. That is the
+ * gap this verb closes, and it closes it by CALLING the library — the same `mcpInstallTargets`
+ * / `mcpLoad` / `mcpKnownNames` / `mcpState` / `mcpMeta` sequence the console's read endpoint
+ * runs, rendered as text instead of as JSON.
+ *
+ * ponytail: READ-ONLY, on purpose, and this is the ceiling. Wiring a server from here needs
+ * the console's toggle orchestration, whose load-bearing part is not the toggle at all — it
+ * is the refusal to rewrite a config it could not parse strictly, because for a global
+ * Claude install that file holds projects and history and a rewrite from an empty object
+ * would erase them. A second copy of that guard is a second place for it to be wrong. When a
+ * terminal toggle is wanted, move the console's non-HTTP core down into this module and have
+ * both faces call it; do not grow a parallel one here.
+ */
+export function cmdMcp() {
+  const targets = mcpInstallTargets()
+    .filter(([, , host, scope, root]) => installState(root, host, scope) === 'active');
+  if (!targets.length) {
+    pyPrintErr('[mcp] no active Geneseed install found. Run `geneseed setup` first.\n');
+    return 1;
+  }
+  for (const [label, p, host] of targets) {
+    const cfg = mcpLoad(p, host);
+    pyPrint(`[mcp] ${host} ${label}: ${p}${existsSync(p) ? '' : ' (not written yet)'}\n`);
+    if (mcpCommented(p)) {
+      pyPrint('  this config carries comments — edit it by hand so they survive.\n');
+    }
+    for (const name of mcpKnownNames(cfg, host)) {
+      const [lbl] = mcpMeta(name);
+      pyPrint(`  ${pyLjust(mcpState(cfg, name, host), 8)}  ${pyLjust(name, 12)}  ${lbl}\n`);
+    }
+  }
+  return 0;
+}

package/js/memory.mjs

@@ -0,0 +1,108 @@
+/**
+ * `geneseed memory` — the memory store from a terminal.
+ *
+ * WHY THIS VERB IS NEW RATHER THAN PORTED. The reference had no `memory` subcommand: a fact
+ * could be written by the `learn` hook and deleted from the web console, and there was no
+ * third way. So the semantics here are the DELETE ENDPOINT's, deliberately and field for
+ * field — the same reserved names, the same "a bare slug, never a path" rule, the same
+ * index line dropped from MEMORY.md after the file goes — because two ways to remove a fact
+ * that disagree about what a fact is would be worse than one way.
+ *
+ * WHERE IT PARTS COMPANY WITH THE ENDPOINT, AND WHY. Two places, both forced by the
+ * difference between a browser talking to a running server and a person typing in a shell:
+ *
+ *   * THE STORE IS RESOLVED, NOT CONFIGURED. The endpoint is always `<target>/memory`,
+ *     because a server has a target. A CLI has a cwd, so this takes the resolver every other
+ *     terminal-side reader of the store already uses — `$GENESEED_MEMORY`, then a store
+ *     beside the cwd, then the global config dir — with `--memory` as the explicit override.
+ *     `status` prints the answer of that same resolver, so the two agree about which store
+ *     is "the" store.
+ *   * THE RESERVED-NAME CHECK IS CASE-INSENSITIVE, WHICH THE ENDPOINT'S IS NOT. It compares
+ *     `MEMORY` and `README` exactly. On a case-insensitive filesystem — which is every
+ *     Windows install and the default macOS one — `rm memory` then resolves to the index
+ *     file, passes the guard, and deletes the thing the agent reads at session start. This
+ *     is a NARROWING of what the endpoint accepts, on a destructive path, and it is the one
+ *     divergence in this file that is not about resolution.
+ *
+ * `memoryDropIndex` is the hook module's, not a copy: writing the fact and unwriting its
+ * index line are two halves of one format, and the half that writes lives there.
+ */
+import { readdirSync, statSync, unlinkSync } from 'node:fs';
+import path from 'node:path';
+
+import { memoryDropIndex } from './hooks.mjs';
+import { resolveMemoryDir } from './hosts.mjs';
+import { pyPrint, pyPrintErr } from './lib/fs.mjs';
+
+const isFile = (p) => { try { return statSync(p).isFile(); } catch { return false; } };
+
+/**
+ * The two names the store owns rather than holds: the index the agent reads at session
+ * start, and the file that documents the store. `api_memory_delete` refuses both.
+ */
+const RESERVED = ['memory', 'readme'];
+
+/** Whether `name` is a fact this verb may act on — the endpoint's rule, plus the case fold. */
+export function isFactName(name) {
+  return Boolean(name) && !name.includes('/') && !name.includes('\\')
+    && !RESERVED.includes(name.toLowerCase());
+}
+
+/**
+ * The removable facts in `dir`, as bare slugs, sorted.
+ *
+ * DERIVED FROM `isFactName` RATHER THAN FROM ITS OWN FILTER, so a listing can never offer a
+ * name the removal then refuses, and can never hide one it would accept.
+ */
+export function memoryFacts(dir) {
+  let names;
+  try { names = readdirSync(dir); } catch { return []; }
+  return names.filter((n) => n.endsWith('.md') && isFile(path.join(dir, n)))
+    .map((n) => n.slice(0, -3)).filter(isFactName).sort();
+}
+
+/** `api_memory_delete`, minus the HTTP: the file, then its line in the index. */
+export function memoryDelete(dir, name) {
+  if (!isFactName(name)) return false;
+  const p = path.join(dir, `${name}.md`);
+  if (!isFile(p)) return false;
+  unlinkSync(p);
+  memoryDropIndex(dir, name);
+  return true;
+}
+
+/** The verb. */
+export function cmdMemory(args) {
+  const dir = resolveMemoryDir(args.memory);
+  if (dir === null) {
+    // The resolver answers null for "no store anywhere on the chain", which is also what an
+    // explicit `--memory` that is not a directory gives — so the message names both.
+    pyPrintErr('[memory] no memory store found. Pass --memory <dir>, set $GENESEED_MEMORY, '
+      + 'or run this from a directory with a memory/ store.\n');
+    return 1;
+  }
+  if (args.action === 'list') {
+    const facts = memoryFacts(dir);
+    if (!facts.length) {
+      pyPrint(`[memory] ${dir}: no facts.\n`);
+      return 0;
+    }
+    pyPrint(`[memory] ${dir}\n`);
+    for (const name of facts) pyPrint(`  ${name}\n`);
+    return 0;
+  }
+  if (!args.name) {
+    pyPrintErr('[memory] rm needs the name of a fact.\n');
+    return 2;
+  }
+  if (!memoryDelete(dir, args.name)) {
+    // ONE MESSAGE FOR BOTH REFUSALS, which is the endpoint's shape too — it raises the same
+    // `NotFound(name)` for a reserved name, a name with a separator and a fact that is not
+    // there. Telling a caller that `MEMORY` exists but is protected is a distinction this
+    // verb has no reason to draw.
+    pyPrintErr(`[memory] no such fact '${args.name}' in ${dir}.\n`);
+    return 1;
+  }
+  pyPrint(`[memory] deleted ${args.name}.\n`);
+  return 0;
+}

package/js/menu.mjs

@@ -0,0 +1,118 @@
+/**
+ * `menu` and `home` — `rituals/_harness_menu.py`'s two dispatchers.
+ *
+ * WHAT CROSSES HERE AND WHAT DOES NOT, said plainly, because this is the one module in the
+ * port whose Python twin is 3,398 lines and whose Node twin is ninety.
+ *
+ * `cmd_menu` is a FORK, not a menu. Off a TTY it prints five lines of command list and
+ * returns 0; on a TTY it hands control to `curses.wrapper(_main_menu)` — the full-screen
+ * panel, which is P7c's and is not here. The fork's off-TTY arm is what every cell of this
+ * port can reach, and it is ported byte for byte.
+ *
+ * ON A TTY, THIS ENTRY FALLS BACK RATHER THAN INVENTING A SECOND MENU. The reference already
+ * has that behaviour: `cmd_menu` wraps the panel in `except Exception`, writes `[menu] TUI
+ * unavailable (<reason>)` to stderr and prints the same command list. Node's reason is
+ * permanent rather than accidental, and it is stated as such.
+ *
+ * ⚠ THE REASON THIS HEADER ORIGINALLY GAVE WAS WRONG, and P7b measured it: it said the
+ * reference reaches that arm often because "`import curses` fails on stock Windows Python".
+ * A bare `import curses` does fail here, but `rituals/_harness_core.py` installs
+ * `rituals/_winterm.py` under the name `curses` when it does — so inside the harness the
+ * import succeeds, the panel opens, and it is the PORT that has no window. The fallback is
+ * still the right shape; only its explanation moved. The alternative that was considered and
+ * refused: building a numbered line-menu out of `js/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
+ * 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
+ * `_web_first_ok()` — the web console, which is P6h's `startDaemon` and is fully ported —
+ * and `cmd_menu` above. Nothing in it was deferred.
+ *
+ * `_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.
+ */
+import { pyPrint, pyPrintErr, pyWhich } from './lib/fs.mjs';
+import { startDaemon } from './web/server.mjs';
+
+/** `_menu_help` — the off-TTY arm, and the fallback both TTY arms end in. */
+export function menuHelp() {
+  pyPrint('Geneseed — no interactive menu here. Get started with:  geneseed setup\n');
+  pyPrint('Other commands:  bootstrap · update · build · doctor · diff · tui · web\n');
+  pyPrint('On a VT-capable terminal, a bare `./geneseed` opens the interactive menu of these.\n');
+  return 0;
+}
+
+/**
+ * `webbrowser.get()`, which raises `webbrowser.Error` when nothing on the machine can open
+ * a URL — and has no Node equivalent, because there is no stdlib registry of browsers.
+ *
+ * The twin answers the question this program actually needs: can `openUrl` (js/web/server.mjs)
+ * do its job? That makes the answer PER PLATFORM and identical to what `openUrl` will run —
+ * `cmd /c start` on Windows and `open` on macOS are OS builtins that are always there, and
+ * everywhere else it is `xdg-open`, which is not.
+ *
+ * DECLARED DIVERGENCE: on Linux the reference consults `$BROWSER` and a list of a dozen
+ * browser binaries before giving up, so a box with `firefox` on PATH and no `xdg-open`
+ * answers True there and false here. It is unreachable from this port's machine (the
+ * previous branch already returned false without a display server, and Windows never gets
+ * here), and closing it would mean reproducing `webbrowser`'s registry — a table of browser
+ * names that would go stale silently, which is the shape this port refuses.
+ */
+function browserAvailable() {
+  if (process.platform === 'win32' || process.platform === 'darwin') return true;
+  return pyWhich('xdg-open') !== null;
+}
+
+/**
+ * `_web_first_ok` — whether a bare `geneseed` opens the web UI rather than the TUI menu.
+ * Deliberately conservative in the reference and here: any doubt falls back to the menu, so
+ * a server box is never dropped into a browser launch that cannot open.
+ */
+export function webFirstOk() {
+  if (process.env.GENESEED_NO_WEB) return false;
+  // `process.stdin.isTTY` is `true` or UNDEFINED — never `false` — which is why this is a
+  // truthiness test and not a comparison.
+  if (!process.stdin.isTTY) return false;
+  if (process.env.SSH_CONNECTION || process.env.SSH_TTY) return false;
+  // On Linux a browser needs a display server; macOS/Windows always have a GUI.
+  if (process.platform === 'linux'
+      && !(process.env.DISPLAY || process.env.WAYLAND_DISPLAY)) return false;
+  return browserAvailable();
+}
+
+/** `cmd_menu`. See this module's header for why the TTY arm falls back. */
+export function cmdMenu() {
+  if (!process.stdin.isTTY) return menuHelp();
+  // 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.
+  // 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
+  // will not be there is worse than one that simply says the screen does not exist.
+  pyPrintErr('[menu] TUI unavailable (this entry has no full-screen menu).\n');
+  return menuHelp();
+}
+
+/** `cmd_home` — the default for a bare `geneseed`. */
+export async function cmdHome(args) {
+  if (webFirstOk()) {
+    pyPrint('[geneseed] opening the web console — `geneseed menu` for the terminal UI, '
+      + 'GENESEED_NO_WEB=1 to disable.\n');
+    return startDaemon(null, 4747, true);
+  }
+  return cmdMenu(args);
+}