geneseed 4.17.1 → 4.18.0

package/CHANGELOG.md

@@ -8,6 +8,32 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [4.18.0] — 2026-10-24
+
+Minor: the web console's numbers tell the truth (stale vs edited drift, lenses, Constitution, Docs) and it keeps your work (error boundary, draft guard, shared staging).
+
+### Fixed
+- **Drift numbers tell the truth.** A file that differs from the source only because the install is behind (unmodified since its build) is now `stale`, not `edited`; `.geneseed-version` is always a build stamp. The Overview counts only real hand edits and shows stale files as "N files behind"; Local edits lists them apart under **Behind source** with a rebuild banner; `diff --out` and the upgrade export include only real local changes. "Never fired" counts each skill once across the fleet. A failed fleet read says so and keeps the last good table; a zero ceiling prints "no ceiling"; the ceiling marker sits on the root file's own lane.
+- **The four Overview lenses agree with the Ledger.** They show the newest runs first, carry the fleet verdict badge, and read runs as `verb · scope · result · duration`. The Greenhouse ring is full at 100%, the Lineage badge no longer hard-codes "in sync", a failed doctor says so instead of drawing a false "1 checks", the HUD KPIs sit on one row, and the Journal map keeps its height.
+- **Constitution ranks tiers by the real precedence** (Dictates, your rules, Credo, Doctrines) and renders rule bodies as Markdown. Rule texts are cached and a failed read offers Retry; a partly-on pack reads as mixed; a disarmed gate is marked off; tier names follow the voice.
+- **Docs pages render their tokens.** The Memory and Notebook pages no longer show raw `{{…}}` build tokens. Heading ids come from one pass, so every outline link lands; wide tables scroll; Back no longer bounces off a hidden page; blocked storage no longer crashes the page; the Docs page no longer scrolls past the shell.
+- **The console survives a page crash.** A page error or a missing chunk after an upgrade shows the error with Retry (or Restart) while the sidebar, topbar and console stay. A malformed `#/item/…` link no longer blanks the app; Skip to content works; each page change sets the title, scrolls to the top and moves focus to the page.
+- **Unsaved work is kept.** Profile and Rules keep a draft through a 409 conflict and ask before an in-app navigation discards it; a draft whose rule was removed reopens as a new rule. Staged kit and doctrine switches are held for the whole console, survive leaving the page, and are kept after a failed rebuild; a row shows "Rebuilding…" while its job runs.
+- **Slow answers no longer overwrite newer ones** in the console's data hook, and a failed first read shows an error instead of "Loading…" forever (Library entry, Activity session).
+
+## [4.17.2] — 2026-10-24
+
+Patch: the web console closes its security and data-loss holes from the 2026-10-24 audit.
+
+### Security
+- **Restore acts only on what the diff offers.** `POST /api/actions/restore` trusted the client's file list: one call could reset `user-rules.md`, `PROFILE.md` or a memory file to its seed, or delete a file the diff never listed. It now restores only the paths `/api/diff` offers, computed on the server. It never touches the files written once and then left to you (`user-rules.md`, `PROFILE.md`, `memory/`, `notebook/`). An added file is moved to `archived-restore/<stamp>/` in the install instead of being deleted.
+- **The web console cannot be framed or driven from another site.** Every response carries a Content-Security-Policy with `frame-ancestors 'none'` and a per-response nonce on the token script, plus `X-Frame-Options: DENY`, `nosniff` and `Referrer-Policy: no-referrer`. One request guard checks the exact Host and port, refuses a cross-site `/api` request (`Sec-Fetch-Site`, foreign `Origin`), and compares the token in constant time. A repeated `GET /api/doctor?fresh=1` reuses a run less than 3 s old. The server sets request and header timeouts.
+- **The markdown sanitizer drops SVG animation elements, `template`, raw-text elements and `style` attributes.** These closed a `javascript:` link set through `<set>`/`<animate>`, a full-page overlay drawn with `style`, and a mutation XSS through `xmp`, `noembed`, `noframes`, `noscript` or `plaintext`.
+
+### Fixed
+- **Settings › Maintenance no longer offers an Uninstall.** It ran `geneseed uninstall --yes` with no target, so it always removed the OpenCode global install, whichever install you were viewing. Each install keeps its own Uninstall in Installs › Hosts.
+- **Editing a rule keeps its scope.** A rule written `scope: global` was saved back as `project` on every Edit or Graduate. A scope the editor does not list is now kept as written. A rule body with a line that reads as a rule heading (`## …`) is refused with a 400, because it could create a second rule with a forged id. So is a `|` in the scope or source.
+
 ## [4.17.1] — 2026-10-23
 
 Patch: the web console's Update button works on a global npm install and re-checks for updates while the page is open.

package/README.md

