geneseed 3.1.3 → 3.2.0

package/js/web/routes.mjs

@@ -3,8 +3,8 @@
  *
  * Eight exported sets and one map. They are not documentation: `tests/unit/web_server.mjs` reads
  * them as a TWO-SIDED PARTITION and probes the real handler against them, because a declaration is
- * not a dispatcher — mutation M23 exists precisely because a route can be declared in one and
- * missing from the other, and nothing but a probe notices.
+ * not a dispatcher — a route can be declared in one and missing from the other, and nothing but
+ * a probe notices.
  *
  * Split out of `server.mjs` because it is the half a reader consults to answer "does the console
  * expose X?", which has nothing to do with sockets, daemons or gzip.
@@ -14,103 +14,64 @@ import { apiExcludesMutate, apiInstallToggle, apiMcpToggle, apiMemoryDelete, api
 import { apiActivityToggle } from './activity.mjs';
 
 /**
- * The API paths this phase does not answer yet.
- *
- * Without it every one of them would fall through to `serveStatic`, which answers ANY
- * unknown path with index.html and a 200 — the SPA fallback. An unported endpoint would
- * therefore return a plausible HTML page instead of failing, and the first cell written
- * against it in P6b would be the thing that discovered the route was missing. A 501
- * naming the phase costs one lookup and cannot be mistaken for a working endpoint.
- *
- * It shrank to empty in P6g and the DECLARATION STAYS. Every GET the reference answers is now
- * answered here, so the two sets hold nothing — but they are half of a partition
- * (`test_every_get_route_is_either_ported_or_declared_unported`), and deleting them would let
- * the next GET route added to the reference fall through to the SPA with nothing to say so.
- * An empty declaration is the partition asserting that there is nothing left to declare.
- */
-/**
- * SPLIT BY VERB SINCE P6b, and the split is the point rather than a tidy-up. Five paths
- * answer BOTH verbs with different bodies — `/api/mcp`, `/api/excludes`, `/api/rules`,
- * `/api/profile`, `/api/activity` — and P6b ports the GET half of two of them. One set
- * keyed on path alone would have taken `/api/excludes` out of the unported list the
- * moment its GET landed, and its POST would then have answered `{"error": "not found"}`
- * with a 404: a plausible-looking response where the reference returns 200 or 409, which
- * is exactly the failure the 501 exists to prevent.
+ * The API paths this daemon does not answer — currently empty, but the DECLARATION STAYS:
+ * without it, an unmatched GET falls through to `serveStatic`'s SPA fallback (200 +
+ * index.html) instead of a clear failure. Half of a partition test, so an empty set still
+ * asserts there is nothing left to declare.
+ *
+ * Declared separately from the POST sets below because five paths — `/api/mcp`,
+ * `/api/excludes`, `/api/rules`, `/api/profile`, `/api/activity` — answer both verbs with
+ * different bodies, so one set keyed on path alone could not track GET and POST status
+ * independently.
  */
-/** EMPTY SINCE P6g — every GET the reference answers is answered here. */
 export const NOT_PORTED = new Set([]);
 export const NOT_PORTED_PREFIXES = [];
 
 /**
- * The POSTs that have not crossed YET — and EMPTY SINCE P6i, which took `/api/install`.
- *
- * IT STAYS DECLARED, for the same reason the GET pair above stays and the prefix lists have
- * stayed since P6g: this set is half of a partition
- * (`test_every_post_route_is_either_ported_or_declared_unported`), so an empty set is the
- * partition ASSERTING that there is nothing left to declare. Delete it and the next POST route
- * added to the reference falls through to `{"error": "not found"}` at 404 — a plausible-looking
- * answer where the reference returns 200 or 409 — with nothing to say so.
- *
- * THE DISPATCHER PROBE NEEDS A TARGET, which an empty set no longer supplies.
- * `tests/test_web_server.py` retired its `unportedGet` probe when `NOT_PORTED` emptied in P6g;
- * `unportedPost` is retired here for the same reason, and `declinedPost` (`/api/pick-folder`,
- * which never crosses) is what keeps the 501 arm of the dispatcher under a live probe.
+ * The POSTs that have not crossed yet — currently empty, for the same reason the GET pair
+ * above stays declared: deleting it would let an unrouted POST fall through to a
+ * plausible-looking 404 instead of the 501 this set exists to produce.
  */
 export const NOT_PORTED_POST = new Set([]);
 export const NOT_PORTED_POST_PREFIXES = [];
 
 /**
- * The POSTs that will NEVER cross, which is a different claim from the set above.
- *
- * `/api/pick-folder` opens an OS-NATIVE folder chooser on the daemon host — `osascript` on
- * macOS, a one-shot `tkinter` subprocess elsewhere. There is no Node twin that is not a new
- * GUI dependency, and reaching for one would also be a sixth `_ALLOWED_SPAWNS` row for a
- * modal dialog. The UI already falls back to its editable path field when this endpoint
- * fails, which is what a 501 gives it.
- *
- * SEPARATE FROM `NOT_PORTED_POST` ON PURPOSE. That set is a to-do list every later phase
- * shrinks, and folding a permanent decline into it would make the list wrong in the one
- * direction nobody checks: a phase that emptied it would have to either port a GUI dialog
- * or quietly delete a declaration. Both sets are unioned into the partition the reference's
- * routes are cross-checked against, so neither can drift.
+ * The POSTs that will NEVER cross, which is a different claim from the set above — currently
+ * EMPTY. `/api/pick-folder` was its one member (an OS-native folder chooser, "declined rather
+ * than deferred" because there was no Node twin that was not a new GUI dependency) until the
+ * user overrode that decision 2026-08-27; it now dispatches inline from `js/web/handler.mjs`'s
+ * `doPost` — see `apiPickFolder` in `js/web/actions.mjs`.
+ *
+ * KEPT DECLARED AND EMPTY FOR THE SAME REASON `NOT_PORTED_POST` STAYS DECLARED WHEN IT EMPTIES
+ * (see that set, just above): an empty set here is the partition asserting there is nothing
+ * PERMANENTLY refused, not an omission a later reader has to double-check. `notPortedPost`
+ * below still consults it, so a genuinely permanent decline — if one is ever added again —
+ * needs no dispatcher change, only a member here.
  */
-export const DECLINED_POST = new Set([
-  '/api/pick-folder',
-]);
+export const DECLINED_POST = new Set([]);
 
 /**
- * The POSTs P6f answers — and this table IS the dispatch, not a declaration beside it.
- *
- * M23's lesson, applied one verb over: `test_the_declared_partition_is_the_one_the_dispatcher_uses`
- * exists because a hand-kept list can agree with the reference while the running handler
- * does something else. `doPost` looks routes up HERE, and `PORTED_POST` is this table's own
- * keys, so the two cannot drift — the same reason `STATE_ROUTES` is a table on the GET side.
- *
- * THE SECOND COLUMN IS THE 409 CONVENTION, and it is a column because it is not uniform.
- * `ok: false` means the write did not happen — a stale fingerprint, a body that never
- * parsed, nothing to remove — and the client must re-fetch rather than retry, which is what
- * 409 says and 200 does not. Five routes map it. `/api/activity` does NOT: its flag write
- * answers 200 whatever `ok` says, and a port that unified the rule would be wrong exactly
- * there. `/api/memory/delete` carries no `ok` at all — it deletes, or it raises `NotFound`
- * and the outer catch answers 404 — so it is `false` here for a third reason again.
- *
- * `NotFound` IS NOT CAUGHT PER ROUTE. The reference wraps six of these calls in their own
- * `except NotFound` AND wraps the whole of `_post_routes` in another inside `do_POST`. The
- * inner six are redundant — every one produces the same `{"error": "not found: …"}` at 404
- * — so the twin keeps the outer one only, in `handler`, where `do_POST`'s is.
+ * The POSTs this daemon answers — and this table IS the dispatch, not a declaration beside
+ * it: `doPost` looks routes up HERE, so a hand-kept declaration and the running dispatcher
+ * cannot drift.
+ *
+ * THE SECOND COLUMN IS THE 409 CONVENTION: `ok: false` means the write did not happen, and
+ * the client must re-fetch rather than retry — which 409 says and 200 does not. Two
+ * exceptions: `/api/activity` answers 200 whatever `ok` says (unifying the rule would be
+ * wrong there), and `/api/memory/delete` carries no `ok` at all (it deletes, or raises
+ * `NotFound` for a 404).
+ *
+ * `NotFound` is caught once, in `handler`, not per route — repeating the catch here would
+ * only duplicate it.
  */
 export const POST_ROUTES = new Map([
   ['/api/mcp', [apiMcpToggle, true]],
-  // P6i. `_post_routes` wraps this one in its own `except NotFound` and then maps
-  // `ok: false` to 409 — the same shape as `/api/mcp` beside it, so it fits the table's
-  // second column exactly and needs no third inline dispatch. The inner catch is redundant
-  // (see this table's docblock); `handler`'s outer one answers identically.
   ['/api/install', [apiInstallToggle, true]],
   ['/api/excludes', [apiExcludesMutate, true]],
   ['/api/view', [apiSelectView, true]],
   ['/api/activity', [apiActivityToggle, false]],
-  // `(self._read_json_body().get("name") or "")` — the SHELL resolves the name, and the
-  // endpoint takes a bare slug rather than a body.
+  // The dispatch wrapper resolves `name` from the body itself; `apiMemoryDelete` takes a bare
+  // slug string, not the body object, unlike the other routes here.
   ['/api/memory/delete',
     [(state, b) => apiMemoryDelete(state, isTruthy(b.name) ? formatValue(b.name) : ''), false]],
   ['/api/rules', [apiRulesMutate, true]],
@@ -121,87 +82,56 @@ export const POST_ROUTES = new Map([
 export const PORTED_POST = [...POST_ROUTES.keys()];
 
 /**
- * The 409 column, exported so it can be cross-checked against the reference's own `200 if
- * res.get("ok") else 409` conditionals by `ast`.
- *
- * A MUTATION IS WHY THIS EXISTS. Giving `/api/activity` the 409 treatment survived the whole
- * cell matrix: every toggle a cell can perform succeeds, and reaching the `ok: false` arm
- * needs the flag write to raise — which the two runtimes word differently, so no byte
- * comparison could hold it. The column is the thing under test and no cell can see it, so
- * the gate reads it out of both implementations instead.
+ * The 409 column, exported so a test can assert it directly. Giving `/api/activity` the 409
+ * treatment is the invisible mutation: nothing in normal use can force the `ok: false` arm
+ * to raise, so the convention has to be checked on its own rather than inferred from
+ * behaviour.
  */
 export const POST_ROUTES_CONVENTION = Object.fromEntries(
   [...POST_ROUTES].map(([p, [, okIs409]]) => [p, okIs409]),
 );
 
 /**
- * The GET paths the dispatcher answers OUTSIDE the two tables, declared so the partition
- * cross-check can see them: `/api/ping` is the shell's own, and the two Docs routes take
- * the `?harness=` query param, which a `(state)` table entry has no way to receive.
- *
- * A declaration is not a dispatcher — M23 — so
- * `test_the_declared_partition_is_the_one_the_dispatcher_uses` probes all three against
- * the running handler as well.
+ * The GET paths answered OUTSIDE the two tables, declared so the partition cross-check can
+ * see them: `/api/ping` is the shell's own, and the two Docs routes take the `?harness=`
+ * query param, which a `(state)` table entry has no way to receive. A probe checks all
+ * three against the running handler too, not merely against this list.
  */
 export const PORTED_INLINE = ['/api/ping', '/api/docs', '/api/docs/page/',
   '/api/jobs', '/api/jobs/'];
 
 /**
- * The POSTs P6g answers outside `POST_ROUTES`, and they are outside it for a reason the
- * table's SECOND COLUMN makes plain.
- *
- * `POST_ROUTES` maps a route to `(fn, okIs409)` — one handler taking `(state, body)`, one
- * boolean deciding 200 against 409. The jobs routes fit neither half. `/api/jobs/<id>/cancel`
- * answers 200 or 404 on a lookup, not on an `ok` field; `/api/actions/<x>` answers 202 with a
- * job id, 409 when the runner is busy, 404 for an action the table does not name, 501 for one
- * that has not crossed, 400 or 409 for a resolver's refusal, and 200 for `restore` — six
- * statuses over one prefix, none of them read off `ok`. Bending the column to fit would make
- * it lie about the five routes it currently describes exactly, so these dispatch beside the
- * table and `tests/test_web_jobs.py` reads them out of `PORTED_POST_INLINE` instead.
+ * The POSTs that answer outside `POST_ROUTES`, because they don't fit its shape:
+ * `/api/jobs/<id>/cancel` answers 200 or 404 on a lookup, not an `ok` field, and
+ * `/api/actions/<x>` spans six statuses (202, 409, 404, 501, 400, 200) over one prefix, none
+ * read off `ok`. Bending the 409 column to fit either would make it lie about the routes it
+ * already describes correctly.
+ *
+ * `/api/pick-folder` joined 2026-08-27 for a THIRD reason: `POST_ROUTES`'s `fn(state, body)
+ * -> object` shape answers the instant `fn` returns, and this endpoint cannot — it spawns a
+ * native folder dialog and answers only once a human (or a timeout) closes it. See
+ * `apiPickFolder` in `js/web/actions.mjs`, dispatched inline from `js/web/handler.mjs`'s
+ * `doPost` the same way the other three rows here are.
  */
 export const PORTED_POST_INLINE = ['/api/shutdown', '/api/restart', '/api/jobs/',
-  '/api/actions/'];
+  '/api/actions/', '/api/pick-folder'];
 
 /**
- * POST routes THAT NEVER EXISTED ON THE REFERENCE — the first of them, and the reason this set
- * has to exist at all.
- *
- * `test_every_post_route_is_either_ported_or_declared_unported` asserts SET EQUALITY against
- * `REF_POST`, a frozen literal of the paths the Python daemon answered. That was exactly right
- * while the port was in flight: a route on one side and not the other was a defect either way.
- * The port is finished and the reference is deleted, so the assertion now says something else —
- * "this daemon may never grow a route" — which is a rule nobody chose.
- *
- * SO THE PARTITION GAINS A FOURTH PART RATHER THAN LOSING ITS EQUALITY. Widening `REF_POST` would
- * have been the cheap edit and it would have been a lie: that list is a RECORD of what the
- * reference answered, and a route added in 2026 was never in it. Keeping the record honest and
- * declaring the additions beside it keeps both claims checkable — the reference's surface is
- * still pinned, and everything past it is enumerated here instead of merely appearing.
- *
- * A route belongs here only once it is dispatched below; the dispatcher probe is what keeps this
- * from becoming a declaration nobody honours.
+ * POST routes added after the ported reference surface was frozen. Kept separate from
+ * `NOT_PORTED_POST` so that frozen record stays honest, while a new route is still
+ * enumerated rather than appearing unchecked. Belongs here only once dispatched below — a
+ * probe, not just this declaration, is what keeps that true.
  */
 export const POST_BEYOND_REF = new Set([
   '/api/reveal',
 ]);
 
 /**
- * GET routes THAT NEVER EXISTED ON THE REFERENCE — the same fourth part of the partition, one
- * verb over, and it exists for the reason `POST_BEYOND_REF` above spells out in full.
- *
- * `test_every_get_route_is_either_ported_or_declared_unported` asserts SET EQUALITY against
- * `REF_GET`, a frozen literal of the paths the Python daemon answered. Widening that list to
- * admit a route added in 2026 would forge the record; leaving the equality unqualified would
- * mean this daemon may never grow a GET. So additions are enumerated here instead, and the
- * gate compares the covered set against the reference's surface PLUS this one.
- *
- * `/api/recent` is the first, and it is a genuine gap rather than a convenience: no catalog row
- * on the whole surface carries a date, and a browser cannot stat the `source` path it is handed
- * — so "what changed lately" had no answer that did not involve the server looking. See
- * `apiRecent` in `api.mjs` for what it will and will not date.
- *
- * A route belongs here only once it is dispatched; the dispatcher probe is what keeps this from
- * becoming a declaration nobody honours.
+ * GET routes added after the ported reference surface was frozen — the same reason
+ * `POST_BEYOND_REF` above exists, one verb over. `/api/recent` is a genuine gap: no catalog
+ * row carries a date and a browser cannot stat the `source` path it is handed, so "what
+ * changed lately" needed a server that looks. See `apiRecent` in `api.mjs` for what it will
+ * and will not date.
  */
 export const GET_BEYOND_REF = new Set([
   '/api/recent',
@@ -217,21 +147,12 @@ export function notPortedPost(path) {
 }
 
 /**
- * `Handler._read_json_body` — the drained body as a dict, `{}` for ANYTHING else.
- *
- * P6a retained the drain with a note that it was measured indistinguishable and stayed
- * because "`_read_json_body` needs the bytes from P6f on". This is that caller.
- *
- * `{}` AND NEVER A RAISE is the contract, and it is what makes a malformed body a 409 or a
- * 404 from the endpoint's own validation rather than a 500 from a parser. That matters
- * beyond tidiness: P5a's one un-portable line is a `json` error message, because CPython
- * and V8 word them differently AND report different offsets — so a 500 carrying a parse
- * error is a response the two implementations can never agree on.
+ * The drained request body as a plain object, `{}` for ANYTHING else — never a raise, so a
+ * malformed body becomes a 409/404 from the endpoint's own validation, not a 500.
  *
  * `parseJson`, not `JSON.parse`: a body value can be written straight into a user's file
- * (`api_profile_save`'s `text`, `api_rules_mutate`'s `title`) and `str(1.0)` is `"1.0"`
- * where `String(1)` is `"1"`. A non-object body — a bare list, a number, `null` — takes the
- * same `{}` arm as garbage, because `isinstance(obj, dict)` is what the reference asks.
+ * (`apiProfileSave`'s `text`, `apiRulesMutate`'s `title`), and `parseJson` keeps the
+ * int/float distinction plain `JSON.parse` loses (see `lib/json.mjs`).
  */
 export function readJsonBody(buf) {
   let obj;

package/js/web/server.mjs

@@ -4,44 +4,23 @@
  * declarations in `routes.mjs`, the daemon record and lifecycle in `daemon.mjs`; this file
  * binds a socket and wires the three together.
  *
- * WHY THE SHELL FIRST, AND ALONE. `_web_server.py` is 654 lines and none of it is an API
- * function: it is routing, two security guards, gzip negotiation, the static route with
- * its per-request token injection, and the daemon record. Every one of those is invisible
- * to a test that calls `api_X(state)` in process — which is how `tests/test_web.py`
- * reaches all 136 of its assertions — so the shell is both the part with no existing
- * coverage and the part every later sub-phase builds on. `tests/web_golden.py` is its
- * gate and was written before this file.
- *
- * THE SERIALISER, WHICH TOUCHES ALL 29 PATHS. `_send_json` is a bare `json.dumps(obj)`:
- * Python's DEFAULT separators, `(', ', ': ')`, and `ensure_ascii=True`. That is exactly
- * `jsonDumpsCompact` — whose name says "compact" meaning "no indent", not "no spaces";
- * read its body, it joins on `', '`. So the twin needs no new helper and the response
- * bodies stay byte-comparable.
- *
- * Its one condition is the int/float distinction. `formatValue` refuses a BARE JS number
- * because `json.loads` tells `20` from `1.0` and `JSON.parse` does not — but the numbers
- * in a response body are not parsed from JSON, they are computed here (counts, a port, a
- * pid, a unix second), and every one of them is a Python `int`, which renders identically
- * in both languages. `bareInts` says that out loud rather than wrapping several dozen
- * call sites in a factory. A Python float would be the counter-example — `1.0` against
- * JS's `1` — and the byte gate over every endpoint body is what would catch one.
- *
- * THE DAEMON LIFECYCLE MOVED OUT, AND THE PREDICTED CYCLE DID NOT MATERIALISE. This
- * docblock used to argue that splitting the handler from the daemon would make `serve()`
- * (which needs `npmBuild`) and the launcher (which needs `readDaemon`) import each other.
- * They do not: the dependency runs ONE WAY, `server → daemon`, because `npmBuild` stayed
- * here with `serve` and only the record readers went. `probe`, `liveDaemon`,
+ * MODULE BOUNDARY: the dependency runs one way, `server → daemon`. `probe`, `liveDaemon`,
  * `spawnDetached`, `start|stop|status|restartDaemon`, `openUrl` and `requestRestart` are in
- * `daemon.mjs`; `npmBuild`, `buildPlan`, `serve` and `cmdWeb` are here.
+ * `daemon.mjs`; `npmBuild`, `buildPlan`, `serve` and `cmdWeb` are here — `npmBuild` stays with
+ * `serve` rather than moving with the rest of the daemon lifecycle, which is why the split
+ * does not produce a two-way import.
  *
  * `bin/geneseed-cli.mjs` imports `cmdWeb` statically, which is what put this tree on the
- * CLI's import graph and moved `js/web/jobs.mjs`'s spawn row to `entry: "cli"` — and it is
- * why a runtime dependency reached from here would load on EVERY `geneseed` invocation.
+ * CLI's import graph and moved `js/web/jobs.mjs`'s `ALLOWED_SPAWNS` row to `entry: "cli"` —
+ * and it is why a runtime dependency reached from here would load on EVERY `geneseed`
+ * invocation.
  *
- * WHAT IS STILL NOT HERE, SINCE P6i: `/api/pick-folder` alone, and it is DECLINED rather than
- * deferred — an OS-native folder chooser has no Node twin that is not a new GUI dependency.
- * `NOT_PORTED_POST` is empty and stays declared, because an empty half of a partition is the
- * partition asserting there is nothing left; `DECLINED_POST` is what still has a member.
+ * WHAT WAS STILL NOT HERE, SINCE P6i UNTIL 2026-08-27: `/api/pick-folder`, DECLINED rather
+ * than deferred — an OS-native folder chooser had no Node twin that was not a new GUI
+ * dependency. The user overrode that decline; the endpoint now dispatches inline from
+ * `js/web/handler.mjs`'s `doPost` (see `apiPickFolder` in `js/web/actions.mjs`). Both
+ * `NOT_PORTED_POST` and `DECLINED_POST` are empty now and stay declared regardless, because an
+ * empty half of a partition is the partition asserting there is nothing left, not an omission.
  */
 import { GLOBAL_MANIFEST, resolvePath } from '../hosts/hosts.mjs';
 import { printOut } from '../lib/fs.mjs';
@@ -59,7 +38,7 @@ import { createServer } from 'node:http';
 import { join, resolve as pathResolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const ROOT = pathResolve(fileURLToPath(import.meta.url), '..', '..', '..');
+const ROOT = pathResolve(import.meta.dirname, '..', '..');
 
 // Re-exported so the console's state lives in one place and its importers are unchanged.
 export { webState };
@@ -67,16 +46,10 @@ export { webState };
 // ---- serve -----------------------------------------------------------------
 
 /**
- * Pure: what `serve()` should do about the UI bundle. Ported ahead of the rest of the
- * verb because it decides whether a server starts at all, and because it is the second
- * interactive prompt in this port — `interactive` is an ARGUMENT, which is what makes it
- * gateable by a corpus rather than only by a cell.
- *
- * P6h GAVE IT BOTH KINDS OF GATE AND FOUND THE CLAIM ABOVE HAD NEVER BEEN PAID. It had a
- * Python unit test (`tests/test_web.py`) and nothing cross-implementation until now: the
- * corpus in `tests/test_pure_function_parity.py` covers all five answers, and two
- * `harness_golden` cells cover the two arms that TERMINATE — which are also the only two
- * that let a `web` cell exist at all, since every other arm of `serve` binds a socket.
+ * Pure: what `serve()` should do about the UI bundle, decided before anything else since it
+ * decides whether a server starts at all. `interactive` is a plain argument rather than a
+ * read of `process.stdin.isTTY` inside this function, which is what keeps it callable from a
+ * test without mocking stdin.
  */
 export function buildPlan(dist, webDir, npm, interactive) {
   if (isFile(join(dist, 'index.html'))) return 'serve';
@@ -87,15 +60,14 @@ export function buildPlan(dist, webDir, npm, interactive) {
 }
 
 /**
- * `npm install` then `npm run build` in `web/`, streams inherited — the third spawn this
+ * `npm install` then `npm run build` in `web/`, streams inherited — one of the spawns this
  * module declares, and the one NO test reaches.
  *
- * THAT IS A DECLARED PARTITION, not an omission. `web/dist/index.html` is TRACKED (asserted
- * by `tests/test_web_daemon.py` against `git ls-files`, so the claim cannot rot), which
- * means `buildPlan` answers `serve` in every checkout a cell can build and the `ask` arm is
- * reachable only from a partial checkout on an interactive terminal. There is no npm
- * library to call instead; a Node twin that reimplemented `npm install` is not a thing that
- * exists.
+ * THAT IS A DECLARED GAP, not an omission. `web/dist/index.html` is TRACKED (asserted by
+ * `tests/unit/web_daemon.test.mjs` against `git ls-files`, so the claim cannot rot), which
+ * means `buildPlan` answers `serve` in any checkout a test can build against, and the `ask`
+ * arm is reachable only from a partial checkout on an interactive terminal. There is no npm
+ * library to call instead of the real thing.
  *
  * `shell` ON WINDOWS, and it is required rather than stylistic: `which('npm')` resolves
  * to `npm.CMD` through PATHEXT, and Node refuses to `spawn` a `.cmd` directly. The path is
@@ -123,8 +95,8 @@ export async function serve({ theme = null, port = 4747, openBrowser = true,
   const dist = join(ROOT, 'web', 'dist');
   const webDir = join(ROOT, 'web');
   const manual = '        cd web && npm install && npm run build';
-  // `sys.stdin.isatty()`. `process.stdin.isTTY` is `undefined` rather than false on a pipe,
-  // which is the same trap `cmdSetup` documents.
+  // `process.stdin.isTTY` is `undefined` rather than false on a pipe — the same trap
+  // `cmdSetup` documents.
   const plan = buildPlan(dist, webDir, which('npm'), Boolean(process.stdin.isTTY));
   if (plan === 'no-source') {
     printOut(`[web] web/ sources are missing from ${ROOT}.\n`);
@@ -144,11 +116,10 @@ export async function serve({ theme = null, port = 4747, openBrowser = true,
     return 1;
   }
   if (plan === 'ask') {
-    // `except (EOFError, KeyboardInterrupt): answer = "n"`. EOF is the arm that matters and
-    // it is the one a naive port gets backwards: `input()` RAISES at EOF, so the reference
-    // reads it as "no", while a read that returned `''` would fall into the empty-answer
-    // arm and start an npm install nobody asked for. `promptLine` returns null for exactly
-    // that case — see its docblock in js/maintain/setup.mjs.
+    // EOF is the arm that matters: treated as an empty string it would fall into the
+    // empty-answer arm below (which defaults to yes) and start an npm install nobody asked
+    // for. `promptLine` returns null for exactly that case — see its docblock in
+    // js/maintain/setup.mjs — which is why `null` maps to `'n'` here.
     const line = promptLine('[web] UI not built — run npm install && npm run build now? [Y/n] ');
     const answer = line === null ? 'n' : line;
     if (['', 'y', 'yes'].includes(answer.trim().toLowerCase())) {
@@ -167,14 +138,14 @@ export async function serve({ theme = null, port = 4747, openBrowser = true,
   }
   const token = randomBytes(24).toString('base64url');
   const holder = {};
-  // `JobManager(history_path=state.target / ".geneseed-web-runs.json")` — the console's job
-  // list survives a reload and a restart because it is a FILE, not a process's memory.
+  // The console's job list survives a reload and a restart because it is a FILE on disk,
+  // not held in process memory.
   const jm = new JobManager(join(state.target, '.geneseed-web-runs.json'));
   const srv = createServer(makeHandler(state, jm, token, dist, holder));
   holder.srv = srv;
   return new Promise((done) => {
     srv.on('error', () => {
-      // The reference retries on port 0; the same fallback, one level in.
+      // On a listen error, retry with port 0 so the OS picks a free one.
       srv.listen(0, '127.0.0.1', () => ready());
     });
     srv.listen(port, '127.0.0.1', () => ready());
@@ -191,10 +162,9 @@ export async function serve({ theme = null, port = 4747, openBrowser = true,
       printOut(`[web] Geneseed UI on ${url}  (theme: ${state.theme})\n`);
       printOut(daemon ? '[web] daemon ready.\n' : '[web] Ctrl-C to stop.\n');
       if (openBrowser) openUrl(url);
-      // `except KeyboardInterrupt: print("\n[web] stopped.")` around `serve_forever`. Node
-      // kills on SIGINT by default, which would skip the message AND the record cleanup in
-      // the `finally` below — a foreground `--daemon-internal` server stopped with Ctrl-C
-      // would leave a record pointing at a dead port.
+      // Node kills on SIGINT by default, which would skip this message and the record
+      // cleanup in `srv.on('close', ...)` below — a foreground `--daemon-internal` server
+      // stopped with Ctrl-C would otherwise leave a record pointing at a dead port.
       process.on('SIGINT', () => {
         printOut('\n[web] stopped.\n');
         srv.close();
@@ -212,20 +182,18 @@ export async function serve({ theme = null, port = 4747, openBrowser = true,
 }
 
 /**
- * `cmd_web` — the verb `bin/geneseed-cli.mjs` dispatches to, and the reason this module is
+ * `cmdWeb` — the verb `bin/geneseed-cli.mjs` dispatches to, and the reason this module is
  * on the CLI's import graph at all (which is what moved `js/web/jobs.mjs`'s
- * `_ALLOWED_SPAWNS` row from `entry: "web"` to `entry: "cli"`).
+ * `ALLOWED_SPAWNS` row from `entry: "web"` to `entry: "cli"`).
  *
- * The reference's `cmd_web` does `import web` INSIDE the function; the ESM equivalent would
- * be a dynamic `import()`, and it is deliberately NOT used — a static import is what lets
- * `test_the_cli_reaches_child_process_only_where_it_is_declared` walk the CLI's graph and
- * find the two spawning modules under `js/web/`. The cost is parsing the web tree on every
- * CLI invocation; `bin/geneseed-cli.mjs` is user-invoked and carries no latency budget (the
- * hook entry, which does, is a different binary for exactly this reason).
+ * The import above is static rather than dynamic on purpose: a static import is what lets the
+ * spawn-graph walk find the two spawning modules under `js/web/`. The cost is parsing the web
+ * tree on every CLI invocation; `bin/geneseed-cli.mjs` is user-invoked and carries no latency
+ * budget (the hook entry, which does, is a different binary for exactly this reason).
  */
 export async function cmdWeb(args) {
-  // `--port` is `type=int` on the reference, and `bin/geneseed-cli.mjs`'s `ints` column
-  // refuses a non-integer before this runs — so `parseIntStrict` cannot be null here.
+  // `bin/geneseed-cli.mjs`'s `ints` column refuses a non-integer before this runs — so
+  // `parseIntStrict` cannot be null here.
   const port = args.port === null ? 4747 : parseIntStrict(args.port);
   const openBrowser = !args.noBrowser;
   if (args.action === 'start') return startDaemon(args.theme, port, openBrowser);
@@ -237,12 +205,9 @@ export async function cmdWeb(args) {
 
 // ---- entry -----------------------------------------------------------------
 //
-// KEPT AFTER P6h, and it is not a duplicate of the verb above. `tests/web_golden.py` drove
-// this module directly for all of P6a–P6g, and its 95 cells are what license the MOVE: the
-// same matrix now runs against `node bin/geneseed-cli.mjs web` as well, and a byte gate
-// that passed against one command proves nothing about the other until it is re-aimed. The
-// module entry is also what a debugging session reaches for when the CLI's argument layer
-// is the thing under suspicion.
+// Not a duplicate of `cmdWeb` above: this lets `node js/web/server.mjs` be run directly,
+// which is what a debugging session reaches for when the CLI's own argument layer is the
+// thing under suspicion.
 
 async function main(argv) {
   let theme = null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "Every field here is argued and gated in tests/unit/package_manifest.test.mjs. `files`, `bin` and `engines` each have a test that fails when reality drifts from this file; `version` mirrors harness.config.json and is gated too. Read that docblock before editing this one.",
   "name": "geneseed",
-  "version": "3.1.3",
+  "version": "3.2.0",
   "description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
   "keywords": [
     "ai",

package/src/agents/explorer.md

@@ -31,7 +31,8 @@
 - A concise answer: the conclusion, the key `file:line` references that support
   it, and any open questions. Never the full contents of what was read.
 - If the search comes up empty, report what was searched and where, and answer
-  not-found — a confident wrong location costs more than an honest blank.
+  not-found — a confident wrong location costs more than an honest blank
+  ({{LAW}} XI).
 
 ## Pipeline role
 

package/src/doctrines/process.md

@@ -83,5 +83,7 @@ the session — `D` decisions, `O` options, `F` findings, `R` risks, `Q` questio
 one within each kind, invent a new letter for a kind the list omits, and never
 renumber a code once issued — the user will cite it back, and a moved code makes
 their reply mean something you did not say. A code is an address, not an ornament:
-it lets a long exchange be answered by reference ({{ONTOLOGY}}: {{ONT_CONDUCT}}), and
-a decision taken on turn three still be named on turn thirty.
+it lets a long exchange be answered by reference, and a decision taken on turn
+three still be named on turn thirty. Where the {{ONTOLOGY}}'s {{ONT_CONDUCT}}
+governs how an answer speaks, this is only the addressing convention — a practice
+a repository adopts or drops like any other rule in these {{DOCTRINES}}.