geneseed 3.1.1 → 3.1.2

package/js/web/api.mjs

@@ -14,7 +14,7 @@
  * `apiOverview` compute anything of their own, and most of what `apiOverview` computes is
  * counting.
  *
- * THE ONE PARAMETER: `doctorCollect({groups})`. `js/doctor.mjs` carried a `ran(check,
+ * THE ONE PARAMETER: `doctorCollect({groups})`. `js/inspect/doctor.mjs` carried a `ran(check,
  * label, probs)` that returned its third argument and threw the first two away, with a
  * docblock saying the label stays "because it is the one place each check is NAMED, and
  * what P6's accumulator will key on". This is that phase. `on_progress=` — the TUI's — is
@@ -26,15 +26,15 @@
  * `state.inventory` and the badges and taxonomy classes belonged to a phase that had not
  * arrived. `api_catalog` consumes exactly those fields, so this is the phase that would
  * have made the counting half and the reading half two classifiers. It did not:
- * `tuiInventory` in `js/inventory.mjs` is the one walk, `js/status.mjs`'s `inventoryCounts`
+ * `tuiInventory` in `js/inspect/inventory.mjs` is the one walk, `js/inspect/status.mjs`'s `inventoryCounts`
  * is three `length`s off it, and `specEntries` grew out of `specNames` by adding the READ
  * rather than by being written beside it.
  *
  * THE TAXONOMY WAS ALREADY PORTED, which the measurement found and the handoff did not.
- * `js/status.mjs` said flatly that "the ~111 LOC of TUI taxonomy" was P7's; `LAW_CLASS`,
+ * `js/inspect/status.mjs` said flatly that "the ~111 LOC of TUI taxonomy" was P7's; `LAW_CLASS`,
  * `SKILL_CLASS`, `LAW_CLASSES` and `ENTITY_STATUSES` had in fact crossed in P5g inside
- * `js/doctor.mjs`, because doctor's authoring gates are what validate them. P6c moved the
- * four to `js/inventory.mjs` — where Python keeps them — rather than copying them, and
+ * `js/inspect/checks-authoring.mjs`, because doctor's authoring gates are what validate them. P6c moved the
+ * four to `js/inspect/inventory.mjs` — where Python keeps them — rather than copying them, and
  * doctor imports them back. Only `parse_laws`, `load_registry` and `entity_status` were
  * genuinely new.
  *
@@ -46,7 +46,7 @@
  * carries the key, which is why its replay harness erases it before comparing.
  *
  * P6c's ROUTES ARE THE FIRST THAT PARSE A PATH, which brings three things no earlier
- * endpoint could reach: `pyUnquote` (NOT `decodeURIComponent`, which throws where the
+ * endpoint could reach: `percentDecode` (NOT `decodeURIComponent`, which throws where the
  * reference leaves a stray `%` alone), the `NotFound` → 404 convention, and `flatName`'s
  * traversal refusal — a GET carries no token, so before that check the item route was an
  * arbitrary-file read.
@@ -55,27 +55,28 @@ import { createHash } from 'node:crypto';
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 
-import { ROOT, THEMES, discoverNames } from '../checkout.mjs';
-import { diffCollect } from '../diff.mjs';
-import { doctorCollect } from '../doctor.mjs';
-import { excludesSnapshot } from '../excludes.mjs';
-import { GLOBAL_MANIFEST, HOSTS, opencodeConfigDir, pyResolve } from '../hosts.mjs';
+import { CONFIG, ROOT, THEMES, discoverNames } from '../build/source.mjs';
+import { sourceReleaseVersion } from '../hosts/opencode.mjs';
+import { diffCollect } from '../inspect/diff.mjs';
+import { doctorCollect } from '../inspect/doctor.mjs';
+import { excludesSnapshot } from '../inspect/excludes.mjs';
+import { GLOBAL_MANIFEST, HOSTS, opencodeConfigDir, resolvePath } from '../hosts/hosts.mjs';
 import {
   doctrinesForBuild, excludedRulesOfDir, footprintOfDir, installState, installTargets,
   installedDefaults, modeOfDir,
   postureOfDir, readJsonMaybe, readMaybe, themeOfDir,
-} from '../installs.mjs';
-import { frontmatter } from '../hooks.mjs';
+} from '../hosts/installs.mjs';
+import { frontmatter } from '../hosts/hooks.mjs';
 import {
   SKILL_CLASS, entityStatus, loadRegistry, tuiInventory,
-} from '../inventory.mjs';
-import { firstBlockquote } from '../native.mjs';
-import { EMIT_OPTIONS, themeOptions } from '../setup.mjs';
-import { accentFor, statusData } from '../status.mjs';
-import {
-  comparePaths, normcase, pyStripSpace, pyUnquote, readText, withDiscardableStderr, within,
-} from '../lib/fs.mjs';
-import { readJsonc } from '../settings.mjs';
+} from '../inspect/inventory.mjs';
+import { firstBlockquote } from '../hosts/native.mjs';
+import { EMIT_OPTIONS, themeOptions } from '../maintain/setup.mjs';
+import { accentFor, statusData } from '../inspect/status.mjs';
+import { readText, withDiscardableStderr } from '../lib/fs.mjs';
+import { comparePaths, normcase, within } from '../lib/paths.mjs';
+import { stripWhitespace, percentDecode } from '../lib/text.mjs';
+import { readJsonc } from '../hosts/settings.mjs';
 import { apiActivity, apiActivityDetail } from './activity.mjs';
 import { apiMcp, apiRules } from './actions.mjs';
 import { apiGraph } from './graph.mjs';
@@ -87,7 +88,7 @@ const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return
 const isFile = (p) => { try { return statSync(p).isFile(); } catch { return false; } };
 
 /** Two resolved paths, compared as `PurePath.__eq__` does — case-folded on Windows. */
-const samePath = (a, b) => normcase(pyResolve(a)) === normcase(pyResolve(b));
+const samePath = (a, b) => normcase(resolvePath(a)) === normcase(resolvePath(b));
 
 /** `dict.get(key, default)` — `??` would also swallow an explicit null the file declared. */
 const dget = (obj, key, dflt) => (Object.hasOwn(obj, key) ? obj[key] : dflt);
@@ -177,7 +178,7 @@ export function webState(theme = null, target = null) {
       try {
         const em = path.join(d, '.geneseed-emit');
         if (isFile(em)) {
-          const v = pyStripSpace(readText(em));
+          const v = stripWhitespace(readText(em));
           if (v) return v;
         }
       } catch { /* as the Python's `except OSError: pass` */ }
@@ -264,7 +265,7 @@ export function specEntries(root, nested) {
     if (!isFile(p)) continue;
     const [fm, body] = frontmatter(readMaybe(p) ?? '');
     const name = nested ? path.basename(path.dirname(p)) : path.basename(p, '.md');
-    out.push({ name, desc: specDesc(fm, body), body, source: pyResolve(p) });
+    out.push({ name, desc: specDesc(fm, body), body, source: resolvePath(p) });
   }
   out.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
   return out;
@@ -353,7 +354,7 @@ export function memoryItems(state) {
       name: stem,
       title: fm.has('name') ? fm.get('name') : stem,
       desc: fm.has('description') ? fm.get('description') : '',
-      source: pyResolve(p),
+      source: resolvePath(p),
     };
   });
 }
@@ -363,7 +364,7 @@ export function notebookItems(state) {
   const d = notebookDir(state);
   if (!isDir(d)) return [];
   return globMd(d).map((n) => ({
-    name: stemOf(n), title: stemOf(n), desc: '', source: pyResolve(path.join(d, n)),
+    name: stemOf(n), title: stemOf(n), desc: '', source: resolvePath(path.join(d, n)),
   }));
 }
 
@@ -381,7 +382,7 @@ export function configItems(state) {
     if (!isFile(p)) continue;
     const [title, desc] = CONFIG_META[fname] ?? [fname, ''];
     out.push({ name: fname, title, desc, type: 'config', kind: 'manifest',
-      source: pyResolve(p) });
+      source: resolvePath(p) });
   }
   return out;
 }
@@ -389,13 +390,14 @@ export function configItems(state) {
 export const WIKI_FILE_CAP = 5000;
 
 /**
- * `pyResolve` for a path that came out of a HAND-MAINTAINED manifest — `null`, never a throw.
+ * `resolvePath` for a path that came out of a HAND-MAINTAINED manifest — `null`, never a throw.
  *
- * The three wiki sites below are the only request-path callers of `expanduser`, and it now
- * REFUSES a `~user` form by printing and throwing (`js/hosts.mjs`'s docblock). None of them
- * may let that escape: `js/web/server.mjs` wraps the whole GET in a blanket `catch` → a JSON
+ * The three wiki sites below, and `apiDeployCmd` in `js/web/actions.mjs`, are the
+ * request-path callers of `expanduser`, and it REFUSES a `~user` form by printing and throwing
+ * (`js/hosts/hosts.mjs`'s docblock). None of them may let that escape: `js/web/handler.mjs`
+ * wraps the whole GET in a blanket `catch` → a JSON
  * 500, so an unguarded refusal would turn ONE bad line in a file the user hand-edits into a
- * dead Knowledge section. That is the same argument `sovereignBypass` makes in `js/hooks.mjs`
+ * dead Knowledge section. That is the same argument `sovereignBypass` makes in `js/hosts/hooks.mjs`
  * — contain the refusal per entry and take the site's OWN degrade — and each of the three
  * already has one: `[]`, `continue`, `continue`-into-404. The reference reaches those same
  * three degrades for a `~user` path, from the other direction: `ntpath.expanduser` expands
@@ -413,7 +415,7 @@ export const WIKI_FILE_CAP = 5000;
  */
 function wikiPath(p) {
   try {
-    return withDiscardableStderr(() => pyResolve(p));
+    return withDiscardableStderr(() => resolvePath(p));
   } catch {
     return null;
   }
@@ -423,7 +425,7 @@ function wikiPath(p) {
  * `_web_catalog._wiki_manifest` — `$GENESEED_WIKI` first, else `wiki.jsonc` beside the
  * deployed bundle, read with the harness's generic JSONC loader.
  *
- * `pyResolve` where the reference only `expanduser()`s. NOT OBSERVABLE, so it stays: `p` is
+ * `resolvePath` where the reference only `expanduser()`s. NOT OBSERVABLE, so it stays: `p` is
  * consumed by `isFile` and `mcpLoad` and never reaches a response body, and both of those
  * follow symlinks and resolve a relative path against the same cwd anyway.
  */
@@ -476,7 +478,7 @@ export function wikiItems(state) {
     if (!w || typeof w !== 'object' || Array.isArray(w)) continue;
     const wname = String(dget(w, 'name', null) || 'wiki');
     // PER ENTRY, and the loop continues — one unusable `path` in the manifest must not blank
-    // every OTHER vault in it. `pyResolve` where the reference only `expanduser()`s is again
+    // every OTHER vault in it. `resolvePath` where the reference only `expanduser()`s is again
     // unobservable: `root` is only ever joined against or used as the base of a `relative()`
     // whose other operand was built FROM it, and `source` is `.resolve()`d on both sides.
     const root = wikiPath(String(dget(w, 'path', null) || ''));
@@ -504,7 +506,7 @@ export function wikiItems(state) {
         seen.add(key);
         items.push({ name: key, title: path.basename(md, '.md'),
           desc: mds.length === 1 ? desc : r, type: 'wiki', kind: 'page', group: wname,
-          source: pyResolve(md) });
+          source: resolvePath(md) });
       }
     }
   }
@@ -525,7 +527,7 @@ export function apiWikiItem(state, name) {
     // where the reference lands when the expanded root turns out not to exist.
     const root = wikiPath(String(dget(w, 'path', null) || ''));
     if (!root) continue;
-    const p = pyResolve(path.join(root, rel));
+    const p = resolvePath(path.join(root, rel));
     if (rel && path.extname(p) === '.md' && within(p, root) && isFile(p)) {
       const body = readMaybe(p) ?? '';
       return { type: 'wiki', name, title: path.basename(p, '.md'), desc: '',
@@ -536,10 +538,13 @@ export function apiWikiItem(state, name) {
 }
 
 /**
- * `harness._within` — re-exported from `js/lib/fs.mjs`, where P6i moved it.
+ * `harness._within` — re-exported from `js/lib/paths.mjs`, where the lib split put it.
+ *
+ * ⚠ A SECOND, INDEPENDENT COPY lives in `js/inspect/scan.mjs`, written for the doctor's tree
+ * walks. A change to the containment rule has to land on both, and nothing compares them.
  *
  * It lived here from P6b (the restore's containment check) until `_install_move_list` needed
- * the same predicate from `js/uninstall.mjs`, which must not import the web tree. The
+ * the same predicate from `js/maintain/uninstall.mjs`, which must not import the web tree. The
  * re-export keeps `js/web/actions.mjs`'s import path unchanged.
  */
 export { within };
@@ -577,9 +582,9 @@ export function resolveLinks(state, body) {
   const links = [];
   const seen = new Set();
   for (const m of body.matchAll(WIKILINK_RE)) {
-    // `pyStripSpace`, not `trim()` — P6d measured the two whitespace classes apart and P6e
+    // `stripWhitespace`, not `trim()` — P6d measured the two whitespace classes apart and P6e
     // gave this regex a second reader, so the two call sites answer with one rule.
-    const label = pyStripSpace(m[1]);
+    const label = stripWhitespace(m[1]);
     if (known.has(label) && !seen.has(label)) {
       seen.add(label);
       links.push({ label, type: known.get(label), name: label });
@@ -715,7 +720,7 @@ export function apiItem(state, type, name) {
     if (!isFile(p)) throw new NotFound(name);
     const body = readMaybe(p) ?? '';
     return { type, name, title: name, desc: '', body,
-      links: resolveLinks(state, body), source: pyResolve(p) };
+      links: resolveLinks(state, body), source: resolvePath(p) };
   }
   if (type === 'wiki') return apiWikiItem(state, name);
   if (type === 'config') {
@@ -725,7 +730,7 @@ export function apiItem(state, type, name) {
     const raw = readMaybe(p) ?? '';
     const [title, desc] = CONFIG_META[name] ?? [name, ''];
     return { type, name, title, desc, manifest: configManifest(name, p),
-      body: `\`\`\`json\n${raw}\n\`\`\``, links: [], source: pyResolve(p) };
+      body: `\`\`\`json\n${raw}\n\`\`\``, links: [], source: resolvePath(p) };
   }
   throw new NotFound(type);
 }
