geneseed 3.10.0 → 3.11.0

package/js/build/generate.mjs

@@ -254,7 +254,18 @@ export function rebuildCommand(argv) {
  * choose — which is the same failure mode `_footprint_of_dir`'s WARN exists to prevent, at a
  * larger scale.
  */
-export function cmdRebuildAll() {
+export async function cmdRebuildAll() {
+  const rc = rebuildAll();
+  // A console started before an upgrade keeps serving the old `index.html`; restart it — only
+  // when stale, see `bounceDaemonIfRunning`. Lazy: no other verb in this module needs js/web/.
+  const { bounceDaemonIfRunning } = await import('../web/daemon.mjs');
+  await bounceDaemonIfRunning(null, (m) => printOut(`${m}
+`), { onlyIfStale: true });
+  return rc;
+}
+
+/** The rebuild itself, synchronous — `cmdRebuildAll` is it plus the console restart. */
+export function rebuildAll() {
   const targets = installTargets().filter(([h, s, r]) => installState(r, h, s) === 'active');
   if (!targets.length) {
     printOut('[rebuild-all] no active installs detected.\n');

package/js/build/source.mjs

@@ -168,6 +168,12 @@ export const CONFIG = path.join(ROOT, 'harness.config.json');
 export const THEMES = path.join(ROOT, 'themes');
 export const PLUGIN_SRC = path.join(ROOT, 'adapters', 'opencode', 'plugins');
 export const WORKFLOW_SRC = path.join(ROOT, 'adapters', 'opencode', 'workflows');
+/**
+ * The user docs: one folder per kind of reading, all under `docs/` so GitHub renders the same
+ * files the console serves. A page's id is its basename, so ids must be unique across folders.
+ */
+export const DOCS = path.join(ROOT, 'docs');
+export const DOC_FOLDERS = ['understand', 'guides', 'concepts', 'reference'];
 
 /**
  * `_build_render.posture_names()` / `mode_names()` — discovered, never hardcoded, so a new

package/js/cli-table.json

@@ -1,5 +1,5 @@
 {
-  "prog": "harness",
+  "prog": "geneseed",
   "commands": [
     {
       "name": "bootstrap",

package/js/hosts/mcp.mjs

@@ -68,7 +68,7 @@ export const MCP_PRESETS = {
       + 'install). Edit GITLAB_PERSONAL_ACCESS_TOKEN (scopes: api, read_repository) '
       + 'and GITLAB_API_URL before use. For a second instance (a self-hosted server), '
       + 'copy this block by hand under a new name and point it at the other URL — '
-      + 'SETUP.md has the pattern.',
+      + 'docs/guides/mcp.md has the pattern.',
     block: {
       type: 'local',
       command: ['npx', '-y', '@zereight/mcp-gitlab'],

package/js/hosts/settings.mjs

@@ -483,6 +483,18 @@ export function hookShimPath(platform = process.platform) {
   return path.join(shimHome(), ...shimRel(platform));
 }
 
+/**
+ * The paths the machine's hook shim names that are gone — `[]` when the shim is absent or live.
+ *
+ * Cheap on purpose: `status`, the doctor and EVERY CLI run call it (the run-time warning in
+ * `bin/geneseed-cli.mjs`), because a dead shim disables every hook of every Claude-shaped
+ * install and nothing else would say so. An absent shim is not dead — a checkout that has never
+ * emitted owns none — and an unreadable one is reported by the doctor, not here.
+ */
+export function shimDead() {
+  try { return shimDeadPaths(readText(hookShimPath())); } catch { return []; }
+}
+
 /**
  * `_build_settings._hook_shim_body`, with the two volatile values INJECTED.
  *
@@ -988,7 +1000,7 @@ export function migrateShape(commands, shimBody) {
 /**
  * `_build_settings._autostart_paths` — where a hand-written web-daemon autostart entry lives.
  *
- * NOTHING IN THIS REPOSITORY HAS EVER WRITTEN ONE — `SETUP.md` tells the user to create them
+ * NOTHING IN THIS REPOSITORY HAS EVER WRITTEN ONE — the install guide tells the user to create them
  * by hand, and no .py/.mjs/.sh/.cmd in the tree contains `vbs`, `LaunchAgents` or `plist`. So
  * `migrate` REPORTS a stale one and never rewrites it, on the rule `settingsIntegrityCheck`
  * already states: an entry the manifest does not claim is "possibly user-authored; left alone".

package/js/inspect/checks-authoring.mjs

@@ -13,7 +13,7 @@
  */
 import path from 'node:path';
 import {
-  CONFIG, PACK_ORDER, PLUGIN_SRC, RETIRED_RULE_IDS, ROOT, RULE_ID_RE, SRC, THEMES, canonFiles,
+  CONFIG, DOCS, DOC_FOLDERS, PACK_ORDER, PLUGIN_SRC, RETIRED_RULE_IDS, ROOT, RULE_ID_RE, SRC, THEMES, canonFiles,
   knownRuleIds, ruleCanon, titleKey,
 } from '../build/source.mjs';
 import { themeFiles } from '../hosts/installs.mjs';
@@ -763,7 +763,7 @@ export function countTableProblems() {
 
   // WHERE THE ONBOARDING COPY LIVES, AND WHY THIS READ MOVED. It used to open the one module
   // that held the web console's onboarding prose. That prose has since moved into
-  // `docs/web/*.md`, and the counts in it render from `{N_LAWS}` / `{N_AGENTS}` / `{N_SKILLS}`
+  // `docs/<folder>/*.md`, and the counts in it render from `{N_LAWS}` / `{N_AGENTS}` / `{N_SKILLS}`
   // — so the read was still succeeding against a file the sentences had left, all three arms
   // below scored zero, and the check looked healthy while gating nothing. A templated count
   // cannot drift; what these arms still catch is a maintainer typing the NUMBER into a page
@@ -773,7 +773,9 @@ export function countTableProblems() {
   // byte moves. `web` stays fail-soft — a missing docs tree is not an authoring fault.
   let web = '';
   try {
-    web = globSorted(path.join(ROOT, 'docs', 'web'), (n) => n.endsWith('.md'))
+    web = DOC_FOLDERS
+      .flatMap((f) => (isDir(path.join(DOCS, f))
+        ? globSorted(path.join(DOCS, f), (n) => n.endsWith('.md')) : []))
       .map(readText).join('\n');
   } catch { web = ''; }
   // ⚠ NOT FAIL-SOFT, UNLIKE `web` ABOVE, AND THE ASYMMETRY IS THE POINT. A missing `docs/web`

package/js/inspect/doctor.mjs

@@ -283,7 +283,7 @@ export function cmdDoctor(args) {
       // (`js/build/generate.mjs`), which forwards `--theme` and nothing else. So the front door
       // answered `unrecognized arguments: --sync-themes` to anyone who followed doctor's own
       // advice, for as long as the premise went unchecked. The flag belongs to the GENERATOR,
-      // whose binary is `geneseed-build` — which is what `README.md` and `SETUP.md` have said
+      // whose binary is `geneseed-build` — which is what `README.md` and the install guide have said
       // all along. A hint is a command; if it is not runnable it is decoration.
       printOut('  tip: a theme is missing a key another theme defines — run '
         + '`geneseed-build --sync-themes` to fill it from _TEMPLATE.json, '

package/js/inspect/inventory.mjs

@@ -108,7 +108,7 @@ export const SKILL_CLASS = {
   // `understand` before, which made that class a grab-bag.
   wiki: 'harness', geneseed: 'harness', rule: 'harness', profile: 'harness',
   herdr: 'harness', 'skill-forge': 'harness', 'consolidate-memory': 'harness',
-  teach: 'learn', quiz: 'learn',
+  teach: 'learn', quiz: 'learn', 'learn-mode': 'learn',
 };
 
 /** `k in dict` — own keys only, where `k in obj` also finds `Object.prototype` members. */

package/js/inspect/registry.mjs

@@ -17,10 +17,10 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync } from 'n
 import path from 'node:path';
 import os from 'node:os';
 
-import { expanduser } from '../hosts/hosts.mjs';
+import { expanduser, resolvePath } from '../hosts/hosts.mjs';
 import { writeText, isFile, isDir } from '../lib/fs.mjs';
 import { parseJson, jsonDumpsIndent } from '../lib/json.mjs';
-import { toPlatformPath } from '../lib/paths.mjs';
+import { toPlatformPath, within } from '../lib/paths.mjs';
 
 /** `_install_registry._path()` — `$XDG_CONFIG_HOME/geneseed/installs.json`. */
 function registryPath() {
@@ -28,6 +28,21 @@ function registryPath() {
   return path.join(base, 'geneseed', 'installs.json');
 }
 
+/**
+ * Is `root` a scratch install — inside the OS temp dir while the registry is not?
+ *
+ * Agent sessions emit into scratchpads under `%TEMP%`; recorded, each one is rebuilt by every
+ * `rebuild-all` and listed by every `status` for as long as the folder survives. The second
+ * clause is what keeps every test and golden cell meaningful: their registry lives in a
+ * sandbox under the temp dir too, so their temp roots are not scratch RELATIVE TO IT.
+ * `within` is case-insensitive on win32, so `C:\Users\X\AppData\Local\Temp` and its
+ * lower-cased spelling are one directory.
+ */
+export function isScratchRoot(root, registryFile) {
+  const tmp = resolvePath(os.tmpdir());
+  return within(resolvePath(root), tmp) && !within(resolvePath(registryFile), tmp);
+}
+
 function registryLoad() {
   try {
     const data = parseJson(readFileSync(registryPath(), 'utf8'));
@@ -59,6 +74,7 @@ export function registryRecord(dir) {
   try {
     let root;
     try { root = realpathSync.native(dir); } catch { root = path.resolve(dir); }
+    if (isScratchRoot(root, registryPath())) return;
     const cur = registryLoad();
     if (!cur.includes(root)) registrySave([...cur, root]);
   } catch { /* a registry hiccup must never fail a build */ }
@@ -75,6 +91,7 @@ export function registryRecord(dir) {
  */
 export function registryRoots() {
   const original = registryLoad();
+  const file = registryPath();
   const out = [];
   const kept = [];
   const seen = new Set();
@@ -96,7 +113,7 @@ export function registryRoots() {
     let key;
     try { key = existsSync(root) ? realpathSync.native(root) : root; } catch { key = root; }
     if (seen.has(key)) continue;
-    if (isDir(root) && isFile(path.join(root, '.geneseed-emit'))) {
+    if (isDir(root) && isFile(path.join(root, '.geneseed-emit')) && !isScratchRoot(root, file)) {
       seen.add(key);
       kept.push(root);
       out.push(root);

package/js/inspect/status.mjs

@@ -73,6 +73,7 @@ import {
   defaultTheme, installedDefaults, installTargets, manifestIsClaude, readJsonMaybe, readMaybe,
 } from '../hosts/installs.mjs';
 import { installProfile, rebuildCommand } from '../build/generate.mjs';
+import { shimDead } from '../hosts/settings.mjs';
 import { printOut } from '../lib/fs.mjs';
 import { codePointLength, padEndToWidth } from '../lib/text.mjs';
 
@@ -208,7 +209,9 @@ export function gateSummary(cfgDirs) {
       total += 1;
     }
   }
-  return { standing_down: standingDown, asks, total };
+  // `dead` is the machine shim's missing targets: every gate below is armed on paper and never
+  // runs, so it outranks `armed` in the row.
+  return { standing_down: standingDown, asks, total, dead: shimDead() };
 }
 
 /** `_harness_status._status_data`. */
@@ -350,7 +353,9 @@ export function statusLines(d, color = false) {
   // panels carry no `gates` key and must render unchanged.
   if (d.gates) {
     const g = d.gates;
-    const armed = g.standing_down.length
+    const armed = g.dead?.length
+      ? `DEAD — hook shim points at ${g.dead.join(', ')}; run: geneseed rebuild-all`
+      : g.standing_down.length
       ? `STANDING DOWN for this cwd (excludes.json in ${g.standing_down.join(', ')})`
       : 'armed';
     const byRule = Object.entries(g.asks).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))

package/js/lib/node-floor.mjs

@@ -0,0 +1,30 @@
+/**
+ * The Node floor — the FIRST import of all three binaries, so an old Node gets one sentence
+ * instead of a stack trace from whichever API it lacks.
+ *
+ * `engines` in package.json only makes npm warn, and `npx geneseed`, a global install and the
+ * hook shim all run the binaries directly. ESM links the whole graph before any body runs, so
+ * this only helps while every file still PARSES on the old Node; it runs before any of them
+ * executes. The hook exits 0: a hook must never block a tool call, and the message on stderr
+ * is what the host surfaces. Nothing here may print to stdout — the hook's decision channel.
+ */
+import path from 'node:path';
+
+export const NODE_FLOOR = '22.3.0';
+
+/** Numeric, not string, comparison: '22.10.0' is above '22.3.0'. */
+export function belowFloor(version, floor = NODE_FLOOR) {
+  const v = version.replace(/^v/, '').split('.').map(Number);
+  const f = floor.split('.').map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    if ((v[i] || 0) !== f[i]) return (v[i] || 0) < f[i];
+  }
+  return false;
+}
+
+if (belowFloor(process.versions.node)) {
+  process.stderr.write(`geneseed needs Node 22.3 or newer; this is Node ${process.versions.node}. `
+    + 'Install a current Node from https://nodejs.org (or your package manager), then run the '
+    + 'command again.\n');
+  process.exit(path.basename(process.argv[1] || '').startsWith('geneseed-hook') ? 0 : 1);
+}

package/js/maintain/setup.mjs

@@ -50,9 +50,10 @@ import { discoverNames, PACK_ORDER } from '../build/source.mjs';
 import { exportImprovements } from '../inspect/diff.mjs';
 import { cmdDoctor } from '../inspect/doctor.mjs';
 import { setupBuildArgs } from '../build/generate.mjs';
-import { GLOBAL_MANIFEST, opencodeConfigDir } from '../hosts/hosts.mjs';
+import { GLOBAL_MANIFEST, HOSTS, opencodeConfigDir } from '../hosts/hosts.mjs';
 import {
-  defaultMode, defaultPosture, defaultTheme, installedDefaults, themeFiles,
+  claudeCfg, defaultMode, defaultPosture, defaultTheme, EMIT_HOST_SCOPE, installedDefaults,
+  readJsonMaybe, themeFiles,
 } from '../hosts/installs.mjs';
 import { printOut, printErr } from '../lib/fs.mjs';
 import { which } from '../lib/paths.mjs';
@@ -457,39 +458,77 @@ export function lspPrereqs() {
     + "SDKMAN `sdk install java 21-tem`, or your distro's package"]];
 }
 
+/** The name each host goes by on screen — the same four labels `hostTools` prints. */
+const TOOL_NAME = {
+  opencode: 'OpenCode', claude: 'Claude Code', bob: 'IBM Bob', openclaude: 'OpenClaude',
+};
+
+/**
+ * Where an emit put its root file, and — for the Claude-shaped hosts — its hooks.
+ *
+ * READ BACK, NOT RE-SPELLED: the placements differ by host and scope (Bob global's preamble is
+ * `rules/geneseed.md`, a Claude project's CLAUDE.md sits beside `.claude/`, a project's hooks go
+ * to `settings.local.json`, Bob global's to `settings/settings.json`), and the emit already
+ * records each one in the install's manifest (`managed.claude_md`, `settings_file`,
+ * `settings_hooks`). A summary that recomputed them would be a second owner of every rule.
+ */
+function emitFacts(emit, out) {
+  const [host, scope] = EMIT_HOST_SCOPE.get(emit) ?? ['files', 'project'];
+  if (host === 'files' || host === 'opencode') {
+    const dir = emit === 'opencode-global' ? opencodeConfigDir() : resolveOut(out || 'Harness');
+    return { host, rootFile: path.join(dir, 'AGENT.md') };
+  }
+  const spec = HOSTS.find((h) => h.host === host);
+  const cfg = claudeCfg(scope === 'global' ? spec.configDir() : resolveOut(out || '.'), scope, host);
+  const managed = readJsonMaybe(path.join(cfg, GLOBAL_MANIFEST))?.managed ?? {};
+  const rootFile = managed.claude_md?.rel
+    ? path.resolve(cfg, managed.claude_md.rel)
+    : path.join(cfg, host === 'bob' ? path.join('rules', 'geneseed.md') : spec.agentFile);
+  return {
+    host,
+    rootFile,
+    settings: managed.settings_file ? path.join(cfg, managed.settings_file) : null,
+    hookGroups: Array.isArray(managed.settings_hooks) ? managed.settings_hooks.length : 0,
+  };
+}
+
 /**
  * `_harness_setup._setup_summary_lines` — the post-build report as `[kind, text]` rows,
  * `kind` being ok | warn | info.
  *
  * `ok` is the build's own success, so the first row is the only one that can say "build
- * failed"; every later row assumes a tree on disk. The global-install warning is the row
- * with real behaviour in it: a bundle or project emit made while an OpenCode GLOBAL install
- * exists is loaded by nothing, and saying so is the difference between a wizard and a form.
+ * failed"; every later row assumes a tree on disk. HOST-AWARE since the install-hardening
+ * pass: it used to know only OpenCode's AGENT.md, so a successful claude-global install ended
+ * on "expected AGENT.md … but it is not there" and "start a NEW OpenCode session". The
+ * global-install warning is the row with real behaviour in it: a bundle or project emit made
+ * while an OpenCode GLOBAL install exists is loaded by nothing, and saying so is the
+ * difference between a wizard and a form.
  */
 export function setupSummaryLines(theme, emit, out, root, ok) {
-  const agentMd = emit === 'opencode-global'
-    ? path.join(opencodeConfigDir(), 'AGENT.md')
-    : path.join(resolveOut(out || 'Harness'), 'AGENT.md');
+  const f = emitFacts(emit, out ?? root);
+  const name = path.basename(f.rootFile);
   const lines = [];
-  if (ok && existsSync(agentMd)) {
-    lines.push(['ok', `AGENT.md written to ${agentMd}`]);
+  if (ok && existsSync(f.rootFile)) {
+    lines.push(['ok', `${name} written to ${f.rootFile}`]);
   } else if (ok) {
-    lines.push(['warn', `expected AGENT.md at ${agentMd} but it is not there`]);
+    lines.push(['warn', `expected ${name} at ${f.rootFile} but it is not there`]);
   } else {
     lines.push(['warn', 'build failed — see the output above']);
   }
-  if (emit === 'opencode-global') {
-    const cfgDir = opencodeConfigDir();
-    const hint = process.platform === 'win32'
-      ? `learn plugin: $env:GENESEED_HARNESS = "${cfgDir}"  (persist: setx GENESEED_HARNESS "${cfgDir}")`
-      : 'learn plugin: export GENESEED_HARNESS="$HOME/.config/opencode"';
-    lines.push(['info', hint]);
-  } else if (emit === 'files') {
-    lines.push(['info', `point your tool's instructions at ${agentMd}`]);
+  if (ok && f.settings) {
+    lines.push(['ok', `${f.hookGroups} hook groups wired in ${f.settings}`]);
+    if (!process.env.GENESEED_LLM) {
+      lines.push(['info', 'memory learning is off until you set GENESEED_LLM '
+        + '(see docs/reference/environment.md)']);
+    }
+  }
+  if (emit === 'files') {
+    lines.push(['info', `point your tool's instructions at ${f.rootFile}`]);
   }
   try {
     const cfg = opencodeConfigDir();
-    if (emit !== 'opencode-global' && existsSync(path.join(cfg, GLOBAL_MANIFEST))) {
+    // Only for an emit OpenCode itself would load — a Claude or Bob install is not shadowed.
+    if (['opencode', 'files'].includes(emit) && existsSync(path.join(cfg, GLOBAL_MANIFEST))) {
       lines.push(['warn', `a global install exists at ${cfg} — OpenCode loads THAT, `
         + `not this build; re-run with 'opencode-global' to change it`]);
     }
@@ -500,7 +539,12 @@ export function setupSummaryLines(theme, emit, out, root, ok) {
       lines.push(present ? ['ok', `${label} present`] : ['warn', `${label} missing — ${hint}`]);
     }
   }
-  lines.push(['info', `theme is now '${theme}' — start a NEW OpenCode session for the new voice`]);
+  const tool = TOOL_NAME[f.host];
+  lines.push(['info', tool
+    ? `theme is now '${theme}' — start a NEW ${tool} session to load it`
+    : `theme is now '${theme}' — start a NEW session in your tool to load it`]);
+  lines.push(['info', 'what was installed and what each piece does: '
+    + 'https://github.com/Arylmera/Geneseed/blob/main/docs/understand/on-your-machine.md']);
   return lines;
 }
 
@@ -593,5 +637,49 @@ export function cmdSetup() {
       + '  geneseed build --emit opencode-global --theme neutral\n');
     return 1;
   }
+  if (!toolsReport()) return 1;
   return setupLines();
 }
+
+/**
+ * The AI coding tools Geneseed installs into, as `[label, present, url]` rows in HOSTS order.
+ *
+ * PRESENT MEANS THE COMMAND IS ON PATH, and nothing else. The config dir looked like a second
+ * signal — a desktop-only install has one and no command — but GENESEED ITSELF CREATES IT: a
+ * `bob-global` emit writes `~/.bob` on a machine that never had Bob, and the first run of this
+ * check reported Bob present on exactly such a machine. A wrong "ok" sends the user to an
+ * install mode for a tool they cannot open; a wrong "not found" costs one line they can ignore.
+ *
+ * NO SPAWN, deliberately. `which` walks PATH by hand, so asking costs nothing on the CLI's
+ * child_process allow-list — a `claude --version` probe would have been a third entry there to
+ * learn nothing `which` does not already say. `lookup` is the seam for the test, which cannot
+ * rely on what this machine happens to have installed.
+ */
+export function hostTools({ lookup = which } = {}) {
+  return [
+    ['OpenCode', 'opencode', 'https://opencode.ai/docs/'],
+    ['Claude Code', 'claude', 'https://code.claude.com/docs/en/setup'],
+    ['IBM Bob', 'bob', 'https://bob.ibm.com/'],
+    ['OpenClaude', 'openclaude', 'https://openclaude.gitlawb.com/'],
+  ].map(([label, cmd, url]) => [label, Boolean(lookup(cmd)), url]);
+}
+
+/**
+ * Show which tools are here before asking anything — the install-mode question is easier to
+ * answer knowing it — and when NONE is, ask whether to stop and install one first. It never
+ * installs one: on a managed machine that is IT's call, and each tool has its own installer.
+ * A missing tool among several present is a line, not a question; nobody needs all four.
+ * `false` is the user choosing to stop.
+ */
+export function toolsReport(tools = hostTools()) {
+  printOut('AI coding tools on this machine:\n');
+  for (const [label, present, url] of tools) {
+    printOut(present ? `  ok  ${label}\n` : `  --  ${label} not on PATH — install: ${url}\n`);
+  }
+  if (tools.some(([, present]) => present)) { printOut('\n'); return true; }
+  printOut('\nNone of them is installed. Install the one you use (links above), then run setup '
+    + 'again — or go on and pick the plain bundle, which any AGENT.md tool can read.\n');
+  if (confirm('Continue without one?', false)) { printOut('\n'); return true; }
+  printOut('Stopped. Run setup again once a tool is installed.\n');
+  return false;
+}

package/js/maintain/update.mjs

@@ -50,7 +50,7 @@ import { appendText, copyFile, printOut, printErr, readText, writeText } from '.
 import { toPlatformPath, which } from '../lib/paths.mjs';
 import { WHITESPACE, parseIntStrict, stripWhitespace } from '../lib/text.mjs';
 import { NO_WINDOW } from '../lib/proc.mjs';
-import { restartDaemon } from '../web/daemon.mjs';
+import { bounceDaemonIfRunning } from '../web/daemon.mjs';
 
 /**
  * `_CREDS_RE` / `_redact_url_creds` — strip a `user[:token]@` userinfo out of any URL in
@@ -578,20 +578,9 @@ export async function rebuildBundle(here, out, theme, emit, rootDir, log) {
     { cwd: String(here), stdio: 'inherit' });
   if (proc.status !== 0) return proc.status === null ? 1 : proc.status;
   // If a web daemon is running, bounce it so the new source and the freshly rebuilt web/dist
-  // take effect — otherwise the open PWA keeps hitting the old code. EXCEPT when this
-  // upgrade IS a web-daemon job: restarting the daemon here kills the process tracking this
-  // very job (console stuck on 'running' forever); in that case the server restarts itself
-  // once the job is recorded as finished. `js/web/jobs.mjs` sets the variable; this is the
-  // side that reads it, and `upgrade/the-web-job-marker-...` is what gates the pair.
-  if (process.env.GENESEED_WEB_JOB) {
-    log('[geneseed] web daemon will restart itself after this job to load the new code.');
-    return 0;
-  }
-  try {
-    await restartDaemon(theme, 4747, false, true);
-  } catch (e) {                       // never fail an upgrade on this
-    log(`[geneseed] ⚠️  could not refresh the web daemon (${e && e.message ? e.message : e}) — \`geneseed web restart\` manually if it was running.`);
-  }
+  // take effect — otherwise the open PWA keeps hitting the old code. The web-job exception
+  // (`upgrade/the-web-job-marker-...` gates it) lives with the helper.
+  await bounceDaemonIfRunning(theme, log);
   return 0;
 }
 

package/js/ui/cli.mjs

@@ -69,7 +69,7 @@ function load() {
   try {
     return JSON.parse(readFileSync(CLI_JSON, 'utf-8'));
   } catch {
-    return { prog: 'harness', commands: [] };
+    return { prog: 'geneseed', commands: [] };
   }
 }
 
@@ -88,7 +88,7 @@ const pageArgs = (args) => (args ?? [])
 export function cliReference() {
   const data = load();
   return {
-    prog: data.prog ?? 'harness',
+    prog: data.prog ?? 'geneseed',
     commands: (data.commands ?? []).map((c) => ({
       name: c.name ?? '',
       help: c.help ?? '',

package/js/web/api.mjs

@@ -819,6 +819,9 @@ export function apiOverview(state) {
     install,
     target: state.target,
     deployed: deployed(state),
+    // True when the files on disk changed under this server since it started (an upgrade).
+    // `serve` installs the comparison; a state built without a server has none and is false.
+    daemon_stale: Boolean(state.daemonStale?.()),
     counts: {
       agents: inv.agents.length,
       skills: inv.skills.length,

package/js/web/daemon.mjs

@@ -13,6 +13,7 @@ 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 { createHash } from 'node:crypto';
 import { chmodSync, mkdirSync, openSync, readFileSync, unlinkSync } from 'node:fs';
 import { join, resolve as pathResolve } from 'node:path';
 
@@ -20,6 +21,29 @@ const ROOT = pathResolve(import.meta.dirname, '..', '..');
 
 // ---- the daemon record -----------------------------------------------------
 
+/**
+ * Which code a console serves: the package version and a hash of the `web/dist/index.html` it
+ * would load. A daemon writes the stamp it started with into its record; an npm upgrade or a
+ * `git pull` that replaces `web/dist/` changes the stamp on disk, and the daemon — still
+ * serving the old `index.html`, whose chunk hashes may no longer exist — is then STALE.
+ * Read fresh on every call: the comparison is against the files as they are NOW.
+ */
+export function codeStamp(root = ROOT) {
+  const read = (rel) => { try { return readFileSync(join(root, rel)); } catch { return ''; } };
+  let version = 'unknown';
+  try { version = JSON.parse(read('package.json')).version ?? version; } catch { /* unknown */ }
+  const html = createHash('sha256').update(read(join('web', 'dist', 'index.html'))).digest('hex');
+  return `${version}:${html.slice(0, 12)}`;
+}
+
+/** A record written by an older daemon carries no `code` — and is stale by definition. */
+export function daemonStale(record, root = ROOT) {
+  return record?.code !== codeStamp(root);
+}
+
+export const STALE_LINE = '[web] running OLD code (started before the last upgrade) — '
+  + 'geneseed web restart';
+
 const statePath = (target) => join(target, '.geneseed-web.json');
 
 export function readDaemon(target) {
@@ -268,6 +292,7 @@ export async function statusDaemon(theme = null) {
   const st = await liveDaemon(target);
   if (st) {
     printOut(`[web] running on ${st.url}  (theme: ${none(st.theme)}, pid ${none(st.pid)})\n`);
+    if (daemonStale(st)) printOut(`${STALE_LINE}\n`);
     return 0;
   }
   // EXIT 1, which is the verb's whole contract for a script. The snapshot's `<exit>`
@@ -276,6 +301,33 @@ export async function statusDaemon(theme = null) {
   return 1;
 }
 
+/**
+ * Bounce a running console so it serves the code now on disk — `upgrade` after it rebuilt,
+ * `rebuild-all` when the running one is stale. EXCEPT inside a web job (`GENESEED_WEB_JOB`,
+ * set by `js/web/jobs.mjs`): restarting here would kill the process tracking that very job,
+ * leaving the console stuck on 'running'; the server restarts itself after an update job, and
+ * shows its stale banner otherwise. `onlyIfStale` is `rebuild-all`'s: after an `upgrade`
+ * (which bounces, then runs `rebuild-all`) the console is current, and bouncing it again
+ * would drop the open tab for nothing. Never throws — no rebuild fails over a console.
+ */
+export async function bounceDaemonIfRunning(theme, log, { onlyIfStale = false } = {}) {
+  if (onlyIfStale) {
+    const st = readDaemon(webState(theme).target);
+    if (!st || !daemonStale(st)) return;
+  }
+  if (process.env.GENESEED_WEB_JOB) {
+    log(onlyIfStale
+      ? '[geneseed] the web console is running old code — use its Restart banner.'
+      : '[geneseed] web daemon will restart itself after this job to load the new code.');
+    return;
+  }
+  try {
+    await restartDaemon(theme, 4747, false, true);
+  } catch (e) {
+    log(`[geneseed] ⚠️  could not refresh the web daemon (${e && e.message ? e.message : e}) — \`geneseed web restart\` manually if it was running.`);
+  }
+}
+
 export async function restartDaemon(theme = null, port = 4747, openBrowser = true,
   onlyIfRunning = false) {
   const { target } = webState(theme);