geneseed 4.16.0 → 4.17.1

package/CHANGELOG.md

@@ -8,6 +8,30 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [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.
+
+### Changed
+- **The web console's Update button follows the install.** On a clone it runs `upgrade`, as before. On a global npm install it now runs `npm install -g geneseed@latest` and then the new package's `rebuild-all`, where it used to fail with "not a git checkout". On any other copy (an npx cache, a project's `node_modules`, an unzipped folder) it shows the command to run instead of a button. A clone also says whether there is anything to pull ("3 commits to pull", "up to date") from a daily background `git fetch`. An Overview page left open asks again every hour and when its tab comes back into view, so it shows a new release within a day.
+
+## [4.17.0] — 2026-10-23
+
+Minor: doctrine comms 5 Mark the Ask; a version bump on main now releases itself; two Bob fixes.
+
+### Upgrade notes
+- Run `geneseed rebuild-all`; nothing changes on a machine until something re-emits.
+
+### Added
+- **Doctrine comms 5, Mark the Ask.** When a reply stops and waits on the user (a question, a choice, an approval, a blocker), the agent marks the ask so a reader who skims finds it first: one leading emoji marker for its kind (`❓` question, `👉` act to do, `⚠️` risk or blocker, `✅` done, waits on sign-off), placed before the reference code (`❓ **Q3** — keep the v1 route?`), arrows (`→`) for options and flows with the recommended option first, and one ask per block. Colour is used only where the host renders it, never as raw ANSI in plain text. Routine output stays plain, and the prose around a marker keeps Simplified Technical English. It is in the toggleable comms pack, not a law, per DESIGN.md Decision 7: `--exclude-rules "comms 5"` turns it off. The carrier ceilings rise by 1 114 characters (full) and 512 (lean). Run `geneseed rebuild-all` to get it.
+
+### Changed
+- **The version bump is the release.** `publish.yml` now also runs when CI finishes green on a push to `main`. If the version in `harness.config.json` is not on npm yet, it re-runs its gates against the commit CI tested, publishes it, and creates the `v<version>` tag and the GitHub release from that version's CHANGELOG section; otherwise it stops after one cheap check. A PR's CI run, a red one or a fork's never publishes. The manual dispatch stays, still a dry run by default.
+
+### Fixed
+- Bob: a gate block no longer promises a confirmation Bob cannot give. Bob has no ask tier, so "Confirm this specific command" sent the model round the gate (a retry with `-Confirm:$false`, then `git clean`) and finally to "disable the Geneseed hook". Every Bob block now says that nothing in the chat lifts it, and that the user can act outside Bob. Claude's wording is unchanged.
+- Bob: read-only agents now stay read-only. Bob ignores Claude's `disallowedTools`, so every reviewer, explorer and council seat got Bob's default `read, edit, execute`. The Bob emit now writes Bob's own `groups:` key (`read`, plus `execute` for an agent that opts into bash). An `agent-overrides.json` value is not applied on Bob and a warning says so: Bob drops an agent that carries `model:`. Run `geneseed rebuild-all`.
+
 ## [4.16.0] — 2026-10-23
 
 Minor: foreman mode now really delegates, and the web console updates and rebuilds a clone without a manual restart.

package/README.md

@@ -13,7 +13,7 @@
 [![Themes](https://img.shields.io/badge/themes-14-9cf)](themes/)
 [![Skills](https://img.shields.io/badge/skills-47-blueviolet)](src/skills/)
 [![Agents](https://img.shields.io/badge/agents-20-orange)](src/agents/)
-[![Laws and doctrines](https://img.shields.io/badge/laws-9%20%2B%2030%20doctrines-critical)](src/doctrines/)
+[![Laws and doctrines](https://img.shields.io/badge/laws-9%20%2B%2031%20doctrines-critical)](src/doctrines/)
 [![Plugins](https://img.shields.io/badge/plugins-7-teal)](adapters/opencode/plugins/)
 [![OpenCode · Claude Code · Bob · OpenClaude · AGENT.md](https://img.shields.io/badge/works%20with-OpenCode%20·%20Claude%20Code%20·%20Bob%20·%20OpenClaude%20·%20AGENT.md-1f6feb)](#-supported-harnesses)
 
@@ -294,7 +294,7 @@ Geneseed/
 │                         Docs pages; maintainer notes beside them (extending, design-history…);
 │                         specs/, reviews/, superpowers/ are local working docs — git-ignored
 ├── adapters/             per-host glue (opencode/, claude-code/, bob/, openclaude/)
-└── .github/workflows/    ci.yml (doctor + tests) · publish.yml (npm, OIDC, manual only)
+└── .github/workflows/    ci.yml (doctor + tests) · publish.yml (npm, OIDC, on a version bump)
 ```
 
 ## 🧪 Validate & test
@@ -304,7 +304,7 @@ node bin/geneseed-cli.mjs doctor      # every theme + parity + authoring + drift
 node --test --test-reporter=tap "tests/**/*.test.mjs"   # the suites (node expands the glob)
 ```
 
-`doctor` checks each theme for unresolved tokens, dead/non-hermetic links, theme-key parity, author-time gates (every spec has a purpose line, the plugins parse, the learn-prompt literal stays extractable), and that a committed bundle still matches a fresh render of `src/`. CI (`.github/workflows/ci.yml`) runs both on every push and PR, on both Linux and Windows. Publishing is a separate, manually-triggered workflow (`.github/workflows/publish.yml`) — see [Contributing](#-contributing).
+`doctor` checks each theme for unresolved tokens, dead/non-hermetic links, theme-key parity, author-time gates (every spec has a purpose line, the plugins parse, the learn-prompt literal stays extractable), and that a committed bundle still matches a fresh render of `src/`. CI (`.github/workflows/ci.yml`) runs both on every push and PR, on both Linux and Windows. Publishing is a separate workflow (`.github/workflows/publish.yml`) that runs when CI finishes green on `main` and releases only a version npm does not have yet — see [Contributing](#-contributing).
 
 ### AI Harness Scorecard
 
@@ -365,7 +365,7 @@ Three things that bite when you don't know them:
 
 - **`js/cli-table.json` IS the CLI.** The argument parser is data, and that file is the owned document — not a generated one. `bin/geneseed-cli.mjs` cannot parse a single verb without it, `bin/geneseed-hook.mjs` renders `--help` from it, and the console's `cli` docs page is a filtered view of it. What holds it honest is `tests/unit/cli_table.test.mjs` — change a flag here and that suite is what tells you.
 - **The version has one owner: `harness.config.json`.** `package.json` mirrors it and a test fails the fork. Never `npm version` — it edits one of the two.
-- **Publishing is deliberate and manual.** `.github/workflows/publish.yml` uses npm trusted publishing (OIDC); there is no `NPM_TOKEN` in this repository and there must not be one. It runs only from Actions → publish → Run workflow, and the npm-side trusted publisher is keyed on that workflow's **filename** — renaming the file breaks publishing with no local symptom, which is why the file names itself in its own header and a test asserts the two agree.
+- **The version bump is the release.** `.github/workflows/publish.yml` uses npm trusted publishing (OIDC); there is no `NPM_TOKEN` in this repository and there must not be one. When CI finishes green on a push to `main` and the version in `harness.config.json` is not on npm yet, it publishes that version, then creates the `v<version>` tag and the GitHub release from the CHANGELOG. Actions → publish → Run workflow still works by hand (a dry run by default), and the npm-side trusted publisher is keyed on that workflow's **filename** — renaming the file breaks publishing with no local symptom, which is why the file names itself in its own header and a test asserts the two agree.
 
 ## 🙏 Credits
 

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.16.0**.
+> string. Current label: **4.17.1**.
 
 ## Capabilities
 

package/adapters/bob/README.md

@@ -20,8 +20,11 @@ limitation to be aware of on a shared repo.
   preamble as a delimited **managed block** (your prose around it survives a
   re-emit; the block is replaced, never stacked).
 - **`.bob/`** layer:
-  - `agents/<name>.md` — the **Claude subagent dialect** verbatim (`name` +
-    `description` + a `disallowedTools:` denylist for read-only agents).
+  - `agents/<name>.md` — **Bob's agent dialect**: `name` + `description`, and for a
+    read-only agent a `groups:` list of `read` (plus `execute` when the spec opts into
+    bash). An editing agent states no groups and keeps Bob's default `read, edit, execute`.
+    Bob ignores Claude's `disallowedTools`, and an `agent-overrides.json` value is not
+    applied (Bob refuses a `model:` key).
   - `skills/<name>/SKILL.md` — **byte-identical** to every other host; skills
     are model-invoked via the `skill` tool. The one exception is the folder skills'
     own directory — see *Bob-ism 3*.
@@ -99,7 +102,7 @@ What the global emit writes into `~/.bob/settings/settings.json`:
 | event | verb | how the verdict travels |
 | --- | --- | --- |
 | `SessionStart` | `context --host bob` | plain stdout, as on Claude |
-| `PreToolUse` | `tool-gate --host bob` — one group, no matcher | Laws I/IV, rigor-5 and ops-2: **exit 2**, reason on stderr; process 1/5: a stderr line, exit 0 |
+| `PreToolUse` | `tool-gate --host bob` — one group, no matcher | Laws I/IV, rigor-5 and ops-2: **exit 2**, reason on stderr — it says no chat confirmation lifts the block, since Bob has no ask tier; process 1/5: a stderr line, exit 0 |
 | `Stop` | `learn` | never a verdict |
 
 No matcher on `PreToolUse`, deliberately: Bob's tools page already drifts from its own

package/docs/concepts/enforcement-table.md

@@ -64,7 +64,8 @@ follow them, not because a tool call was ever inspected.
 **Doctrine: rigor** — `idempotent-by-default` · `honest-tests` · `cover-and-verify` ·
 `prove-the-gate`.
 
-**Doctrine: comms** — `codes-that-persist` · `structure-beside-prose` · `declare-the-judgment-calls`.
+**Doctrine: comms** — `codes-that-persist` · `structure-beside-prose` · `declare-the-judgment-calls` ·
+`simplified-technical-english` · `mark-the-ask`.
 
 ---
 

package/docs/extending.md

@@ -856,8 +856,11 @@ gated. Every other appearance is derived at runtime (`.geneseed-version` markers
 why no test pins a version string and none should.
 
 Do not run `npm version`. Bump the two files by hand, add the `CHANGELOG` section, update
-`SHIPPED.md`, rebuild `web/dist` if `web/src` moved, run the seven commands from §1, push, tag,
-then rehearse and fire the workflow:
+`SHIPPED.md`, rebuild `web/dist` if `web/src` moved, run the seven commands from §1, and merge to
+`main`. **The bump is the release** (since 2026-10-23): when CI finishes green on that push,
+`publish.yml` sees a version npm does not have, re-runs its gates, publishes it, and creates the
+`v<version>` tag and the GitHub release from the version's CHANGELOG section. A push that does not
+change the version stops at the `release-check` job. A manual rehearsal still works:
 
 ```bash
 gh workflow run publish.yml -f dry_run=true

package/docs/guides/install-bob.md

@@ -13,7 +13,7 @@ geneseed build --emit bob-global                                   # ~/.bob
 geneseed build --emit bob --out /path/to/repo --root /path/to/repo # one repo
 ```
 
-Bob is shaped like Claude Code, so it gets the same agents and skills. Per repo, the preamble goes into a root `AGENTS.md` and the rest into `.bob/`. Globally, everything goes under `~/.bob` (`$BOB_CONFIG_DIR` moves it), and the preamble rides `rules/geneseed.md`, because Bob does not auto-load a global `AGENTS.md`. Bob's hooks refuse an action with exit code 2, and Bob has no `SubagentStop` or `PreCompact` events.
+Bob is shaped like Claude Code, so it gets the same agents and skills. A read-only agent is limited with Bob's own `groups:` key, because Bob ignores Claude's `disallowedTools`. Per repo, the preamble goes into a root `AGENTS.md` and the rest into `.bob/`. Globally, everything goes under `~/.bob` (`$BOB_CONFIG_DIR` moves it), and the preamble rides `rules/geneseed.md`, because Bob does not auto-load a global `AGENTS.md`. Bob's hooks refuse an action with exit code 2, and Bob has no `SubagentStop` or `PreCompact` events.
 
 Both scopes open Bob's carrier with a short first-reply override, so the theme's readiness line (for example "🧬 Gene-seed implanted…") starts the first reply. Without it, Bob's own greeting outranked the instruction lower in the file. A bare greeting such as "hi" still gets Bob's fixed welcome; the line appears on the first real request. That much was checked by hand in the Bob IDE (2026-10); the rest of the Bob support has not been verified against a live install.
 

package/docs/guides/upgrade.md

@@ -34,7 +34,23 @@ geneseed upgrade imperial     # the same, switching the theme
 
 A dirty working tree, or a folder that is not a git clone, is reported rather than force-updated. `update` and `sync-self` are aliases of `upgrade`. `bootstrap` does the same and then opens the setup wizard (`--no-setup` skips the wizard).
 
-In the web console, the **Update** button on the Overview runs `upgrade`. On a clone it is always there, also when the release check cannot reach npm, because `main` moves between releases. When the update is done, the console restarts and the page reloads. If you ran `git pull` yourself, the Overview shows a banner that the console runs old code. Click **Rebuild** on an install that is behind: the console restarts after the rebuild and reloads the page. If no install is behind, click **Restart** in the banner.
+## The Update button in the web console
+
+The **Update** button on the Overview picks its route from how this copy of Geneseed is installed:
+
+| Install | What **Update** runs | When the button shows |
+|---|---|---|
+| A clone (or a worktree) | `geneseed upgrade` | Always, because `main` moves between releases. |
+| A global npm install (`npm root -g`/geneseed) | `npm install -g geneseed@latest`, then `geneseed rebuild-all` from the new package | When npm has a newer release. |
+| Anything else (an npx cache, a project's `node_modules`, an unzipped copy) | Nothing. The Overview shows the command to run instead. | Never. |
+
+On a clone, the Overview also says whether there is anything to pull. Once a day the console runs `git fetch` in the background and counts the commits upstream has that the clone does not: "3 commits to pull", or "up to date". The fetch has the same timeout as `upgrade` (`GENESEED_NET_TIMEOUT`, 120 s by default). If the fetch fails, the Overview shows the release check instead, and the button stays. `GENESEED_NO_UPDATE_CHECK` turns off both the npm check and the fetch.
+
+The console asks npm for the latest release once a day. An Overview page that stays open asks the console again every hour, and each time you come back to its tab, so it shows a new release within a day.
+
+The npm route never uses `sudo` and never retries. If npm refuses (no permission on the global folder, a proxy, a private registry), the job log shows npm's own output. Fix the cause, or run the two commands yourself.
+
+When the update is done, the console restarts and the page reloads. If you ran `git pull` yourself, the Overview shows a banner that the console runs old code. Click **Rebuild** on an install that is behind: the console restarts after the rebuild and reloads the page. If no install is behind, click **Restart** in the banner.
 
 ## What an upgrade keeps
 

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.16.0"
+  "version": "4.17.1"
 }

package/js/hosts/hooks.mjs

@@ -196,6 +196,20 @@ const setHost = (args) => { HOST = (args && args.host) || 'claude'; };
  */
 const BOB_DENY_EXIT = 2;
 
+/**
+ * Said after every Bob block. Exit 2 is final on Bob — no ask tier, and consent typed in the
+ * chat never reaches the hook — so a reason that invites a confirmation sends the model looking
+ * for a way round: live (2026-10-23) it retried with `-Confirm:$false`, then `git clean`, then
+ * told the user to disable the Geneseed hook. This names the one real way out instead.
+ */
+const BOB_FINAL = ' Bob has no approval step for this gate: neither a confirmation in the chat '
+  + 'nor a retry in another form lifts it. Leave it, or ask the user to do it themself, outside '
+  + 'Bob. Never suggest disabling the Geneseed hook.';
+
+/** Law IV's real-loss tail, where the host can ask. Bob's is `BOB_FINAL`, appended by `ask`. */
+const confirmTail = () => (HOST === 'bob' ? 'Leave the data in place.'
+  : 'Confirm this specific command, or leave the data in place.');
+
 /**
  * On Bob, which has no ask tier, which rules are worth a hard block. Laws I and IV: a
  * credential in a tracked file and a history-discarding git act are wrong in every context,
@@ -260,7 +274,7 @@ function ask(args, verb, rule, reason) {
     }
     ledger(args && args.root, verb, rule);
     // stdout is not read on Bob's PreToolUse; the reason goes where Bob's hook log looks.
-    err(`[geneseed] BLOCKED: ${reason}\n`);
+    err(`[geneseed] BLOCKED: ${reason}${BOB_FINAL}\n`);
     return BOB_DENY_EXIT;
   }
   ledger(args && args.root, verb, rule);
@@ -458,7 +472,7 @@ function gitDecide(args, payload) {
       { split: lossSegments });
     if (loss) {
       return ask(args, 'git-gate', 'law-4', `Geneseed (Deletion Is Deliberate) \u2014 ${loss}. `
-        + 'Confirm this specific command, or leave the data in place.');
+        + confirmTail());
     }
   }
   // Before `--no-consent`: that flag drops the process pack's rule, not this one.

package/js/hosts/native.mjs

@@ -376,6 +376,24 @@ function claudeAgentFrontmatter(stem, text, overrides) {
   return fm;
 }
 
+/**
+ * Bob's agent dialect, read from its 2.2.3 runtime (`bob-code/dist/extension.js`; Bob's persona
+ * docs pages 404). Bob ignores Claude's `disallowedTools`, so the Claude dialect left every
+ * read-only agent with Bob's default groups `read, edit, execute` (live review 2026-10-23, F2).
+ * An ALLOWLIST of capability groups rather than a `denyTools` list of tool names: a tool Bob adds
+ * to the edit group later is shut without an emit change. `browser`/`mcp` stay out for every
+ * read-only agent, the webfetch marker included — which group holds Bob's web fetch is unverified.
+ * No `model:`: Bob throws on the key and drops the agent silently (`warnBobIgnored` says so).
+ */
+function bobAgentFrontmatter(stem, text) {
+  const fm = [`name: ${stem}`, `description: ${jsonDumps(agentDescription(text))}`];
+  if (isReadonly(text)) {
+    fm.push('groups:', '  - read');
+    if (text.includes(BASH_MARKER)) fm.push('  - execute');
+  }
+  return fm;
+}
+
 /** `_build_emit._opencode_agent_frontmatter`. */
 function opencodeAgentFrontmatter(stem, text, overrides, theme = null) {
   const fm = [`description: ${jsonDumps(agentDescription(text))}`, 'mode: subagent'];
@@ -467,6 +485,19 @@ function warnClaudeIgnored(overrides) {
   }
 }
 
+/** Bob's agents take none of the four override keys — `model:` would even drop the agent. */
+function warnBobIgnored(overrides) {
+  const keys = new Set();
+  for (const entry of Object.values(overrides)) {
+    if (!isDict(entry)) continue;
+    for (const key of OVERRIDE_KEYS) if (key === 'model' ? isTruthy(entry[key]) : given(entry[key])) keys.add(key);
+  }
+  for (const key of keys) {
+    warn(`[geneseed] WARN: agent-overrides.json sets '${key}', which Bob's agents do not `
+      + 'support — it is not applied');
+  }
+}
+
 /**
  * Claim-on-create, as a closure over one emit's prior manifest: `claim(dest)` is true when
  * `dest` may be (over)written, false for a pre-existing file no previous emit owned — the
@@ -568,14 +599,15 @@ export function writeNativeLayer(items, agentsDir, skillsDir, overrides = null,
   // `disable-model-invocation` — and giving it the Claude-dialect alias SKILL.md (the
   // `host === 'claude'` branch below) would be an unverified key PLUS a visible duplicate
   // in the model's catalogue (exactly the OpenCode problem this file already dodges for
-  // aliases). `bobDialect` suppresses both for Bob only, while `host: 'claude'` keeps every
-  // OTHER Claude-dialect choice (agent frontmatter, `warnClaudeIgnored`) — Bob still renders
-  // those verbatim. The caller (`emit-claude.mjs`) routes the suppressed names through
+  // aliases). `bobDialect` suppresses both for Bob only, and gives its agents Bob's own
+  // frontmatter (`bobAgentFrontmatter`) — `host: 'claude'` keeps every OTHER Claude-dialect
+  // choice. The caller (`emit-claude.mjs`) routes the suppressed names through
   // `writeAliasCommands(..., alsoUserOnly: true)` into `.bob/commands/*.md` instead (O2).
   bobDialect = false,
 } = {}) {
   const ov = overrides || {};
-  if (host === 'claude') warnClaudeIgnored(ov);
+  if (bobDialect) warnBobIgnored(ov);
+  else if (host === 'claude') warnClaudeIgnored(ov);
   let nAgents = 0;
   let nSkills = 0;
   const written = [];
@@ -653,8 +685,9 @@ export function writeNativeLayer(items, agentsDir, skillsDir, overrides = null,
     let kind;
     let userOnly = false;
     if (folder === 'agents') {
-      fm = host === 'claude' ? claudeAgentFrontmatter(stem, text, ov)
-        : opencodeAgentFrontmatter(stem, text, ov, theme);
+      if (bobDialect) fm = bobAgentFrontmatter(stem, text);
+      else if (host === 'claude') fm = claudeAgentFrontmatter(stem, text, ov);
+      else fm = opencodeAgentFrontmatter(stem, text, ov, theme);
       dest = path.join(agentsDir, `${stem}.md`);
       kind = 'agent';
     } else {

package/js/inspect/cost.mjs

@@ -35,7 +35,7 @@ import { isFile, readText } from '../lib/fs.mjs';
  * console draws it on the cost chart, so it lives here, once, where both read it. Raise it by
  * exactly the measured overrun and say why in that test's docblock, which keeps its history.
  */
-export const CARRIER_CEILING = { full: 63_299, lean: 39_661 };
+export const CARRIER_CEILING = { full: 64_413, lean: 40_173 };
 
 /**
  * A frontmatter value as the host shows it. The emit writes descriptions JSON-escaped

package/js/web/api.mjs

@@ -8,7 +8,7 @@
  * bind paths to these functions are `routes.mjs`. This file imports none of its route siblings,
  * which is what keeps the old `api ↔ actions` and `api ↔ activity` cycles from coming back.
  */
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 
 import { CONFIG, CREDIT_RE, ROOT, SRC, THEMES, discoverNames, loadKits, makeCfg, upstreamOf } from '../build/source.mjs';
@@ -35,7 +35,7 @@ import {
   configItems, deployed, dget, memoryItems, notebookItems, wikiItems,
 } from './catalog.mjs';
 import { stampMinute, viewCfg } from './state.mjs';
-import { updateStatus } from './update-check.mjs';
+import { MANUAL_UPDATE, gitBehind, installKind, updateStatus } from './update-check.mjs';
 
 /**
  * `js/web/docs.mjs` imports these three from HERE, and that file is outside this split — so
@@ -499,12 +499,26 @@ export function apiLoopsActive() {
   return { loops: activeLoops() };
 }
 
-/** Is a newer release on npm than the source this console serves? See update-check.mjs. */
-// `git`: a clone updates by `git pull` whatever npm says — main moves between releases, and a
-// work proxy can leave the release check unanswered — so the console always offers Update there.
-// `.git` is a file in a worktree, a folder in a clone; existence covers both.
-export const apiUpdate = (state) => ({ ...updateStatus(state, releaseLabel()),
-  git: existsSync(path.join(ROOT, '.git')) });
+/**
+ * Is a newer release on npm than the source this console serves, and how would this copy take
+ * it? See update-check.mjs.
+ *
+ * `install` picks the Update route (`git`, `npm-global`, `other`); `git` is kept beside it for a
+ * console bundle older than the field. `behind` is a clone's own "up to date": commits upstream
+ * holds that it does not, null when unknown — a clone can always pull, since `main` moves between
+ * releases and a work proxy can leave the release check unanswered. `command` is what to run by
+ * hand when the console cannot update this copy itself.
+ */
+export function apiUpdate(state) {
+  const install = installKind();
+  return {
+    ...updateStatus(state, releaseLabel()),
+    install,
+    git: install === 'git',
+    behind: install === 'git' ? gitBehind(state, { busy: Boolean(state.jobBusy?.()) }) : null,
+    command: install === 'other' ? MANUAL_UPDATE : null,
+  };
+}
 
 /** The source's release label, or null when it cannot be read. */
 function releaseLabel() {

package/js/web/handler.mjs

@@ -13,13 +13,13 @@
 import { resolvePath } from '../hosts/hosts.mjs';
 import { isTruthy, jsonDumpsCompact } from '../lib/json.mjs';
 import { parseIntStrict, percentDecode } from '../lib/text.mjs';
-import { preflight } from '../maintain/update.mjs';
 import { apiDeployCmd, apiInstallCmd, apiPickFolder, apiRestore, buildActionCmds, mcpTargetPaths } from './actions.mjs';
 import { NotFound } from './catalog.mjs';
 import { openUrl, requestRestart } from './daemon.mjs';
 import { apiDocs, apiDocsPage } from './docs.mjs';
-import { actionCommands } from './jobs.mjs';
+import { actionCommands, updatePlan } from './jobs.mjs';
 import { POST_ROUTES, PREFIX_ROUTES, STATE_ROUTES, readJsonBody } from './routes.mjs';
+import { installKind } from './update-check.mjs';
 import { isFile } from '../lib/fs.mjs';
 import { readFileSync, statSync } from 'node:fs';
 import { basename, dirname, extname, join, sep } from 'node:path';
@@ -287,16 +287,26 @@ export function makeHandler(state, jm, token, dist, holder = null) {
       return startJob(res, 'deploy', [plan.cmd], ae);
     }
     if (action === 'update') {
-      const pre = preflight();
-      if (!pre.ok) {
-        return sendJson(res,
-          { precondition: pre.code, kind: pre.kind, message: pre.message }, 422, ae);
+      // The route follows the install (`updatePlan`); a refusal is the same friendly 422.
+      // The daily background `git fetch` still running would hold `.git` locks the update's own
+      // fetch needs, and fail it as `fetch_failed`; it ends within GENESEED_NET_TIMEOUT.
+      if (state._behind?.inflight) {
+        return sendJson(res, { precondition: 'checking', kind: 'info',
+          message: 'The console is checking upstream right now. Try Update again in a moment.' },
+        422, ae);
       }
+      const plan = updatePlan(installKind());
+      if (plan.refuse) return sendJson(res, plan.refuse, 422, ae);
       // `requestRestart` declines on a foreground server, which then shows its stale banner.
-      const jid = jm.start('update', actionCommands('update'), (rc) => {
+      const jid = jm.start('update', plan.cmds, (rc) => {
         state.refresh();
-        if (rc === 0) requestRestart(state.theme);
-      });
+        if (rc === 0) {
+          // The old answers ("3 commits to pull") are about the code just replaced.
+          delete state._behind;
+          delete state._update;
+          requestRestart(state.theme);
+        }
+      }, plan.opts);
       if (jid === null) return sendJson(res, { error: 'busy' }, 409, ae);
       return sendJson(res, { job_id: jid }, 202, ae);
     }

package/js/web/jobs.mjs

@@ -84,6 +84,7 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { StringDecoder } from 'node:string_decoder';
+import { homedir } from 'node:os';
 import path from 'node:path';
 
 import { ROOT, PACK_ORDER } from '../build/source.mjs';
@@ -93,6 +94,8 @@ import { isDict } from '../hosts/mcp.mjs';
 import { readText, writeText, isFile } from '../lib/fs.mjs';
 import { which } from '../lib/paths.mjs';
 import { jsonDumpsCompact, parseJson, isTruthy } from '../lib/json.mjs';
+import { preflight } from '../maintain/update.mjs';
+import { MANUAL_UPDATE } from './update-check.mjs';
 
 /**
  * Terminate a job's WHOLE process tree.
@@ -255,9 +258,11 @@ export class JobManager {
 
   /**
    * `cmds` is a LIST OF ARGVS, run in order, stopping at the first failure. `null` when a
-   * job is already running, which the HTTP layer maps to 409.
+   * job is already running, which the HTTP layer maps to 409. `cwd` defaults to this checkout;
+   * the npm update passes another, since npm cannot replace a folder a child sits in on Windows.
+   * `winShell` is the npm update's too, and only its: see `_run`.
    */
-  start(action, cmds, onDone = null) {
+  start(action, cmds, onDone = null, { cwd = ROOT, winShell = false } = {}) {
     if (this._busy) return null;
     this._busy = true;
     const jid = randomBytes(8).toString('hex');
@@ -272,7 +277,7 @@ export class JobManager {
     });
     // Hand the work to the scheduler and return the id NOW, so the 202 goes out before the
     // child has produced a byte.
-    void this._run(jid, cmds, onDone);
+    void this._run(jid, cmds, onDone, cwd, winShell);
     return jid;
   }
 
@@ -286,15 +291,22 @@ export class JobManager {
     }
   }
 
-  async _run(jid, cmds, onDone = null) {
+  async _run(jid, cmds, onDone = null, cwd = ROOT, winShell = false) {
     let rc = 0;
     let p = null;
     try {
       for (let i = 0; i < cmds.length; i += 1) {
         const cmd = cmds[i];
         this._append(jid, `$ ${cmd.map((c) => String(c)).join(' ')}\n`);
-        p = spawn(cmd[0], cmd.slice(1), {
-          cwd: ROOT,
+        // `npm.cmd` on Windows: Node refuses to spawn a batch file without a shell (the reason
+        // `npmBuild` gives in server.mjs). OPT-IN per job, never sniffed off the argv: only the
+        // npm update asks, and its argv is constants — `install`/`deploy`/`build` carry
+        // body-derived arguments that must never reach cmd.exe.
+        const shell = winShell && process.platform === 'win32'
+          && /\.(cmd|bat)$/i.test(String(cmd[0]));
+        p = spawn(shell ? `"${cmd[0]}"` : cmd[0], cmd.slice(1), {
+          cwd,
+          shell,
           stdio: ['ignore', 'pipe', 'pipe'],
           // No console window for a child of a windowless daemon.
           windowsHide: true,
@@ -457,5 +469,50 @@ export function actionCommands(action, opts = {}) {
   return Object.hasOwn(table, action) ? table[action] : null;
 }
 
+/**
+ * The `update` action on a GLOBAL NPM install, which `upgrade` (a git pull) cannot update:
+ * `npm install -g geneseed@latest`, then the NEW package's `rebuild-all`. `CLI()` IS the new
+ * package: `installKind` only says `npm-global` when ROOT is the folder npm installs into, and the
+ * step is a fresh process started after npm replaced it, so it loads the code npm just wrote.
+ * Outside the table, whose rows are frozen in tests/unit/web_jobs.test.mjs, because its argv
+ * depends on which npm is on this machine.
+ *
+ * No `sudo`, no elevation, no retry: a permission or proxy refusal is npm's own output in the job
+ * log, which is the one place the user can read how to fix it.
+ */
+export function npmUpdateCommands(npm) {
+  return [
+    [npm, 'install', '-g', 'geneseed@latest'],
+    [NODE(), CLI(), 'rebuild-all'],
+  ];
+}
+
+/**
+ * The Update button's job for an install kind (`installKind`, update-check.mjs): `{ cmds, opts }`
+ * to start, or `{ refuse }`, the 422 body the console shows as an info popup.
+ *
+ * THE KIND IS READ BEFORE `preflight`, which asks git and answers `not_git` for every copy that
+ * is not a clone, an npm install included. An `other` copy is told what to run instead: `upgrade`
+ * there would `git pull` whatever repository the copy happens to sit inside. The npm job runs in
+ * the home folder, not ROOT: on Windows npm cannot replace a folder a child's cwd is in.
+ * The dependencies are injectable for the tests, which must not spawn git or npm.
+ */
+export function updatePlan(install, {
+  pre = preflight, npm = () => which('npm'), home = homedir,
+} = {}) {
+  if (install === 'git') {
+    const p = pre();
+    if (!p.ok) return { refuse: { precondition: p.code, kind: p.kind, message: p.message } };
+    return { cmds: actionCommands('update'), opts: undefined };
+  }
+  const exe = install === 'npm-global' ? npm() : null;
+  if (!exe) {
+    return { refuse: { precondition: 'manual', kind: 'info',
+      message: `The console cannot update this copy. Run \`${MANUAL_UPDATE}\` for a global npm `
+        + 'install, or `git pull` in a clone.' } };
+  }
+  return { cmds: npmUpdateCommands(exe), opts: { cwd: home(), winShell: true } };
+}
+
 /** `actionTable`'s own keys — the table IS the declaration, so this cannot drift from it. */
 export const PORTED_ACTIONS = Object.keys(actionTable());

package/js/web/server.mjs

@@ -150,6 +150,8 @@ export async function serve({ theme = null, port = 4747, openBrowser = true,
   // 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(home, '.geneseed-web-runs.json'));
+  // Read by `/api/update`, whose background `git fetch` must not race a running update's pull.
+  state.jobBusy = () => jm.busy;
   const srv = createServer(makeHandler(state, jm, token, dist, holder));
   holder.srv = srv;
   return new Promise((done) => {