@@ -334,7 +334,7 @@ geneseed rebuild-all   # re-render every registered install in its own theme + m
 ./geneseed upgrade     # just the content refresh (remembers theme + emit mode)
 ```
 
-**Local edits survive.** The self-improvement loops write to notes under `notebook/`, which no rebuild touches. If you or the agent edited deployed agent/skill files in place anyway, an upgrade exports that drift to an `improvements/` file inside the install before overwriting. Details: [Upgrade](docs/guides/upgrade.md).
+**Local edits survive.** The self-improvement loops write to notes under `notebook/`, which no rebuild touches. If you or the agent edited deployed agent/skill files in place anyway, an upgrade exports those edits to an `improvements/` file inside the install; the rebuild then keeps each edited file instead of overwriting it. Details: [Upgrade](docs/guides/upgrade.md).
 
 ## 📚 Documentation
 

package/SHIPPED.md

@@ -20,7 +20,7 @@ historical references, not files distributed with the repo.
 > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
 > human-readable label only. The canonical identity of an installed harness is the
 > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
-> string. Current label: **4.17.1**.
+> string. Current label: **4.18.0**.
 
 ## Capabilities
 

package/docs/extending.md

@@ -125,7 +125,7 @@ Notes that matter:
 
 ### The gates CI does not run
 
-- **The mutation matrix itself.** `tests/mutate.mjs` — 35 rows, each a one-string edit to a
+- **The mutation matrix itself.** `tests/mutate.mjs` — 34 rows, each a one-string edit to a
   product file with a written argument for which gate should catch it. The full run is **in no
   workflow** and should not be: it mutates the product tree 33 times and runs a gate per edit.
   Run `node tests/mutate.mjs --all` (or `--only M7`) by hand when you change something a gate is

package/docs/guides/upgrade.md

@@ -64,7 +64,7 @@ A rebuild only replaces files the install's manifest says Geneseed owns. It leav
 
 ## Local edits, and the improvements file
 
-The agent records what it learns about a skill or agent in notes under `notebook/skill-notes/` and `notebook/agent-notes/`, which rebuilds never touch. Edits made to the deployed agent and skill files themselves, by you or by an older harness, are another matter: a rebuild would overwrite those, so **setup, re-theme and upgrade export them first**. When the files they are about to overwrite differ from a fresh render, the differences are written to a markdown **improvements file** in `improvements/`, inside the install's own folder (for the OpenCode global install, `~/.config/opencode/improvements/`). The manifest does not list that folder, so rebuilds never overwrite it and uninstall never removes it.
+The agent records what it learns about a skill or agent in notes under `notebook/skill-notes/` and `notebook/agent-notes/`, which rebuilds never touch. Edits made to the deployed agent and skill files themselves, by you or by an older harness, are another matter: a rebuild would overwrite those, so **setup, re-theme and upgrade export them first**. When deployed files carry local edits (files only behind the source are not edits and are not exported), the differences are written to a markdown **improvements file** in `improvements/`, inside the install's own folder (for the OpenCode global install, `~/.config/opencode/improvements/`). The manifest does not list that folder, so rebuilds never overwrite it and uninstall never removes it.
 
 A rebuild also refuses to overwrite a file you edited. The manifest records a fingerprint of every file Geneseed wrote; when a file no longer matches it, the rebuild leaves it alone and prints `kept your edited <file> — delete it to get Geneseed's copy back`. From then on the file is yours and later rebuilds skip it. A file the new version no longer ships is kept the same way, with `(no longer shipped)`. Line-ending changes from a git checkout do not count as edits. Installs made before fingerprints existed are overwritten as before.
 