@@ -898,22 +903,39 @@ export function apiOverview(state) {
     doctor: state.doctor,
     diff,
     build_time: buildTime,
+    // The RELEASE LABEL OF THE SOURCE THIS CONSOLE IS SERVED FROM, not of the deployed install —
+    // the two differ whenever something has changed since the last emit, which is exactly when
+    // knowing which one you are looking at matters. `.geneseed-version` carries the install's own
+    // label and the fingerprint comparison already reports the drift; this answers the plainer
+    // question the topbar asks, "what is running".
+    //
+    // Degrades to null rather than to a wrong number: `sourceReleaseVersion` answers '0.0.0' for
+    // an unreadable config, and a console confidently displaying 0.0.0 is worse than one that
+    // shows nothing.
+    version: releaseLabel(),
   };
 }
 
+/** The source's release label, or null when it cannot be read. */
+function releaseLabel() {
+  const v = sourceReleaseVersion({ config: CONFIG });
+  return v && v !== '0.0.0' ? v : null;
+}
+
 /**
  * `_web_server.Handler.STATE_ROUTES`, the ported half.
  *
  * A literal path to `api_X(state)`, exactly as the reference's table is — and the reason
- * it is a table on this side too is `tests/test_web_server.py`'s cross-check, which reads
- * the reference's table out of `rituals/_web_server.py` with `ast` and requires this one
- * plus `NOT_PORTED` to equal it. On the second instance of anything, the gate becomes a
- * table cross-checked against the source of truth.
+ * it is a table on this side too is `tests/unit/web_server.test.mjs`'s cross-check, which
+ * requires this table plus `PREFIX_ROUTES`, `PORTED_INLINE` and `NOT_PORTED` to equal
+ * `REF_GET` — a FROZEN LITERAL of what the reference daemon answered, since the source it
+ * was once read from with `ast` is deleted. On the second instance of anything, the gate
+ * becomes a table cross-checked against a declaration.
  */
 /**
  * `_web_server.do_GET`'s prefix routes, the ported ones — path in, response out.
  *
- * `pyUnquote` and not `decodeURIComponent`: the JS builtin throws a `URIError` on a `%`
+ * `percentDecode` and not `decodeURIComponent`: the JS builtin throws a `URIError` on a `%`
  * that is not an escape, which the shell would answer as a 500 where the reference answers
  * a 404 naming the literal text.
  */
