geneseed 2.0.0

package/js/lib/proc.mjs

@@ -0,0 +1,28 @@
+/**
+ * The spawn flag — one rule for every child process this tool starts, in one place.
+ *
+ * Windows gives every console child of a CONSOLE-LESS parent a brand-new console window.
+ * The web daemon is console-less by design (`DETACHED_PROCESS`), so without this flag every
+ * short-lived process it shells out to pops a window and closes it — the Doctor page is the
+ * 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
+ * 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
+ * a recorded corpus cannot be the gate here. A shared constant plus
+ * `tests/unit/spawn_hygiene.test.mjs` is what makes the next spawn site inherit the answer
+ * instead of re-deciding it.
+ *
+ * CAPTURING SPAWNS ONLY, and the asymmetry is deliberate. The rule was measured on Windows:
+ * a process that sets `STARTF_USESTDHANDLES` only when a stream is redirected gives an
+ * INHERITING child spawned with `CREATE_NO_WINDOW` a fresh hidden console and discards
+ * everything it prints — `geneseed build > log.txt` wrote an empty file. libuv always passes
+ * the handles explicitly, so the flag on an inheriting spawn would be harmless here; it stays
+ * off anyway, because an inheriting child of a console-owning parent shows no window in the
+ * first place, so it would buy nothing and re-open a failure mode already paid for once.
+ */
+export const NO_WINDOW = { windowsHide: process.platform === 'win32' };

package/js/lib/udiff.mjs