@@ -76,7 +76,7 @@ geneseed diff --full                   # with line-level diffs
 geneseed diff --out improvements.md    # write the improvements file
 ```
 
-`diff` compares the global OpenCode install by default. Pass `--target <config dir>` to compare another install. A file you replaced with a link to your own copy (a skill folder junctioned or symlinked elsewhere, say) is listed as `linked`: Geneseed never writes through a link, so it is yours and not drift, and it stays out of the improvements file. `diff` also lists every non-empty self-improvement note, and `--out` copies them into the improvements file; the upgrade export does not fire on notes alone, since a rebuild cannot lose them. The improvements file is self-contained. To make the changes permanent, hand it to an agent in a Geneseed clone and ask it to fold them back into `src/`. Then they survive every future build. The web console's **Changes** page exports the same file.
+`diff` compares the global OpenCode install by default. Pass `--target <config dir>` to compare another install. A file you replaced with a link to your own copy (a skill folder junctioned or symlinked elsewhere, say) is listed as `linked`: Geneseed never writes through a link, so it is yours and not drift, and it stays out of the improvements file. A file unmodified since its build that differs only because the source moved on is listed as behind source; a rebuild updates it, and it stays out of the improvements file too. `diff` also lists every non-empty self-improvement note, and `--out` copies them into the improvements file; the upgrade export does not fire on notes alone, since a rebuild cannot lose them. The improvements file is self-contained. To make the changes permanent, hand it to an agent in a Geneseed clone and ask it to fold them back into `src/`. Then they survive every future build. The web console's **Changes** page exports the same file.
 
 ## Moving from a clone to npm
 

package/docs/web-ui.md

@@ -44,6 +44,15 @@ so other sites can't trigger builds, deletes, or shutdown. Mutating actions (bui
 update, export, restore, memory-delete, uninstall) run in the background and report back
 as toasts (fire-and-notify). Read-only browsing needs no token.
 
+Every request passes one guard first: the `Host` must be `127.0.0.1`, `localhost` or `[::1]`
+**at the server's own port** (DNS rebinding, other local servers), `/api/*` refuses a
+`Sec-Fetch-Site` of `cross-site`/`same-site` or a foreign `Origin` (so another site cannot read
+the API either), and every write compares the token in constant time. Every response carries
+`X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer` and a
+strict CSP (`frame-ancestors 'none'`, same-origin only, the one inline token script admitted by
+a per-response nonce). `?fresh=1` on the doctor re-runs at most once per 3 s, and the server
+drops a request whose headers take over 10 s or whose whole request takes over 30 s.
+
 ## The rail
 
 The left rail mirrors the harness's own shape:
@@ -74,8 +83,11 @@ streams the output of background jobs and keeps their history across reloads.
 - **Dashboard** (`#/`) — a live readout of what's deployed. Three lenses: **Status**
   (readiness ring, a KPI band, a genome grid, recent activity), **Lineage** (the
   source → render → deployed timeline and the genome-by-volume strand chart), and
-  **Operator** (a searchable table of every deployed capability). Headlines reflect the
-  active theme's voice.
+  **Operator** (a searchable table of every deployed capability). Every lens hero carries the
+  fleet verdict badge (the Ledger's `fleetVerdict`). The headline speaks the theme's voice only
+  while that verdict is good or still loading; a warn, bad or unreachable fleet reads plain
+  *Deployed*. Recent-run previews read `verb · scope · result · duration`, and the raw command
+  is a tooltip only.
 
   The KPI band reads **Agents · Skills · Dictates · Local edits**. That third tile is
   labelled *Dictates* (the name AGENT.md gives the laws) and not *Constitution* on purpose: its value is the law count
@@ -89,7 +101,9 @@ streams the output of background jobs and keeps their history across reloads.
 
 - **Rules** (`#/rules`) — your own standing rules, read from and written to the
   `user-rules.md` beside the deployed AGENT.md (the seed-once file no update ever
-  touches). List with scope (user/project) and trial chips, add/edit/retire forms, a
+  touches). List with scope (user/project, or any other scope written by hand, which a
+  save keeps as written) and trial chips, add/edit/retire forms (a body line starting
+  `## ` is refused: the file would read it as a new rule heading), a
   **Graduate** action that adopts a trial rule for good, and a budget meter that turns
   amber as the always-loaded set gets heavy. Every write carries the fingerprint of the
   content the page last read — if an agent session edited the file meanwhile, the save
@@ -167,8 +181,12 @@ streams the output of background jobs and keeps their history across reloads.
 - **Activity** (`#/activity`) — the agent sessions on this machine: each one's status,
   the files it touched and its todo progress; open one for its detail.
 - **Changes** (`#/diff`) — the diff between the deployed harness and the source: edited /
-  added / missing files with per-file expansion and coloured unified-diff lines. Select
+  added / missing files, and files only behind the source (unedited; a rebuild updates them)
+  listed apart under **Behind source**, with per-file expansion and coloured unified-diff lines. Select
   files to **export an `improvements.md`** back-port, or **restore** them to source.
+  Restore acts only on files the diff lists, and never on your own files (`user-rules.md`,
+  `PROFILE.md`, `memory/`, `notebook/`). An added file is moved into
+  `archived-restore/<date-time>/` in the install, not deleted.
 - **Doctor** (`#/doctor`) — runs the same health engine as the `doctor` command (every
   theme, parity, links, authoring gates, drift), grouping any problems per check. It shows
   the server's last run — warmed at start, redone after a job, an install toggle or a view
@@ -201,14 +219,17 @@ streams the output of background jobs and keeps their history across reloads.
     add or remove one here, the web mirror of `harness exclude add|remove|list`.
 - **Kits** (`#/installs/kits`) — every install (disabled ones read-only) as a panel with one switch per kit.
   Toggling only stages the set; **Apply** asks first, then rebuilds that install with
-  exactly that set as a console job. Files you edited in a kit that is now off are kept,
+  exactly that set as a console job. Staged switches are held for the whole console: they
+  survive leaving the page, and the Kits page and Installs › Kits share them. A refetch drops a
+  row's staging only when that install's kits changed. A failed rebuild keeps it and says so,
+  and a reload asks first while anything is staged. Files you edited in a kit that is now off are kept,
   and the row lists them.
 - **Settings** (`#/settings`) — a **Console direction** picker (the visual flavour of the
   console: Cultivar, Operator, Matrix or Atlas) with a **Dashboard layout** control (Auto follows each theme's designed Status
   lens; Cultivar / Greenhouse / Operator / Journal force one regardless of skin), the
   install snapshot (deployed/target/theme/version/memory store), a Maintenance card (PATH
-  link/unlink, uninstall), an offline package download, server controls (Stop), and the
-  **About** colophon — project + creator credits and the source link, folded in from the
+  link/unlink and Update; each install is uninstalled from its own panel in Hosts), an
+  offline package download, server controls (Stop), and the **About** colophon — project + creator credits and the source link, folded in from the
   retired `#/about` tab (which still resolves here). Build, update, and MCP wiring live in
   the Harness tab.
 

package/harness.config.json

@@ -2,5 +2,5 @@
   "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
   "theme": "neutral",
   "product": "Geneseed",
-  "version": "4.17.1"
+  "version": "4.18.0"
 }

package/js/README.md

@@ -235,7 +235,7 @@ the deployed harness as JSON.
 |---|---|
 | `server.mjs` | `serve()`/`cmdWeb`: UI-build precheck, socket bind, token mint, daemon record wiring |
 | `routes.mjs` | The route tables — `STATE_ROUTES`, `PREFIX_ROUTES`, `POST_ROUTES` (+ its 409 column) — and the inline lists |
-| `handler.mjs` | One function per request: dispatch, gzip, Host/CSRF guards and body cap (before the body is read), static SPA fallback |
+| `handler.mjs` | One function per request: dispatch, gzip, `requestGuard` (Host+port, Origin/Sec-Fetch-Site on `/api`, constant-time CSRF token) and body cap (before the body is read), `securityHeaders` (CSP nonce, framing), static SPA fallback |
 | `state.mjs` | `webState` — the resolved install view every endpoint reads, with its cached inventory and doctor |
 | `catalog.mjs` | The Library read model: inventory, constitution tiers, memory/notebook/wiki/config items, `apiCatalog`/`apiItem`, `NotFound` |
 | `api.mjs` | The dashboard and settings reads: overview, recent, themes, setup, doctor, diff, installs, excludes, loops |

package/js/inspect/diff.mjs

@@ -54,7 +54,7 @@ import {
   trustOfDir,
   readJsonMaybe, readMaybe, themeOfDir,
 } from '../hosts/installs.mjs';
-import { safeLeaf } from '../hosts/owned.mjs';
+import { hashesOf, ownedState, safeLeaf } from '../hosts/owned.mjs';
 import { unifiedDiff, splitLines } from '../lib/udiff.mjs';
 import { printOut, printErr, readText, writeText, isFile } from '../lib/fs.mjs';
 import { toPlatformPath } from '../lib/paths.mjs';
@@ -86,8 +86,7 @@ export function cmpKey(rel, text) {
 }
 
 /** `_harness_diff._owned_set` — the files a global install claims, per its manifest. */