@@ -925,13 +947,13 @@ export const PREFIX_ROUTES = [
   ['/api/item/', (state, p) => {
     const parts = splitN(p, '/', 4);
     if (parts.length < 5 || !parts[4]) throw new NotFound(p);
-    return apiItem(state, parts[3], pyUnquote(parts[4]));
+    return apiItem(state, parts[3], percentDecode(parts[4]));
   }],
   // P6e. The reference's own `path[len("/api/activity/"):]`, unquoted — the sid keeps
   // whatever it carries and `api_activity_detail`'s safe-name scheme is what makes the
   // lookup safe, rather than a check out here.
   ['/api/activity/', (state, p) => apiActivityDetail(
-    state, pyUnquote(p.slice('/api/activity/'.length)))],
+    state, percentDecode(p.slice('/api/activity/'.length)))],
 ];
 
 /** `str.split(sep, maxsplit)` — at most `n` splits, the remainder kept whole. */

package/js/web/daemon.mjs

@@ -0,0 +1,319 @@
+/**
+ * The daemon — its on-disk record, and the lifecycle that starts, probes, stops and restarts it.
+ *
+ * `geneseed web` can run in the foreground or detached. Detached is the interesting half: the
+ * record at `.geneseed-web.json` is how a later `web stop` or `web status` finds a server nobody
+ * kept a handle to, and `probe` is the liveness question every one of those verbs asks first.
+ *
+ * TWO OF THIS PACKAGE'S THREE SPAWNS ARE HERE — the detached daemon and the desktop URL opener —
+ * and both are declared by name in `tests/unit/hook_cli.test.mjs`'s spawn allow-list. A new spawn
+ * in this file is a deliberate act that reddens that gate until it is declared.
+ */
+import { printOut, writeText } from '../lib/fs.mjs';
+import { isTruthy, jsonDumpsCompact } from '../lib/json.mjs';
+import { webState } from './api.mjs';
+import { spawn } from 'node:child_process';
+import { chmodSync, mkdirSync, openSync, readFileSync, unlinkSync } from 'node:fs';
+import { request as httpRequest } from 'node:http';
+import { join, resolve as pathResolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = pathResolve(fileURLToPath(import.meta.url), '..', '..', '..');
+
+// ---- the daemon record -----------------------------------------------------
+
+const statePath = (target) => join(target, '.geneseed-web.json');
+
+export function readDaemon(target) {
+  try {
+    return JSON.parse(readFileSync(statePath(target), 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeDaemon(target, data) {
+  try {
+    mkdirSync(target, { recursive: true });
+    const p = statePath(target);
+    writeText(p, jsonDumpsCompact(data, { bareInts: true }));
+    // Owner-only: the record carries the API token. A no-op on Windows, where the
+    // mode only maps to the read-only attribute — same as the reference's os.chmod.
+    chmodSync(p, 0o600);
+  } catch { /* the reference swallows OSError here too */ }
+}
+
+export function clearDaemon(target) {
+  try {
+    unlinkSync(statePath(target));
+  } catch { /* already gone */ }
+}
+
+// ---- daemon mode -----------------------------------------------------------
+//
+// `geneseed web start|stop|status|restart`. The reference's own banner explains the design
+// — the running server records pid/port/token/url in a small JSON file and control is over
+// HTTP, so nothing here needs OS process-kill semantics, only a localhost request with the
+// token. Two things about the TWIN, neither of which is in that banner:
+//
+//   * `_probe` and `_post_shutdown` are `urllib.request.urlopen` with a timeout, which is
+//     synchronous. Node has no synchronous HTTP client, so every function below that
+//     reaches one is `async` and `cmdWeb` awaits it — which is why `bin/geneseed-cli.mjs`
+//     awaits its dispatch. Nothing about the ORDER of the reference's steps changes.
+//   * `agent: false` on both requests. Node's global agent has kept sockets alive by
+//     default since v19, and a pooled idle socket keeps the event loop referenced — a
+//     `web status` that answered correctly would then hang for the keep-alive timeout
+//     instead of exiting. Python's `urlopen` opens and closes a connection per call.
+
+/** `f"{url}/api/ping"` answered 200 — the cheap liveness probe both `status` and the
+ *  launcher's wait loop are built on. Every failure mode is False, as the reference's
+ *  `(URLError, OSError, ValueError)` catch is. */
+export function probe(url, timeout = 1.5) {
+  return new Promise((done) => {
+    let settled = false;
+    const finish = (v) => { if (!settled) { settled = true; done(v); } };
+    let req;
+    try {
+      req = httpRequest(`${url}/api/ping`, { method: 'GET', agent: false }, (res) => {
+        res.resume();          // drain, or the socket never closes
+        finish(res.statusCode === 200);
+      });
+    } catch {
+      return finish(false);    // a malformed url is `ValueError` there and a throw here
+    }
+    req.setTimeout(Math.round(timeout * 1000), () => { req.destroy(); finish(false); });
+    req.on('error', () => finish(false));
+    req.end();
+    return undefined;
+  });
+}
+
+/** The token-carrying POST `geneseed web stop` and the in-page Stop button both send. */
+export function postShutdown(url, token, timeout = 3.0) {
+  return new Promise((done) => {
+    let settled = false;
+    const finish = (v) => { if (!settled) { settled = true; done(v); } };
+    let req;
+    try {
+      req = httpRequest(`${url}/api/shutdown`, {
+        method: 'POST',
+        agent: false,
+        headers: { 'X-Geneseed-Token': token, 'Content-Type': 'application/json' },
+      }, (res) => {
+        res.resume();
+        finish(res.statusCode === 200);
+      });
+    } catch {
+      return finish(false);
+    }
+    req.setTimeout(Math.round(timeout * 1000), () => { req.destroy(); finish(false); });
+    req.on('error', () => finish(false));
+    req.end('{}');
+    return undefined;
+  });
+}
+
+/**
+ * The record ONLY if a server is answering; otherwise the stale file is deleted.
+ *
+ * The deletion is the part a port drops, and it is what stops a machine that crashed with
+ * a daemon running from re-probing a dead URL on every `status` forever. Both of its arms
+ * are gated by a `harness_golden` cell — a record whose url nothing answers, and a record
+ * carrying no url at all, which skips the probe and still clears.
+ */
+export async function liveDaemon(target) {
+  const st = readDaemon(target);
+  if (st && isTruthy(st.url) && await probe(st.url)) return st;
+  if (isTruthy(st)) clearDaemon(target);
+  return null;
+}
+
+const sleep = (ms) => new Promise((r) => { setTimeout(r, ms); });
+
+/** `st.get(k)` rendered as Python renders it — a missing key prints `None`, not
+ *  `undefined`. Only reachable through a hand-edited record, and one character of
+ *  divergence in a message is still a divergence. */
+export const none = (v) => (v === undefined || v === null ? 'None' : String(v));
+
+/**
+ * `_spawn_detached` — the daemon launcher, and the second `_ALLOWED_SPAWNS` entry this
+ * module owns.
+ *
+ * WHY THERE IS NO IN-PROCESS EQUIVALENT: the whole contract is that the server OUTLIVES
+ * the process that started it. `geneseed web start` prints a URL and returns to the shell;
+ * the server it started must still be there. A thread, a `worker_thread` or an in-process
+ * `serve()` all die with the launcher.
+ *
+ * WHAT IT STARTS IS THIS PROGRAM, named as `process.execPath` + `bin/geneseed-cli.mjs` —
+ * the running interpreter by absolute path and this repo's own CLI. The reference names
+ * `sys.executable` + `rituals/harness.py`; each side re-executes ITSELF, which is what
+ * makes this not the passthrough the port exists to remove, and
+ * `tests/test_web_daemon.py` asserts the twin's argv contains no `python`, no `harness.py`
+ * and no `build.py` at all.
+ */
+function spawnDetached(webArgs, log) {
+  const cmd = [process.execPath, join(ROOT, 'bin', 'geneseed-cli.mjs'), 'web', ...webArgs];
+  let out = 'ignore';
+  try {
+    out = openSync(log, 'a');       // `open(log, "ab")`; DEVNULL on OSError, as there
+  } catch { /* the reference falls back to DEVNULL on exactly this failure */ }
+  const child = spawn(cmd[0], cmd.slice(1), {
+    // `DETACHED_PROCESS | NEW_PROCESS_GROUP` on Windows and `start_new_session` on POSIX
+    // are both `detached` here; `unref()` is what lets the launcher's event loop end while
+    // the child runs on, which is `Popen`'s default and Node's is not.
+    detached: true, windowsHide: true, stdio: ['ignore', out, out],
+  });
+  child.unref();
+}
+
+/** The `web` argv the launcher passes. Pure, and compared against `_daemon_args` by the
+ *  corpus: the binary differs per side by design, the FLAGS may not. */
+export function daemonArgs(port, theme) {
+  const args = ['--daemon-internal', '--port', String(port), '--no-browser'];
+  if (isTruthy(theme)) args.push('--theme', theme);
+  return args;
+}
+
+/** The same for the out-of-band restart — `_restart_args`. */
+export function restartArgs(theme) {
+  const args = ['restart', '--no-browser'];
+  if (isTruthy(theme)) args.push('--theme', theme);
+  return args;
+}
+
+/** `request_restart` — a detached `web restart`, so the new server survives the exit of
+ *  the very process asking for it. Called by POST `/api/restart`. */
+export function requestRestart(theme) {
+  const target = webState(theme).target;
+  spawnDetached(restartArgs(theme), join(target, '.geneseed-web.log'));
+}
+
+/**
+ * `webbrowser.open(url)`, which has no Node equivalent at all — there is no stdlib module
+ * that knows what a desktop's default browser is.
+ *
+ * IT IS A MACHINE PRIMITIVE, the same class as `taskkill` and `java -version` and the
+ * opposite of a passthrough: it asks the OS to open a URL and hands it nothing of this
+ * program's work. Declining it instead would have been a silent regression in the one verb
+ * whose job is to put a UI on screen — `geneseed web` would print an address and do
+ * nothing, and no cell would say so because every cell passes `--no-browser`.
+ *
+ * The reference swallows every failure here (`contextlib.suppress(Exception)` in two call
+ * sites and a bare `except` in the third), and so does this.
+ */
+export function openUrl(url) {
+  const [file, args, extra] = process.platform === 'win32'
+    // `start` is a cmd BUILTIN, not a program. The empty `""` is its title argument —
+    // without it `start "http://…"` treats the quoted URL as the window title and opens
+    // nothing. Verbatim args because Node would otherwise re-quote the whole string.
+    ? [process.env.COMSPEC || 'cmd.exe', ['/d', '/s', '/c', `start "" "${url}"`],
+      { windowsVerbatimArguments: true }]
+    : (process.platform === 'darwin' ? ['open', [url], {}] : ['xdg-open', [url], {}]);
+  try {
+    const child = spawn(file, args, {
+      detached: true, stdio: 'ignore', windowsHide: true, ...extra,
+    });
+    // ⚠ ENOENT ARRIVES AS AN EVENT, NOT AS A THROW, AND THE `try` ABOVE CANNOT SEE IT.
+    // This is where the reference's suppression failed to survive translation: Python's
+    // `subprocess` raises `FileNotFoundError` synchronously, so `contextlib.suppress(Exception)`
+    // really did swallow a missing opener. Node's `spawn` reports the same condition on the
+    // child's `error` event, and an 'error' with no listener is re-thrown as an uncaught
+    // exception. So the port's `try/catch` read as equivalent and suppressed nothing.
+    //
+    // MEASURED, in the packaged no-python container: `geneseed web` on a headless Linux box
+    // printed `Error: spawn xdg-open ENOENT`. Found by the acceptance gate rather than by the
+    // 690-cell corpus, and the docblock above says why the corpus never could — every cell
+    // passes `--no-browser`, so no recorded cell has ever executed this line.
+    child.on('error', () => { /* no opener on this machine; the daemon is still serving */ });
+    child.unref();
+  } catch { /* the reference suppresses every exception from this call too */ }
+}
+
+export async function startDaemon(theme, port, openBrowser = true) {
+  const { target } = webState(theme);
+  const st = await liveDaemon(target);
+  if (st) {
+    printOut(`[web] already running on ${st.url}  (pid ${none(st.pid)})\n`);
+    if (openBrowser) openUrl(st.url);
+    return 0;
+  }
+  clearDaemon(target);
+  const log = join(target, '.geneseed-web.log');
+  spawnDetached(daemonArgs(port, theme), log);
+  // `for _ in range(60): ... time.sleep(0.2)` — twelve seconds for the child to bind and
+  // write its record. The probe timeout is the reference's shorter 0.5 here, not 1.5.
+  for (let i = 0; i < 60; i += 1) {
+    const rec = readDaemon(target);
+     
+    if (rec && isTruthy(rec.url) && await probe(rec.url, 0.5)) {
+      printOut(`[web] Geneseed UI on ${rec.url}  (theme: ${none(rec.theme)}, `
+        + `pid ${none(rec.pid)})\n`);
+      printOut('[web] running in the background — `geneseed web stop` to stop it.\n');
+      if (openBrowser) openUrl(rec.url);
+      return 0;
+    }
+     
+    await sleep(200);
+  }
+  printOut('[web] daemon did not come up in time — check the log:\n');
+  printOut(`      ${log}\n`);
+  return 1;
+}
+
+export async function stopDaemon(theme = null) {
+  const { target } = webState(theme);
+  const st = readDaemon(target);
+  if (!isTruthy(st) || !isTruthy(st.url)) {
+    // NO `clearDaemon` HERE, and the asymmetry with `liveDaemon` is the reference's. A
+    // record that names no url is left exactly where it is; `web status` on the same file
+    // deletes it. Both directions are cells, because a port that unified them would delete
+    // a file the reference keeps and stdout would look identical.
+    printOut('[web] no running server recorded.\n');
+    return 0;
+  }
+  if (await postShutdown(st.url, isTruthy(st.token) ? st.token : '')) {
+    clearDaemon(target);
+    printOut(`[web] stopped (pid ${none(st.pid)}).\n`);
+    return 0;
+  }
+  clearDaemon(target);
+  printOut('[web] no live server (cleared a stale record).\n');
+  return 0;
+}
+
+export async function statusDaemon(theme = null) {
+  const { target } = webState(theme);
+  const st = await liveDaemon(target);
+  if (st) {
+    printOut(`[web] running on ${st.url}  (theme: ${none(st.theme)}, pid ${none(st.pid)})\n`);
+    return 0;
+  }
+  // EXIT 1, which is the verb's whole contract for a script. The snapshot's `<exit>`
+  // column is what gates it.
+  printOut('[web] not running.\n');
+  return 1;
+}
+
+export async function restartDaemon(theme = null, port = 4747, openBrowser = true,
+  onlyIfRunning = false) {
+  const { target } = webState(theme);
+  const st = readDaemon(target);
+  const live = (await liveDaemon(target)) !== null;
+  if (onlyIfRunning && !live) return 0;
+  const usePort = (st && isTruthy(st.port) ? st.port : null) || port;
+  let open = openBrowser;
+  if (live) {
+    // A live daemon means a tab is already open on this (preserved) port and will
+    // reconnect on its own — the reference's `ponytail:` note, kept.
+    open = false;
+    await stopDaemon(theme);
+    for (let i = 0; i < 50; i += 1) {
+       
+      if (!await probe(`http://127.0.0.1:${usePort}`, 0.2)) break;
+       
+      await sleep(100);
+    }
+  }
+  return startDaemon(theme, usePort, open);
+}
+