@@ -0,0 +1,275 @@
+/**
+ * The unified diff — this tool's sequence matcher, and the hunks it produces.
+ *
+ * WHY A HAND-WRITTEN MATCHER RATHER THAN A LIBRARY. The diff is the ENTIRE user-visible
+ * payload of `geneseed diff`: the hunks in `--full` and in the exported improvements file
+ * are this file's output and nothing else's. A generic JS diff would produce a CORRECT diff
+ * and a DIFFERENT one, and `tests/__snapshots__/primitives/` compares the hunks character
+ * for character, so "also a valid diff" fails every cell. The alignment below IS the
+ * specification of what this tool prints, and three of its choices are choices no other
+ * algorithm makes:
+ *
+ *   * It is NOT Myers. `findLongestMatch` takes the longest common block, recurses left and
+ *     right, and therefore prefers a different alignment than an edit-script minimiser
+ *     wherever the two disagree.
+ *   * Ties resolve to the EARLIEST match, in `a` first and then in `b`, because `bestsize` is
+ *     only replaced on a strict `>`.
+ *   * **`autojunk`.** For a `b` of 200 elements or more, any line occurring more than
+ *     `floor(len(b) / 100) + 1` times is deleted from the index and stops matching entirely.
+ *     On this tool's own files — hundreds of lines, many of them blank — that fires
+ *     constantly and changes the hunks. It is off by construction for anything shorter, so a
+ *     small fixture cannot see it at all; the recorded corpus is what carries inputs long
+ *     enough to trip it.
+ *
+ * PROVENANCE, not a contract with a live second party. Every rule above was measured from
+ * CPython's `difflib`, which is why the odd ones are odd — `autojunk` in particular is a
+ * heuristic no one would invent from scratch. That history explains the shape; it does not
+ * govern it any more. The recording does, and the recording cannot be re-blessed.
+ *
+ * No junk predicate is implemented: every call site is `opcodes(a, b)` with no `isjunk`, so
+ * the junk set is empty and its test is constant false. That deletes two of the four
+ * extension loops in `findLongestMatch` — noted here rather than left as an unexplained
+ * absence, because their omission is a consequence of the call sites and not of the
+ * algorithm.
+ */
+
+/**
+ * `SequenceMatcher.__chain_b` — b's element index, minus the popular elements.
+ *
+ * A `Map`, never an object: the elements are LINES, and a file whose first line is `0` would
+ * have its index hoisted to the front of an object literal (the P3a hazard). Nothing here
+ * iterates `b2j`, so the hoist would be invisible until the day something did.
+ */
+function chainB(b, autojunk) {
+  const b2j = new Map();
+  for (let i = 0; i < b.length; i += 1) {
+    const cur = b2j.get(b[i]);
+    if (cur === undefined) b2j.set(b[i], [i]);
+    else cur.push(i);
+  }
+  const n = b.length;
+  if (autojunk && n >= 200) {
+    const ntest = Math.floor(n / 100) + 1;
+    for (const [elt, idxs] of [...b2j]) {
+      if (idxs.length > ntest) b2j.delete(elt);
+    }
+  }
+  return b2j;
+}
+
+/**
+ * `SequenceMatcher.find_longest_match`, with `isbjunk` constant False.
+ *
+ * `j2len` is a `Map` keyed by INTEGER j, where the Python uses a dict. Nothing iterates it
+ * either, so the key type is only about lookup; a plain object would coerce every key to a
+ * string and work, and a Map says what the keys are.
+ */
+function findLongestMatch(a, b, b2j, alo, ahi, blo, bhi) {
+  let besti = alo;
+  let bestj = blo;
+  let bestsize = 0;
+  let j2len = new Map();
+  for (let i = alo; i < ahi; i += 1) {
+    const newj2len = new Map();
+    for (const j of b2j.get(a[i]) ?? []) {
+      if (j < blo) continue;
+      if (j >= bhi) break;
+      const k = (j2len.get(j - 1) ?? 0) + 1;
+      newj2len.set(j, k);
+      // A strict `>`: a later match of equal length never displaces an earlier one, which is
+      // what makes the result the FIRST longest block rather than the last.
+      if (k > bestsize) { besti = i - k + 1; bestj = j - k + 1; bestsize = k; }
+    }
+    j2len = newj2len;
+  }
+  // The two junk-free extension loops. The popular elements `chainB` dropped are NOT junk —
+  // `bjunk` stays empty — so a popular line adjacent to a match is still extended over here
+  // even though it could never have started one. That asymmetry is the Python's.
+  while (besti > alo && bestj > blo && a[besti - 1] === b[bestj - 1]) {
+    besti -= 1; bestj -= 1; bestsize += 1;
+  }
+  while (besti + bestsize < ahi && bestj + bestsize < bhi
+    && a[besti + bestsize] === b[bestj + bestsize]) {
+    bestsize += 1;
+  }
+  return [besti, bestj, bestsize];
+}
+
+/** `SequenceMatcher.get_matching_blocks` — the recursion, the sort, and the adjacent merge. */
+function matchingBlocks(a, b, b2j) {
+  const la = a.length;
+  const lb = b.length;
+  const queue = [[0, la, 0, lb]];
+  const blocks = [];
+  while (queue.length) {
+    // `queue.pop()` — LIFO, as the Python. The order reaches the output through the sort
+    // below only when two blocks tie, which they cannot, so this is faithfulness rather
+    // than necessity.
+    const [alo, ahi, blo, bhi] = queue.pop();
+    const [i, j, k] = findLongestMatch(a, b, b2j, alo, ahi, blo, bhi);
+    if (k) {
+      blocks.push([i, j, k]);
+      if (alo < i && blo < j) queue.push([alo, i, blo, j]);
+      if (i + k < ahi && j + k < bhi) queue.push([i + k, ahi, j + k, bhi]);
+    }
+  }
+  // `list.sort()` on tuples is lexicographic; `Array.prototype.sort` is string-wise by
+  // default and would put [10,...] before [9,...].
+  blocks.sort((x, y) => x[0] - y[0] || x[1] - y[1] || x[2] - y[2]);
+
+  let i1 = 0;
+  let j1 = 0;
+  let k1 = 0;
+  const nonAdjacent = [];
+  for (const [i2, j2, k2] of blocks) {
+    if (i1 + k1 === i2 && j1 + k1 === j2) {
+      k1 += k2;
+    } else {
+      if (k1) nonAdjacent.push([i1, j1, k1]);
+      i1 = i2; j1 = j2; k1 = k2;
+    }
+  }
+  if (k1) nonAdjacent.push([i1, j1, k1]);
+  nonAdjacent.push([la, lb, 0]);
+  return nonAdjacent;
+}
+
+/** `SequenceMatcher.get_opcodes` — [tag, i1, i2, j1, j2]. */
+export function opcodes(a, b, { autojunk = true } = {}) {
+  const b2j = chainB(b, autojunk);
+  let i = 0;
+  let j = 0;
+  const answer = [];
+  for (const [ai, bj, size] of matchingBlocks(a, b, b2j)) {
+    let tag = '';
+    if (i < ai && j < bj) tag = 'replace';
+    else if (i < ai) tag = 'delete';
+    else if (j < bj) tag = 'insert';
+    if (tag) answer.push([tag, i, ai, j, bj]);
+    i = ai + size;
+    j = bj + size;
+    if (size) answer.push(['equal', ai, i, bj, j]);
+  }
+  return answer;
+}
+
+/**
+ * `SequenceMatcher.get_grouped_opcodes` — the hunks, with `n` lines of context.
+ *
+ * Returns a list rather than a generator: the Python's caller is a `for` loop that consumes
+ * it once, and a lazy JS equivalent would buy nothing but a second shape to reason about.
+ */
+export function groupedOpcodes(a, b, n = 3, opts) {
+  let codes = opcodes(a, b, opts);
+  if (!codes.length) codes = [['equal', 0, 1, 0, 1]];
+  if (codes[0][0] === 'equal') {
+    const [tag, i1, i2, j1, j2] = codes[0];
+    codes[0] = [tag, Math.max(i1, i2 - n), i2, Math.max(j1, j2 - n), j2];
+  }
+  if (codes[codes.length - 1][0] === 'equal') {
+    const [tag, i1, i2, j1, j2] = codes[codes.length - 1];
+    codes[codes.length - 1] = [tag, i1, Math.min(i2, i1 + n), j1, Math.min(j2, j1 + n)];
+  }
+  const nn = n + n;
+  const out = [];
+  let group = [];
+  for (const code of codes) {
+    let [, i1, i2, j1, j2] = code;
+    const tag = code[0];
+    if (tag === 'equal' && i2 - i1 > nn) {
+      group.push([tag, i1, Math.min(i2, i1 + n), j1, Math.min(j2, j1 + n)]);
+      out.push(group);
+      group = [];
+      i1 = Math.max(i1, i2 - n);
+      j1 = Math.max(j1, j2 - n);
+    }
+    group.push([tag, i1, i2, j1, j2]);
+  }
+  if (group.length && !(group.length === 1 && group[0][0] === 'equal')) out.push(group);
+  return out;
+}
+
+/** `difflib._format_range_unified`. */
+function formatRangeUnified(start, stop) {
+  let beginning = start + 1;
+  const length = stop - start;
+  if (length === 1) return `${beginning}`;
+  if (!length) beginning -= 1;   // an empty range begins at the line just before it
+  return `${beginning},${length}`;
+}
+
+/**
+ * `difflib.unified_diff` — the lines, WITHOUT trailing newlines when `lineterm` is `""`.
+ *
+ * Every call site in this port passes `lineterm=""` and feeds it `splitlines()` output, which
+ * is the form the Python's own caller uses; the parameter is kept so the shape is the
+ * stdlib's rather than a specialisation that would have to be widened later.
+ */
+export function unifiedDiff(a, b, {
+  fromfile = '', tofile = '', fromfiledate = '', tofiledate = '', n = 3, lineterm = '\n',
+} = {}) {
+  const out = [];
+  let started = false;
+  for (const group of groupedOpcodes(a, b, n)) {
+    if (!started) {
+      started = true;
+      const fromdate = fromfiledate ? `\t${fromfiledate}` : '';
+      const todate = tofiledate ? `\t${tofiledate}` : '';
+      out.push(`--- ${fromfile}${fromdate}${lineterm}`);
+      out.push(`+++ ${tofile}${todate}${lineterm}`);
+    }
+    const first = group[0];
+    const last = group[group.length - 1];
+    out.push(`@@ -${formatRangeUnified(first[1], last[2])} `
+      + `+${formatRangeUnified(first[3], last[4])} @@${lineterm}`);
+    for (const [tag, i1, i2, j1, j2] of group) {
+      if (tag === 'equal') {
+        for (const line of a.slice(i1, i2)) out.push(` ${line}`);
+        continue;
+      }
+      if (tag === 'replace' || tag === 'delete') {
+        for (const line of a.slice(i1, i2)) out.push(`-${line}`);
+      }
+      if (tag === 'replace' || tag === 'insert') {
+        for (const line of b.slice(j1, j2)) out.push(`+${line}`);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * `str.splitlines()`, which is NOT `String.prototype.split('\n')`.
+ *
+ * Python breaks on eight boundaries beyond `\n`. Two of them — `\r\n` and a lone `\r` — are
+ * already gone by the time this is called, because `readText` decodes in universal-newlines
+ * mode exactly as `Path.read_text` does; they are matched anyway so this reproduces
+ * `splitlines` rather than "splitlines after readText". Of the six that survive that
+ * translation, the two a real file plausibly carries are U+2028 and U+2029: paste a paragraph
+ * from a web page into a deployed AGENT.md and the separator comes with it. Python then
+ * reports one more line than a `split('\n')` would, and since `diff` feeds these lists
+ * straight to `unifiedDiff`, every hunk after the paste shifts by one on one side only — a
+ * whole-file disagreement between the two implementations, on a file no fixture can reach,
+ * caused by a character neither diff prints visibly.
+ *
+ * A trailing terminator does NOT produce a final empty element, in either language.
+ *
+ * The escapes are `\u2028`/`\u2029` and not the characters themselves for a reason this file
+ * learned the hard way: a literal U+2028 in a `.mjs` source is a LineTerminator to the JS
+ * grammar, so writing one inside a regex literal ends the line and the file no longer parses.
+ */
+const LINE_BOUNDARY = /\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/g;
+
+export function pySplitLines(text) {
+  const out = [];
+  let last = 0;
+  LINE_BOUNDARY.lastIndex = 0;
+  let m = LINE_BOUNDARY.exec(text);
+  while (m !== null) {
+    out.push(text.slice(last, m.index));
+    last = m.index + m[0].length;
+    m = LINE_BOUNDARY.exec(text);
+  }
+  if (last < text.length) out.push(text.slice(last));
+  return out;
+}

package/js/link.mjs

@@ -0,0 +1,286 @@
+/**
+ * `harness link` / `harness unlink` — run-from-anywhere, and the phase that had to decide
+ * whether they should exist at all under npm.
+ *
+ * ---------------------------------------------------------------------------------------
+ * DO THEY SHIP? YES — AND NOT FOR THE REASON THE HANDOFF PREDICTED.
+ *
+ * The case against was strong and it was measured, not assumed. `npm i -g geneseed` already
+ * puts `geneseed`, `geneseed-hook` and `geneseed-build` on PATH through npm's own bin
+ * linking, so `geneseed link` from an npm install writes a SECOND `geneseed.cmd` — into
+ * `%LOCALAPPDATA%\Geneseed\bin` rather than `%APPDATA%\npm` — and edits the persistent USER
+ * Path to reach it. `npm uninstall -g` removes neither. That is PATH litter with a registry
+ * edit behind it, for a job the package manager already did.
+ *
+ * What decided it against that was the WEB CONSOLE, not the CLI. `web/src/pages/Settings`
+ * has "Run from anywhere" and its inverse as two buttons; both POST `/api/actions/link` and
+ * `/api/actions/unlink`; and the Node job runner can only answer them by spawning
+ * `node bin/geneseed-cli.mjs link`. So the honest options were exactly two:
+ *
+ *   * PORT THE VERBS — the npm package gains a command that duplicates what npm did; or
+ *   * DELETE THE TWO ACTIONS from `action_commands` in BOTH implementations, delete the two
+ *     buttons, and rebuild the tracked `web/dist`.
+ *
+ * The second removes a working feature from every GIT-CHECKOUT user — for whom `link` is
+ * the only thing that puts `geneseed` on PATH, because there is no package manager in that
+ * story — in order to spare npm users a duplicate. It also spends a `web/dist` rebuild on a
+ * deletion. So: they ship, they port, and `NOT_PORTED_ACTIONS` empties.
+ *
+ * The npm duplication is left as it is rather than papered over with a new "you already have
+ * this" refusal: that would be a REDESIGN of the verb, the reference has no such arm, and a
+ * divergence invented by the port is worse than one it inherited.
+ *
+ * ---------------------------------------------------------------------------------------
+ * THE ONE DIVERGENCE, AND IT IS P5b's, NOT A NEW ONE.
+ *
+ * On Windows the verb writes a shim naming an INTERPRETER and an ENTRY. The reference names
+ * `sys.executable` and `rituals/harness.py`; a Node process cannot know which Python would
+ * have run, and inventing one writes a shim that names an interpreter the user may not have.
+ * P5b settled this shape for the hook shim — "Node bakes node" — and P3a settled the gate:
+ * the shim is byte-comparable once runner and entry are ARGUMENTS. So this bakes
+ * `process.execPath` + `bin/geneseed-cli.mjs`, `tests/harness_golden.py` normalises the
+ * shim's argv line the way `js/web/jobs.mjs` normalises the job runner's, and each side's
+ * real content is asserted ABSOLUTELY in `tests/test_win_user_path.py`. A shim written by
+ * the Node CLI reaches sixteen verbs rather than twenty-four; that is the cost of the port
+ * being a port, and it disappears when P7 lands `tui`/`menu`/`home`.
+ *
+ * THE DOUBLE CARRIAGE RETURN IS NOT A TYPO. The reference builds the shim with explicit
+ * `\r\n` and writes it with `Path.write_text`, whose default newline handling then turns
+ * each `\n` into `\r\n` again — the file on disk really is `@echo off\r\r\n`. `writeText`
+ * carries exactly that rule (it is why the helper exists), so passing the same string
+ * through it reproduces the same bytes. cmd.exe does not care; the byte gate does.
+ *
+ * ---------------------------------------------------------------------------------------
+ * NO TEST IN THIS REPO MAY TOUCH THE REAL USER PATH.
+ *
+ * `winUserPath` writes to the registry through PowerShell. That is not sandboxable and a
+ * cell that ran it would edit the developer's machine, so the module is shaped so the gate
+ * never needs to:
+ *
+ *   * `winUserPathScript` is PURE — the escaping, the split and the idempotence live there
+ *     and `tests/test_win_user_path.py` runs it over a corpus (apostrophes, trailing
+ *     separators, UNC roots) against the Python twin, byte for byte.
+ *   * `cmdLink` SHORT-CIRCUITS when the bin dir is already on `PATH`, so a cell that seeds
+ *     `PATH` with its own sandboxed bin dir exercises the whole verb and never spawns.
+ *   * `cmdUnlink` has no such short-circuit, so its cells seed a `PATH` with no `powershell`
+ *     on it: the spawn fails to launch, `winUserPath` returns false through the ENOENT arm,
+ *     and the verb takes its "removed the shim, said nothing about PATH" branch. A real arm,
+ *     reached honestly, with the registry untouched.
+ *
+ * THE SUCCESS ARM OF `winUserPath` IS THEREFORE UNGATED, DELIBERATELY, IN BOTH
+ * IMPLEMENTATIONS — declared here rather than faked, because the only way to gate it is to
+ * edit the machine running the gate.
+ */
+import {
+  chmodSync, existsSync, lstatSync, mkdirSync, readlinkSync, rmSync,
+} from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import os from 'node:os';
+
+import { ROOT } from './checkout.mjs';
+import { readMaybe } from './installs.mjs';
+import { pyPathStr, pyPrint, pyPrintErr, writeText } from './lib/fs.mjs';
+
+const IS_WIN = process.platform === 'win32';
+
+/** `_harness_lifecycle._win_bin_dir`. */
+export function winBinDir() {
+  // `os.environ.get(...) or str(Path.home())` — an EMPTY LOCALAPPDATA falls back too,
+  // which `??` would not do.
+  const base = process.env.LOCALAPPDATA || os.homedir();
+  return path.join(base, 'Geneseed', 'bin');
+}
+
+/**
+ * `_harness_lifecycle._win_user_path_script` — the PowerShell one-liner, built but not run.
+ *
+ * Every quoting hazard in this verb is in this string, which is why it is a separate
+ * function on both sides: `''` is PowerShell's single-quote escape, the `;` split drops
+ * empty segments so a trailing separator cannot append an empty entry, and `-notcontains`
+ * is what makes `link` idempotent.
+ */
+export function winUserPathScript(action, directory) {
+  const d = directory.replaceAll("'", "''");   // PS single-quote escape (O'Brien)
+  if (action === 'add') {
+    return `$d='${d}';`
+      + "$p=[Environment]::GetEnvironmentVariable('Path','User');"
+      + "if (-not $p) {$p=''};"
+      + "$parts=$p.Split(';') | Where-Object {$_ -ne ''};"
+      + 'if ($parts -notcontains $d) {'
+      + "  $np=(@($parts)+$d) -join ';';"
+      + "  [Environment]::SetEnvironmentVariable('Path',$np,'User')}";
+  }
+  return `$d='${d}';`
+    + "$p=[Environment]::GetEnvironmentVariable('Path','User');"
+    + 'if ($p) {'
+    + "  $np=(($p.Split(';') | Where-Object {$_ -ne '' -and $_ -ne $d}) -join ';');"
+    + "  [Environment]::SetEnvironmentVariable('Path',$np,'User')}";
+}
+
+/**
+ * `_harness_lifecycle._win_user_path` — the spawn, and the sixth row of `_ALLOWED_SPAWNS`.
+ *
+ * There is no in-process equivalent: the persistent USER Path lives in the registry
+ * (`HKCU\Environment`), not in this process's environment, and Node has no registry API.
+ * `[Environment]::SetEnvironmentVariable(...,'User')` also broadcasts `WM_SETTINGCHANGE`,
+ * which a hand-rolled `reg add` would not — so even a registry binding would be the wrong
+ * primitive.
+ *
+ * `except OSError -> False`: Python raises when the executable cannot be launched at all.
+ * Node reports the same condition in `r.error` instead of throwing, so the two arms are
+ * spelled differently and mean the same thing — a `powershell` that is not on PATH returns
+ * false rather than crashing the verb.
+ */
+function winUserPath(action, directory) {
+  const r = spawnSync('powershell',
+    ['-NoProfile', '-Command', winUserPathScript(action, directory)],
+    { stdio: 'inherit', windowsHide: true });
+  if (r.error) return false;
+  return r.status === 0;
+}
+
+/** `_harness_lifecycle.cmd_link` — put `geneseed` on PATH so it runs from any directory. */
+export function cmdLink(args) {
+  const here = ROOT;
+  if (IS_WIN) {
+    const bindir = winBinDir();
+    const shim = path.join(bindir, 'geneseed.cmd');
+    try {
+      mkdirSync(bindir, { recursive: true });
+      // The running runtime, not a bare name — the reference's reason (a bare `python` may
+      // be missing or resolve to the Microsoft Store alias stub) applies to `node` too, and
+      // an npm install is exactly where a second Node on PATH is likeliest.
+      writeText(shim, '@echo off\r\n'
+        + `"${process.execPath}" "${path.join(here, 'bin', 'geneseed-cli.mjs')}" %*\r\n`);
+    } catch (e) {
+      pyPrintErr(`geneseed: could not write ${shim} (${pyOsError(e)})\n`);
+      return 1;
+    }
+    pyPrint(`geneseed: wrote shim ${shim}\n`);
+    const on_path = (process.env.PATH || '').toLowerCase().includes(bindir.toLowerCase());
+    if (on_path || winUserPath('add', bindir)) {
+      pyPrint(`geneseed: '${bindir}' is on your user PATH — open a NEW terminal, then run \`geneseed\`.\n`);
+    } else {
+      pyPrint(`geneseed: add '${bindir}' to your PATH manually, then run \`geneseed\` from anywhere.\n`);
+    }
+    return 0;
+  }
+  // Unix: write a shim into a bin dir (default ~/.local/bin, no sudo). See the shim
+  // comment below for why this is no longer a symlink to `ROOT/geneseed`.
+  // `Path(args.dir)` — and `pyPathStr` is that conversion, not decoration. The reference
+  // builds a `Path` here and prints `str(target_dir)` twice (the PATH notice and the `export
+  // PATH=` line) as well as comparing it against `PATH.split(os.pathsep)`, so an argument
+  // that is not already normalised diverges in three places at once. A trailing slash is the
+  // cheapest one: `str(Path('/x/bin/'))` is `/x/bin` and the raw string is not.
+  // `harness_golden`'s `link/an-explicit-dir-argument-is-used-instead-of-the-default` passes
+  // one, and it is the cell that found this.
+  let targetDir = args.dir ? pyPathStr(args.dir) : null;
+  if (targetDir === null) {
+    const local = path.join(os.homedir(), '.local', 'bin');
+    try {
+      mkdirSync(local, { recursive: true });
+      targetDir = local;
+    } catch {
+      targetDir = '/usr/local/bin';
+    }
+  }
+  const dest = path.join(targetDir, 'geneseed');
+  const entry = path.join(here, 'bin', 'geneseed-cli.mjs');
+  try {
+    mkdirSync(targetDir, { recursive: true });
+    // `dest.is_symlink() or dest.exists()` — the first half is what catches a BROKEN
+    // symlink, which `existsSync` follows and reports absent.
+    if (isSymlink(dest) || existsSync(dest)) rmSync(dest, { force: true });
+    // A WRITTEN SHIM, not a symlink to `ROOT/geneseed`. The bash launcher execs a Python
+    // interpreter, so symlinking it puts Python on PATH from the Node verb. The Windows
+    // arm above has always written a shim; this is the same shape. `GENESEED_LINK_SHIM`
+    // is the marker `cmdUnlink` recognises — without it, unlink cannot tell our file from
+    // a stranger's and would have to refuse every regular file, which is a no-op.
+    writeText(dest, '#!/bin/sh\n'
+      + '# GENESEED_LINK_SHIM\n'
+      + `exec "${process.execPath}" "${entry}" "$@"\n`);
+    chmodSync(dest, 0o755);
+  } catch (e) {
+    pyPrintErr(`geneseed: could not write ${dest} (${pyOsError(e)}) — pick a writable dir: `
+      + 'geneseed link <dir>\n');
+    return 1;
+  }
+  pyPrint(`geneseed: linked ${dest} -> ${entry}\n`);
+  if ((process.env.PATH || '').split(path.delimiter).includes(targetDir)) {
+    pyPrint(`geneseed: '${targetDir}' is on PATH — run 'geneseed' from anywhere.\n`);
+  } else {
+    pyPrint(`geneseed: NOTE '${targetDir}' is not on your PATH. Add it, e.g.:\n`);
+    pyPrint(`  echo 'export PATH="${targetDir}:$PATH"' >> ~/.zshrc   # or ~/.bashrc\n`);
+  }
+  return 0;
+}
+
+/** `_harness_lifecycle.cmd_unlink`. */
+export function cmdUnlink() {
+  if (IS_WIN) {
+    const bindir = winBinDir();
+    const shim = path.join(bindir, 'geneseed.cmd');
+    let removed = false;
+    if (existsSync(shim)) {
+      try {
+        rmSync(shim);
+        removed = true;
+        pyPrint(`geneseed: removed ${shim}\n`);
+      } catch (e) {
+        pyPrintErr(`geneseed: could not remove ${shim} (${pyOsError(e)})\n`);
+      }
+    }
+    if (winUserPath('remove', bindir)) {
+      pyPrint(`geneseed: removed '${bindir}' from your user PATH (open a new terminal).\n`);
+    }
+    if (!removed) pyPrint('geneseed: no linked launcher found.\n');
+    return 0;
+  }
+  let removed = false;
+  const candidates = [path.join(os.homedir(), '.local', 'bin'), '/usr/local/bin'];
+  for (const d of (process.env.PATH || '').split(path.delimiter)) if (d) candidates.push(d);
+  const seen = new Set();
+  for (const d of candidates) {
+    if (seen.has(d)) continue;
+    seen.add(d);
+    const f = path.join(d, 'geneseed');
+    // TWO shapes, because two shapes exist on disk. (a) `os.readlink(f)` raw, then `.name`
+    // — NOT a resolved path: the reference asks whether the link's own target BASENAME is
+    // `geneseed`, so a symlink pointing at some other program that happens to sit in a
+    // `geneseed` directory is left alone. That is every install made before the shim.
+    // (b) a regular file we wrote, identified by its marker — never "any regular file
+    // called geneseed", which would delete a stranger's program.
+    const ours = (isSymlink(f) && path.basename(readlinkSync(f)) === 'geneseed')
+      || (!isSymlink(f) && existsSync(f) && (readMaybe(f) ?? '').includes('GENESEED_LINK_SHIM'));
+    if (ours) {
+      try {
+        rmSync(f);
+        pyPrint(`geneseed: removed ${f}\n`);
+        removed = true;
+      } catch { /* `except OSError: pass` */ }
+    }
+  }
+  if (!removed) pyPrint('geneseed: no linked launcher found on PATH\n');
+  return 0;
+}
+
+/** `Path.is_symlink()` — false for a path that does not exist, never a throw. */
+function isSymlink(p) {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `str(OSError)` — what Python interpolates into these two messages.
+ *
+ * `[Errno 13] Permission denied: 'C:\\...'`, and Node's `e.message` is the same three parts
+ * in a different order. Not byte-reproducible and not worth pretending otherwise: both cells
+ * that can reach it assert the arm, not the errno text.
+ */
+function pyOsError(e) {
+  return e && e.message ? e.message : String(e);
+}