-function ownedSet(d) {
-  const data = readJsonMaybe(path.join(d, GLOBAL_MANIFEST));
+function ownedSet(d, data = readJsonMaybe(path.join(d, GLOBAL_MANIFEST))) {
   if (data === null || typeof data !== 'object') return new Set();
   const owned = data.owned;
   return new Set(Array.isArray(owned) ? owned : []);
@@ -275,8 +274,17 @@ export function diffCollect({
     ? memoExpected(memo, host, axes, deployedDir, sourceFp)
     : renderExpected(host, axes, deployedDir);
 
+  // The deployed manifest, read once: its `owned` and its `hashes` both classify below.
+  const manifest = readJsonMaybe(path.join(dir, GLOBAL_MANIFEST));
+  const deployedOwned = ownedSet(dir, manifest);
+  const hashes = hashesOf(manifest);
+  // STALE IS NOT AN EDIT. A file whose bytes still match the hash its emit recorded was never
+  // touched: it differs only because the source moved on, and the next rebuild overwrites it.
+  // Reporting it as "edited" told every install behind its source that it was hand-edited.
+  // Only a manifest with hashes can tell the two apart; a legacy one keeps the old reading.
+  const hashed = Object.keys(hashes).length > 0;
   const files = [];
-  const rels = [...new Set([...ownedSet(dir), ...exp.owned])].sort();
+  const rels = [...new Set([...deployedOwned, ...exp.owned])].sort();
   for (const rel of rels) {
     const a = path.join(dir, rel);
     const tb = exp.texts.get(posixRel(rel));
@@ -289,7 +297,11 @@ export function diffCollect({
         const diff = unifiedDiff(splitLines(tb), splitLines(ta), {
           fromfile: `source/${rel}`, tofile: `deployed/${rel}`, lineterm: '',
         });
-        rec = { rel, status: 'edited', diff };
+        // `.geneseed-version` is a build stamp: a different fingerprint in it is the install
+        // being behind, never an edit, with or without hashes.
+        const stale = rel === VERSION_MARKER
+          || (hashed && ownedState(dir, rel, hashes) === 'unmodified');
+        rec = { rel, status: stale ? 'stale' : 'edited', diff };
       }
     } else if (isFile(a)) {
       const body = splitLines(readText(a));
@@ -298,6 +310,9 @@ export function diffCollect({
         status: 'added',
         diff: ['(only in deployed — your addition)', '', ...body.map((ln) => `+${ln}`)],
       };
+    } else if (hashed && !deployedOwned.has(rel)) {
+      // In source and never in this install's manifest: new since its emit, not deleted.
+      rec = { rel, status: 'stale', diff: ['(new in source, not yet deployed — a rebuild adds it)'] };
     } else {
       rec = { rel, status: 'missing', diff: ['(in source, not deployed — re-emit to add)'] };
     }
@@ -318,9 +333,20 @@ export function diffCollect({
   return { target: dir, theme: themeName, files };
 }
 
-/** The records that are drift: everything but a `linked` path, which is the user's own. */
+/**
+ * The records that are drift: everything but a `linked` path, which is the user's own. A
+ * `stale` file stays in: `apiRestore` offers exactly this set, and restoring a stale file is
+ * the same as rebuilding it.
+ */
 export const drifted = (files) => files.filter((f) => f.status !== 'linked');
 
+/**
+ * The records that are LOCAL CHANGES: drift minus `stale`. A stale file has nothing to
+ * back-port (a rebuild updates it), so the improvements report and the export `setup` and
+ * `update` fire read this set, not `drifted`.
+ */
+export const localChanges = (files) => drifted(files).filter((f) => f.status !== 'stale');
+
 /** Where the self-improvement loops write, relative to an install's `notebook/`. */
 export const NOTES_DIRS = ['skill-notes', 'agent-notes'];
 
@@ -354,7 +380,8 @@ export function collectNotes(dir) {
 /** `_harness_diff._improvements_md` — pure; `when` is the caller's timestamp. */
 export function improvementsMd(target, theme, allFiles, when, notes = []) {
   // A linked path is never a back-port item: the file is the user's, not a local edit of ours.
-  const files = drifted(allFiles);
+  // Nor is a stale one: the source already has what it lacks.
+  const files = localChanges(allFiles);
   const edited = files.filter((f) => f.status === 'edited');
   const added = files.filter((f) => f.status === 'added');
   const missing = files.filter((f) => f.status === 'missing');
@@ -458,7 +485,10 @@ export function exportImprovements(target = null, theme = null, outPath = null)
   // Python's `if not files` — null AND the empty list both return, which is why the caller
   // gets `files` back rather than a bare path and can tell the two apart itself.
   // A linked path alone is not drift, or every update would export an empty report.
-  if (!collected.files || drifted(collected.files).length === 0) return [null, collected.files];
+  // Nor are stale files alone, or every update over an older install would export one.
+  if (!collected.files || localChanges(collected.files).length === 0) {
+    return [null, collected.files];
+  }
   return [writeImprovements(collected.target, collected.theme, collected.files, outPath),
     collected.files];
 }
@@ -515,20 +545,23 @@ export function cmdDiff(args) {
   const added = files.filter((f) => f.status === 'added');
   const missing = files.filter((f) => f.status === 'missing');
   const linked = files.filter((f) => f.status === 'linked');
+  const stale = files.filter((f) => f.status === 'stale');
   printOut(`[diff] deployed ${target}  vs  source (theme: ${theme})\n`);
   printOut(`[diff] ${edited.length} edited, ${added.length} added-in-deployed, `
     + `${missing.length} missing-from-deployed\n`);
   // Its own line, printed only when there is one, so the summary above is unchanged otherwise.
   if (linked.length) printOut(`[diff] ${linked.length} linked (yours, left alone)\n`);
+  if (stale.length) printOut(`[diff] ${stale.length} file(s) behind source — rebuild to update them\n`);
   const notes = collectNotes(target);
   if (notes.length) printOut(`[diff] ${notes.length} self-improvement note(s) to back-port\n`);
   for (const f of edited) printOut(`  ~ ${f.rel}   (edited in deployed — review to back-port)\n`);
   for (const f of added) printOut(`  + ${f.rel}   (only in deployed — your addition)\n`);
   for (const f of missing) printOut(`  - ${f.rel}   (in source, not deployed — re-emit to add)\n`);
   for (const f of linked) printOut(`  = ${f.rel}   (a link — yours, left alone)\n`);
+  for (const f of stale) printOut(`  · ${f.rel}   (behind source — a rebuild updates it)\n`);
   for (const n of notes) printOut(`  * ${n.rel}   (self-improvement note — review to back-port)\n`);
   if (args.out) {
-    if (drifted(files).length || notes.length) {
+    if (localChanges(files).length || notes.length) {
       // Bare `--out` is argparse's `nargs="?"` const: True, meaning "the default timestamped
       // path". `parse()` gives a flag `true` and an option a string, so the two arrive
       // distinguishable here without a third kind of entry in the VERBS table.

package/js/web/actions.mjs

@@ -27,7 +27,8 @@
  */
 import { spawn } from 'node:child_process';
 import {
-  accessSync, constants, copyFileSync, mkdirSync, mkdtempSync, realpathSync, rmSync, unlinkSync,
+  accessSync, constants, copyFileSync, existsSync, mkdirSync, mkdtempSync, realpathSync,
+  renameSync, rmSync,
 } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -36,7 +37,8 @@ import { emitGlobalInto } from '../build/driver.mjs';
 import {
   ROOT, discoverNames, knownRuleIds, loadKits, PACK_ORDER,
 } from '../build/source.mjs';
-import { withStdoutSwallowed } from '../inspect/diff.mjs';
+import { diffCollect, drifted, withStdoutSwallowed } from '../inspect/diff.mjs';
+import { SESSION_FILES } from '../hosts/hooks-context.mjs';
 import { excludeAdd, excludeRemove } from '../inspect/excludes.mjs';
 import { installProfile, setupBuildArgs } from '../build/generate.mjs';
 import { DEFAULT_PRESET, PRESETS } from '../loop/score.mjs';
@@ -503,13 +505,30 @@ export function globalEmitHostFor(emit) {
   return HOSTS.some((h) => h.host === host) ? host : 'opencode';
 }
 
+/**
+ * The session files' names and their top folders (`memory/`, `notebook/`, …): seed-once, the
+ * user's after the first build. Derived from `SESSION_FILES`, the one list of them.
+ */
+const SEED_FILES = new Set(SESSION_FILES.filter((r) => !r.includes('/')));
+const SEED_DIRS = new Set(SESSION_FILES.filter((r) => r.includes('/')).map((r) => r.split('/')[0]));
+const isSeedOnce = (rel) => SEED_FILES.has(rel) || SEED_DIRS.has(rel.split('/')[0]);
+
 /**
  * Restore selected drifted files from the SOURCE render.
  *
  * Source wins and local edits are discarded (the inverse, keeping them, is Export
- * improvements). Renders the expected copy exactly as `diffCollect` does, then per rel:
- * expected present -> overwrite/create the deployed copy; expected absent but deployed present
- * (an 'added' file) -> delete it; neither -> an error and nothing touched.
+ * improvements). Renders the expected copy exactly as `diffCollect` does, then per rel, BY ITS
+ * DIFF STATUS: edited/missing -> overwrite/create the deployed copy; added -> move it into
+ * `archived-restore/<stamp>/` inside the install; anything else -> an error and nothing touched.
+ *
+ * THE CLIENT'S LIST IS A SELECTION, NEVER AN AUTHORITY. Only a rel the drift list offers is
+ * acted on, and that list is `diffCollect` with the arguments `apiDiff` passes, so the panel and
+ * this verb cannot disagree. Trusting the POST made it a write-or-delete primitive over the whole
+ * install (audit SE-1, 2026-10): one request reset `user-rules.md` and the memory index to their
+ * stubs, a second unlinked a memory fact and an unrelated secret file. The seed-once files are
+ * refused even when a manifest claims them. An added file is ARCHIVED, never unlinked, in the
+ * `archived-<name>/<stamp>` shape `archiveStore` gives uninstall; nothing owns the archive, so
+ * the next diff does not list it.
  *
  * SYNCHRONOUS, AND NOT A JOB. One render, the same cost as a diff GET, and it returns a
  * structured result rather than a job id — which is why the dispatcher answers it before it
@@ -534,7 +553,11 @@ export function apiRestore(state, files) {
   const restored = [];
   const deleted = [];
   const errors = [];
+  let archive = null;
   const target = resolvePath(state.target);
+  const offered = new Map(drifted(diffCollect({
+    target: state.target, theme: state.theme, emit: state.emit }).files ?? [])
+    .map((f) => [f.rel, f.status]));
   const tmp = mkdtempSync(path.join(os.tmpdir(), 'geneseed-restore-'));
   try {
     const expected = resolvePath(path.join(tmp, 'expected'));
@@ -566,26 +589,48 @@ export function apiRestore(state, files) {
       const rel = stripWhitespace(formatValue(raw).replace(/\\/g, '/')).replace(/^\/+/, '');
       const dst = resolvePath(path.join(target, rel));
       const src = resolvePath(path.join(expected, rel));
+      const status = offered.get(rel);
       if (!rel || !within(dst, target) || !within(src, expected)) {
         errors.push(`${rel}: outside the deployed tree`);
-      } else if (isFile(src)) {
-        mkdirSync(path.dirname(dst), { recursive: true });
-        // A BYTE copy, so the restored file keeps the render's own line endings rather than
-        // the platform's (the `writeText`/`copy2` rule, one file over).
-        copyFileSync(src, dst);
-        restored.push(rel);
-      } else if (isFile(dst)) {
-        unlinkSync(dst);
-        deleted.push(rel);
+      } else if (!status || isSeedOnce(rel)) {
+        errors.push(`${rel}: not a drifted file restore may touch`);
+      } else if (status !== 'added' && !isFile(src)) {
+        errors.push(`${rel}: not in the source render`);
+      } else if (status !== 'added') {
+        // Caught per file, so one EISDIR/EBUSY cannot lose the report of the files before it.
+        try {
+          mkdirSync(path.dirname(dst), { recursive: true });
+          // A BYTE copy, so the restored file keeps the render's own line endings rather than
+          // the platform's (the `writeText`/`copy2` rule, one file over).
+          copyFileSync(src, dst);
+          restored.push(rel);
+        } catch (e) {
+          errors.push(`${rel}: could not restore (${e.code || e.message})`);
+        }
       } else {
-        errors.push(`${rel}: not in the source render nor deployed`);
+        // `archiveStore`'s local `YYYYMMDD-HHMMSS` stamp, one per call; a taken name gets `-2`, …
+        archive ??= path.join(target, 'archived-restore', new Date().toLocaleString('sv-SE')
+          .replace(/\D/g, '').replace(/^(\d{8})/, '$1-'));
+        let dest = resolvePath(path.join(archive, rel));
+        for (let n = 2; existsSync(dest); n += 1) dest = resolvePath(path.join(archive, `${rel}-${n}`));
+        if (!within(dest, archive)) {
+          errors.push(`${rel}: outside the archive`);
+          continue;
+        }
+        try {
+          mkdirSync(path.dirname(dest), { recursive: true });
+          renameSync(dst, dest);
+          deleted.push(rel);
+        } catch (e) {
+          errors.push(`${rel}: could not archive (${e.code || e.message})`);
+        }
       }
     }
   } finally {
     rmSync(tmp, { recursive: true, force: true });
   }
   state.refresh();
-  return { restored, deleted, errors };
+  return { restored, deleted, errors, archive };
 }
 
 /** (host, scope) -> the emit name that installs it. */

package/js/web/api.mjs

@@ -80,13 +80,24 @@ export function apiSetup(state) {
   };
 }
 
+// Short: a user who fixes a problem and clicks Re-run must not be shown the old verdict for long.
+const DOCTOR_COOLDOWN_MS = 3_000;
+
 /**
  * The same engine as the `doctor` verb, grouped per check — served from the state's cached run
  * (a lens visit or a page mount no longer pays ~3.6 s), and re-run only when `fresh` is asked
  * for: the Doctor page's Re-run button, as `GET /api/doctor?fresh=1`.
+ *
+ * A fresh ask within `DOCTOR_COOLDOWN_MS` of the last one THIS PATH ran reuses that run, so a
+ * page looping on `?fresh=1` cannot pin the event loop. `_doctorFreshAt` is written here only: a
+ * verdict planted any other way still re-runs. No single-flight promise — `runDoctor` is
+ * synchronous, so two fresh runs cannot overlap (revisit if it ever goes async).
  */
 export function apiDoctor(state, fresh = false) {
-  if (fresh) state.runDoctor();
+  if (fresh && Date.now() - (state._doctorFreshAt ?? 0) >= DOCTOR_COOLDOWN_MS) {
+    state.runDoctor();
+    state._doctorFreshAt = Date.now();
+  }
   const { ok, problems, checked_at } = state.doctor;
   return { ...state._doctorRun, ok, problems, checked_at };
 }
@@ -133,13 +144,15 @@ const memoOf = (state) => (state.renderMemo ??= renderMemo());
 
 /**
  * The edited/added/missing tally of a `diffCollect` file list, and apart from it the `linked`
- * paths — the user's own links, which the console never adds into a drift total.
+ * paths — the user's own links, which the console never adds into a drift total — and the
+ * `stale` ones, unedited files a rebuild updates, which the console shows as "behind".
  */
 const driftCounts = (files) => ({
   edited: files.filter((f) => f.status === 'edited').length,
   added: files.filter((f) => f.status === 'added').length,
   missing: files.filter((f) => f.status === 'missing').length,
   linked: files.filter((f) => f.status === 'linked').length,
+  stale: files.filter((f) => f.status === 'stale').length,
 });
 
 /**

package/js/web/catalog.mjs

@@ -24,11 +24,15 @@ import { readText, withDiscardableStderr, isDir, isFile } from '../lib/fs.mjs';
 import { comparePaths, normcase, within } from '../lib/paths.mjs';
 import { stripWhitespace } from '../lib/text.mjs';
 import { readJsonc } from '../hosts/settings.mjs';
-import { loadKits } from '../build/source.mjs';
+import { loadKits, makeCfg } from '../build/source.mjs';
+import { loadTheme } from '../build/render.mjs';
 
 /** A requested catalog section or item that does not exist. */
 export class NotFound extends Error {}
 
+/** A request body the route refuses on its content (a 400, not a 500): the caller can fix it. */
+export class BadRequest extends Error {}
+
 /** `??` would also swallow an explicit `null` the file declared; this does not. */
 export const dget = (obj, key, dflt) => (Object.hasOwn(obj, key) ? obj[key] : dflt);
 
@@ -479,6 +483,17 @@ function kitOwners() {
   return owner;
 }
 
+/**
+ * The constitution's tier nouns in the install's own voice. Pack titles already arrive themed
+ * ("Observance"), so a page that hard-coded "Ethos" beside "Dictates" mixed two voices; the
+ * theme file is the one writer of these words. An unknown theme throws here exactly as it
+ * already throws in `tuiInventory` for the same `state.theme`, so this adds no failure mode.
+ */
+function tierNouns(theme) {
+  const t = loadTheme(makeCfg(), theme);
+  return { ontology: t.ONTOLOGY, law: t.LAW, laws: t.LAWS, doctrines: t.DOCTRINES };
+}
+
 export function apiCatalog(state, section) {
   if (!SECTIONS.includes(section)) throw new NotFound(section);
   const inv = state.inventory;
@@ -491,7 +506,7 @@ export function apiCatalog(state, section) {
     items = inv.skills.map((e) => ({ name: e.name, title: e.name, desc: e.desc,
       source: e.source ?? null, klass: e.klass ?? 'build', status: e.status ?? 'unknown', kit: owner.get(`skill:${e.name}`) ?? null }));
   } else if (section === 'laws') {
-    items = constitutionItems(inv);
+    return { section, items: constitutionItems(inv), nouns: tierNouns(state.theme) };
   } else if (section === 'memory') {
     items = memoryItems(state);
   } else if (section === 'notebook') {

package/js/web/docs.mjs

@@ -18,7 +18,8 @@
 import { readdirSync } from 'node:fs';
 import path from 'node:path';
 
-import { DOCS, DOC_FOLDERS, ROOT, THEMES } from '../build/source.mjs';
+import { DOCS, DOC_FOLDERS, ROOT, THEMES, resolveRuleIds } from '../build/source.mjs';
+import { STRUCTURE, substitute } from '../build/render.mjs';
 import { cliReference } from '../ui/cli.mjs';
 import { readJsonMaybe, readMaybe } from '../hosts/installs.mjs';
 import { resolvePath } from '../hosts/hosts.mjs';
@@ -222,7 +223,9 @@ const GITHUB_BLOB = 'https://github.com/Arylmera/Geneseed/blob/main/';
  * A target that is a docs page becomes `#/docs/<id>` (its `#anchor` dropped — the console
  * addresses pages, not headings); any other repo file — a maintainer doc, a README under
  * `src/` — opens on GitHub, since the console does not serve it. Absolute URLs, in-page
- * anchors and fenced examples are left alone.
+ * anchors and fenced examples are left alone. So is a target that is no file at all: the
+ * memory convention shows example links (`topics/<topic>.md`) in code spans, and a GitHub URL
+ * to a file that does not exist is a dead link where the relative one is merely inert.
  */
 export function rewriteDocLinks(body, fromRel, idByRel) {
   if (!body.includes('.md')) return body;
@@ -233,7 +236,8 @@ export function rewriteDocLinks(body, fromRel, idByRel) {
     return line.replace(MD_LINK_RE, (m, target, anchor) => {
       const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(fromRel), target));
       const id = idByRel.get(resolved);
-      return id ? `](#/docs/${id})` : `](${GITHUB_BLOB}${resolved}${anchor ?? ''})`;
+      if (id) return `](#/docs/${id})`;
+      return isFile(path.join(ROOT, resolved)) ? `](${GITHUB_BLOB}${resolved}${anchor ?? ''})` : m;
     });
   }).join('\n');
 }
@@ -458,14 +462,28 @@ function readDocSource(rel) {
   return readMaybe(target) ?? '';
 }
 
+/** A theme's words, `{}` for a theme that is missing or malformed — never a throw. */
+function themeWords(theme) {
+  const doc = readJsonMaybe(path.join(THEMES, `${theme}.json`));
+  return doc && typeof doc === 'object' && !Array.isArray(doc) ? doc : {};
+}
+
+/**
+ * A `src/` file as an install would render it: rule citations named, then the deployed theme's
+ * words (neutral underneath, for a key the theme lacks) and the fixed STRUCTURE substituted —
+ * the build's own functions, so the page cannot drift from what lands on disk. Only string
+ * words go in: `substitute` throws on any other value, and a theme's AGENT_COLORS is a dict.
+ */
+function renderSource(text, theme) {
+  const words = Object.entries({ ...themeWords('neutral'), ...themeWords(theme) })
+    .filter(([, v]) => typeof v === 'string');
+  return substitute(resolveRuleIds(text), { ...Object.fromEntries(words), ...STRUCTURE });
+}
+
 /** The deployed theme's words beside the neutral ones, from `docs/reference/glossary.md`. */
 function glossary(state, page) {
-  const load = (theme) => {
-    const doc = readJsonMaybe(path.join(THEMES, `${theme}.json`));
-    return doc && typeof doc === 'object' && !Array.isArray(doc) ? doc : {};
-  };
-  const neutral = load('neutral');
-  const themed = state.theme !== 'neutral' ? load(state.theme) : neutral;
+  const neutral = themeWords('neutral');
+  const themed = state.theme !== 'neutral' ? themeWords(state.theme) : neutral;
   const rows = [];
   for (const { label, key, desc, analogy } of parseGlossaryTable(page.body ?? '')) {
     if (key === null) {
@@ -554,9 +572,11 @@ export function apiDocsPage(state, pageId, harnessName = null) {
  * using it.
  */
 const KIND_ROUTES = {
+  // The body's own H1 goes: MarkdownPage prints the page title as the H1, and a page has one.
   markdown: (state, pageId, page, hn) => {
-    const body = rewriteDocLinks(stripHarnessBlocks(readDocSource(page.source), hn),
-      page.source, idsByRel());
+    const text = renderSource(stripHarnessBlocks(readDocSource(page.source), hn), state.theme)
+      .replace(/^# [^\n]*(?:\r?\n)+/, '');
+    const body = rewriteDocLinks(text, page.source, idsByRel());
     return { id: pageId, title: page.title, kind: 'markdown', body,
       source: page.source, links: resolveLinks(state, body) };
   },