@bongos/core 1.19.1079 → 1.19.1080

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.1079",
-  "core_contract": "1.19.1079",
-  "source_commit": "0383ae383a565f9a6b3c9cef65e5db1a25fda1b8",
+  "core_version": "1.19.1080",
+  "core_contract": "1.19.1080",
+  "source_commit": "266542d6d4b7b351e1b5e52e624d6429f20e4a3e",
   "source_ref": "HEAD",
-  "built_at": "2026-09-29T17:08:08.029Z",
+  "built_at": "2026-09-29T22:14:01.252Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 550,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2534,
+    "functional_verbatim": 2535,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3110,
-  "tree_sha256": "09c2966aeb5069bc3a6d9f1f306e4d993ec3f09da7b4136e4cab9b93e0f3e690",
+  "file_count": 3111,
+  "tree_sha256": "05cc1fdd03c698fc64c21d2c5b4c72150f293acda99233129517b7954d4dfda8",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2217,7 +2217,7 @@
     {
       "path": "docs/architecture.md",
       "mode": "0000644",
-      "sha256": "cb0de2130b810b17ba5b79cc52a6bf4594e84d9aa2d88405be7dd96f66e3cf06"
+      "sha256": "5e4d7c92368a07d0f363c7b6cd4db3ba9ed2c7baba3ecad66537baf3b9786b80"
     },
     {
       "path": "docs/branding-contract.md",
@@ -2742,12 +2742,12 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "cd8f1a1404e5c2fc789d2efa06eb513c165de83c6c9af94350ec8fbaf90a897a"
+      "sha256": "f6df65117a87e0af4721f2872bba4ee9f7ab4a01a8ae8b76d38206cad08bf712"
     },
     {
       "path": "docs/modules-contract.md",
       "mode": "0000644",
-      "sha256": "31b76c94f9c9703249328a9faa71a87e79e644c41ba41acb7c7209135ccbcb21"
+      "sha256": "a3969a4cdc2bdbb14a0a5ece7a16d8f280703eef2376ff9a49a3030f9f353160"
     },
     {
       "path": "docs/onboarding/diagrams/01-task-lifecycle.mmd",
@@ -8602,12 +8602,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b94499c149cab0d2b61e2c16da48bdc29e750538aa9c60363cf4d4cc0511b145"
+      "sha256": "4187718df5a94313b87e2871b5c296229ea1a92dabe2c75275f05e3174539c74"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "fc349b40ca4dc25724895e0982b5b689b4ed60e44b1eb567ffc1bbd620977ed9"
+      "sha256": "4307d22a2cadfdbbd821db8058f22dc4b74f47864b5d405a8b6efca3fd842158"
     },
     {
       "path": "public-docs/index.html",
@@ -8627,7 +8627,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "5a79e67ac4a575bc5d0f4a1d8b2e38e4adc746bacaac066d02cea4698e39d79b"
+      "sha256": "e987059aae853c4e12e0890a050c9d8b1f81d2254060d5ea714378ec60b2193e"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -9457,7 +9457,7 @@
     {
       "path": "scripts/gds/module.js",
       "mode": "0000644",
-      "sha256": "eccf6ccfa68342268d8d63ebde68af4402ff3c6cfcecec2262656801e24bf263"
+      "sha256": "2bb8d87422e2b24db1ea9fa0c51556b09a7bea99da5af7ad3798c3b386809f4b"
     },
     {
       "path": "scripts/gds/newcomer-floor.config.json",
@@ -10702,7 +10702,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b65c0562481a90446f4881d84eeda91c28949f216835e6a0bab6105755403932"
+      "sha256": "5f4628ecd7603c1275a4ea0efcdef38540130eb9dfdb6eb0d37dbd28fe675663"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13614,6 +13614,11 @@
       "mode": "0000644",
       "sha256": "0db12d802203780f489e9a6d7abf970dfcde9099ac7011fcaaa6c575336804cd"
     },
+    {
+      "path": "tests/module_update.mjs",
+      "mode": "0000644",
+      "sha256": "1b50c9f68bfe731b29ddcce6947847b6e6f3f7bc5b0a08bbacc4afb25d5a3d90"
+    },
     {
       "path": "tests/modules.mjs",
       "mode": "0000644",

package/docs/architecture.md

@@ -261,7 +261,7 @@ Bongos views: `claimable_tasks` (rebuilt in 006 to use SELECT t.*; rebuilt again
 - Authenticated CLI/web: `GET /me` (returns `rank`), `GET /versions[/progress]`, `GET /tasks[?version=&status=&kind=&discipline=]`, `GET /tasks/claimable[?version=&discipline=]`, `GET /tasks/:id`, `POST /tasks` (accepts `discipline` + `criterion_ids`; **metic+** — [ADR 0090](adr/0090-metic-task-authoring.md)), `PATCH /tasks/:id` (supports `parent_task_id`, `kind`, `discipline`, `goal_id` — (re)assign the task's goal; must be a goal in the task's own version, task 1763; **metic+**), `POST /tasks/:id/promote` (**metic+**), `POST /claims`, `POST /claims/:id/resolve`, `POST /cost`.
 - Criterion rollup + task↔criterion links ([ADR 0025](adr/0025-structured-criterion-task-link.md), [#435](https://example.com/builders#/task/435)/[#438](https://example.com/builders#/task/438)): `GET /versions/:id/progress` rolls up each done-when criterion → its gating tasks (via `task_criteria`) → live status counts + the not-yet-shipped `remaining[]` + `unattributed_tasks` (the read behind the `/status` skill, in `src/bongos/done-when.js criterionProgress`). The link CRUD mirrors the dependency endpoints: `GET /tasks/:id/criteria`, `POST /tasks/:id/criteria` (**metic+** — [ADR 0090](adr/0090-metic-task-authoring.md)) and `DELETE /tasks/:id/criteria/:criterionId` (**metic+**). A criterion ref is a numeric `done_when_criteria.id`, a positional `"Cn"` token, or a `criterion_id` slug, resolved against the task's version (`POST /tasks` links at create time so `/status` counts the task with no backfill).
 - Module store publish (ADR 0338 D1, task 1004271): `POST /store/modules/:key/versions` (`requireBuilder` + `requirePermission('module.submit')`, Metic floor). The body is the raw gzip tarball `bongos module publish` builds (own `express.raw` parser, 5 MB cap; 16 MB / 2000 files unpacked). `scripts/gds/module-artifact.js` re-verifies every hash and the publish gate, then `src/bongos/module-store.js` keeps the file under `var/module-store/` and inserts the `store_module_versions` row in one transaction. The first publish makes the caller the author; later versions are author-only, newer than the last and never overwritten; a delisted key takes none.
-- Module store install (ADR 0338 D1, task 1003785), all `requireBuilder` and own-scoped (the holder is the caller): `POST /store/modules/:key/acquire` (`{version?}`; grants a free entitlement — no price row, or a zero price, is free — or `402 payment_required` for a priced module; refuses a delisted one), `GET /store/modules/:key/versions/:version/tarball` (served only to a live entitlement holder; `X-Tarball-Sha256`), `POST /store/modules/:key/acquired` (`{version}` → `recordAcquired`). Read side in `src/bongos/module-store.js` (`resolveAcquirable`, `isFreePrice`, `versionArtifactFile`). No channel check yet (tasks 1003815, 1003805).
+- Module store install (ADR 0338 D1, task 1003785), all `requireBuilder` and own-scoped (the holder is the caller): `POST /store/modules/:key/acquire` (`{version?}`; grants a free entitlement — no price row, or a zero price, is free — or `402 payment_required` for a priced module; refuses a delisted one), `GET /store/modules/:key/versions/:version/tarball` (served only to a live entitlement holder; `X-Tarball-Sha256`), `POST /store/modules/:key/acquired` (`{version}` → `recordAcquired`). Read side in `src/bongos/module-store.js` (`resolveAcquirable`, `isFreePrice`, `versionArtifactFile`). No channel check yet (tasks 1003815, 1003805). `bongos module update` (task 1003786) reuses the same three calls; the acquire route reads price only for a caller with no entitlement, so a holder is never charged again.
 - Server-mediated branch publish (ADR 0055 / [#1025](https://example.com/builders#/task/1025) — lets a checkout with no GitHub push credential ship). Owner-gated like ship: `POST /tasks/:id/publish-branch` (`requireBuilder` + `gateTaskOwnership`; own 32 MB json parser for the base64 thin-bundle body, 20 MB decoded cap; the server pushes the branch + opens the PR + auto-merges with a server-side push credential — a **GitHub App** installation token (short-lived, repo-scoped; preferred, [ADR 0055](adr/0055-server-mediated-branch-publish.md) update / task 1028) or the `GITHUB_PUSH_TOKEN` PAT fallback; `503 push_unconfigured` when neither is set; `400 tip_mismatch` if the bundle tip ≠ the claimed `head_sha`) and `GET /tasks/:id/publish-status?branch=…` (polls PR + deploy-prod state derived live from GitHub). `branch` is optional: without it the server finds the task's own PR by its `task <id>: …` title, and the answer names the `branch` it used and its `branch_source` (`query` / `task_pr`, or `null` with a `branch_hint` when there is no such PR) — never a `400` (task 1003764). When the PR is still open it also carries `merge_driver`, whose `reason` says why it has not merged; on a red PR `failing_tests` names the failing unit tests (read from the `unit-report` commit status the `unit` workflow posts) and `checks_unreadable: true` says the check list is blind because the App lacks `Checks: read` — so an empty `checks[]` is never read as "nothing failed" (task 1003988, ADR 0301). Because the server's credential is the PR's AUTHOR, publish also **assigns the PR to the task's claim holder** and names them in the body (`modules/lifecycle/pr-assign.js`, task 1003991) — best-effort: the 201 carries `pr_assignee` (the login, or `null` when GitHub would not assign it) and a failed assignment never fails the publish. `ship.js` uses these in `ci` mode only when `pushVia()` resolves to server (no authenticated `gh` on the machine, or `<PREFIX>_PUSH_VIA_SERVER=1`); a machine with `gh` keeps the local push path unchanged. Implementation in `src/bongos/github-push.js`.
 - Archon monitoring reads backing the `/watch` page (ADR 0036): `GET /builders/roster`, `GET /grades/by-builder[?days=N]` (**archon-only**, [#726](https://example.com/builders#/task/726) — per-builder grade breakdown for the MARKS section; the project-wide aggregate stays public at `/public/grades`), `GET /audit-log`, `GET /override-requests`, `GET /access-requests`, `GET /security/reports`. Personal-prefs writes backing `/settings`: `GET/PATCH /me/skill-prefs`, `PATCH /me/disciplines`.
 - Per-builder "needs" + own Gemini key ([ADR 0073](adr/0073-builder-needs-signal-and-byok-gemini-key.md), [#1013](https://example.com/builders#/task/1013)): `GET /me` now also carries `needs` ({items, action_needed_count} — the consistent "the system needs an input from you" signal; `modules/builder-settings/builder-needs.js` is the SSOT — carved out in BV1.R80, resolved by `GET /me` via the `builder-settings` kernel port — rendered by the hall Standing card + the CLI `printNeedsNudge`). The own-key (pragmatic BYOK) endpoints, all own-scoped: `GET /me/art-key/own` (masked meta — last4 only), `PUT /me/art-key/own` (validate-on-save via a Google list-models call → encrypt with `src/bongos/secret-box.js` → store; `503 storage_not_configured` until `BUILDER_SECRET_KEY` is set, `422 invalid_key` on a bad key), `DELETE /me/art-key/own`. The existing `GET /me/art-key` (shared-key delivery) is extended to also deliver the decrypted own key, which `scripts/gds/fetch-art-key.js` syncs into the local `gemini_api_key` slot (own key wins in the `gen_api.py` cascade).

package/docs/module-api-changelog.md

@@ -2649,5 +2649,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.1077 with no explicit bump. run 36600137276. (task 1002620)
   1.19.1079 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.1078 with no explicit bump. run 36602720244. (task 1002620)
+  1.19.1080 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1079 with no explicit bump. run 36638268217. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/modules-contract.md

@@ -364,9 +364,15 @@ Run `bongos upgrade` to confirm coreVersion compatibility, then `node scripts/gd
 - The download is checked with `verifyModuleArtifact`, the same checker the store runs on publish, and must match the version and hashes the store described. A failed check places nothing.
 - A module with no price, or a zero price, is free and granted on the spot. A priced one answers 402 until buying exists (area 8). An entitlement is kept for good, even if a price is added later (ADR 0338 D2).
 - Install never enables. Switch the module on from the hall's Modules tab.
-- A module already on disk is refused; moving one to a newer version is `update`. A module this core cannot mount is refused before download.
+- A module already on disk, in the instance's `modules/` or bundled with the core, is refused; moving one to a newer version is `update`. A module this core cannot mount is refused before download.
 - A delisted module cannot be acquired or downloaded. Channels are not checked yet: every version is general until the channel tasks land.
 
+`bongos module update <key> [--version X.Y.Z]` moves an installed store module forward through the same three calls, so a paid module and a free one take one identical path, and a module you already hold is never charged again (`tests/module_update.mjs` fails if a price-conditional branch appears).
+
+- With no `--version` it takes the newest, and says "up to date" without downloading when that isn't newer. An older `--version` is refused: update only moves forward.
+- The new version is written beside the old one and swapped in; any failure leaves the installed version in place. Files the new version dropped are gone afterwards.
+- The on/off switch is untouched. A module bundled with the core is refused; it updates with the core (`bongos upgrade`).
+
 ## Carving an existing core domain (the `db.js` per-domain pattern)
 
 Most BONGOS-V1 module work is not scaffolding a *new* module — it's **carving an existing core domain out of the monolith** (ADR 0091, criterion C7). The reference carve is the kernel slice `src/bongos/db-kernel.js` (BV1.R69); the feature precedents are `modules/discord/db.js` + `modules/game/db.js`. Every later carve (memory R72, grading R73, …) copies this recipe. The invariant is **OTB byte-identical** at every step — you are *moving* code, not changing behavior.

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1079",
+  "version": "1.19.1080",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.1079",
+      "version": "1.19.1080",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1079",
+  "version": "1.19.1080",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",
@@ -29,6 +29,6 @@
     "pino": "^9.14.0"
   },
   "overrides": {
-    "undici": "^6.28.0"
+    "undici": "^6.28.1"
   }
 }

package/release-notes.json

@@ -7867,5 +7867,11 @@
       "id": "1003785",
       "text": "You can now install a module from the store with one command. It checks the download is exactly what was published and never switches the module on by itself. Modules without a price are free."
     }
+  ],
+  "1.19.1080": [
+    {
+      "id": "1003786",
+      "text": "Installed modules can now be updated with one command. Paid and free modules update the exact same way, you are never charged twice, and a failed update leaves your working version in place."
+    }
   ]
 }

package/scripts/gds/module.js

@@ -61,6 +61,7 @@
 //   bongos upgrade                     pre-check enabled modules vs the core version
 //   bongos module check <key> [--sign-off "Name <email>"]   AGPL/publish pre-check + DCO sign-off
 //   bongos module install <key> [--version X.Y.Z]   acquire from the store, verify, place (not enabled)
+//   bongos module update <key> [--version X.Y.Z]    move an installed store module forward
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -925,30 +926,104 @@ function placeModule(files, target) {
   }
 }
 
+// Every discovery root the loader scans (core + instance, ADR 0108 §1). A key on
+// disk in ANY of them is already taken: the loader treats a repeated key as a hard
+// error, so placing a second copy in the instance root would break boot.
+function discoveryRoots() {
+  return require('../../src/module-loader/loader').DEFAULT_ROOTS;
+}
+
+// Parse `<key> [--version X.Y.Z]` for install and update. Returns { key, wanted }
+// or { code } (2 = usage) after printing why.
+function parseStoreArgs(args, verb, errlog) {
+  const usage = `usage: bongos module ${verb} <key> [--version X.Y.Z]`;
+  const vIdx = args.indexOf('--version');
+  const wanted = vIdx !== -1 ? args[vIdx + 1] : null;
+  const key = args.find((a, i) => !a.startsWith('-') && args[i - 1] !== '--version');
+  if (!key || (vIdx !== -1 && (!wanted || wanted.startsWith('--')))) { errlog(usage); return { code: 2 }; }
+  if (!KEY_RE.test(key)) { errlog(`REFUSING: "${key}" is not a module key (lowercase kebab-case).`); return { code: 2 }; }
+  const { parseVersion } = require('../../src/module-loader/semver');
+  if (wanted && !parseVersion(wanted)) { errlog(`REFUSING: --version must be exact X.Y.Z, not "${wanted}".`); return { code: 2 }; }
+  return { key, wanted };
+}
+
+// The one acquisition path install AND update share (task 1003786): acquire, check
+// the version can mount on this core, download, verify with verifyModuleArtifact and
+// hold the bytes to what the store described. Nothing here reads a price or branches
+// on how the module was obtained — the store decides entitlement, and a holder it has
+// already granted (for any reason) is never asked again. tests/module_update.mjs
+// fails if a price-conditional branch appears in this path.
+//
+// `shouldDownload(described)` lets update stop before the download when the store's
+// version is not newer than what is installed. Resolves { ok, described, verified }
+// or { ok: false, code, upToDate? } after printing why.
+async function fetchVerified(key, { wanted, call, core, log, errlog, verb, shouldDownload = () => true }) {
+  const fail = (code, msg) => { if (msg) errlog(msg); return { ok: false, code }; };
+  const enc = encodeURIComponent(key);
+  let acq;
+  try { acq = await call('POST', `/store/modules/${enc}/acquire`, { json: wanted ? { version: wanted } : {} }); }
+  catch (e) { return fail(1, `bongos module ${verb}: the store could not be reached — ${e.message}`); }
+  if (!acq.ok) return fail(1, `REFUSING: the store would not hand over "${key}" (HTTP ${acq.status}): ${storeError(acq)}`);
+  const described = acq.data;
+  log(`bongos module ${verb} — "${key}" ${described.version} (needs core ${described.core_version})`);
+
+  const stop = shouldDownload(described);
+  if (stop !== true) return { ok: false, code: stop.code, upToDate: stop.upToDate };
+
+  const { satisfies } = require('../../src/module-loader/semver');
+  const coreV = core || require('../../src/module-api').CORE_VERSION;
+  if (!satisfies(coreV, described.core_version)) {
+    return fail(1, `REFUSING: "${key}" ${described.version} needs core ${described.core_version}; this core is ${coreV}, so it could not mount.`);
+  }
+
+  let dl;
+  try { dl = await call('GET', `/store/modules/${enc}/versions/${encodeURIComponent(described.version)}/tarball`, { binary: true }); }
+  catch (e) { return fail(1, `bongos module ${verb}: download failed — ${e.message}`); }
+  if (!dl.ok) return fail(1, `REFUSING: the download was refused (HTTP ${dl.status}): ${storeError(dl)}`);
+
+  const artifact = require('./module-artifact');
+  const verified = await artifact.verifyModuleArtifact(dl.buf, { key, includeFiles: true });
+  if (!verified.ok) return fail(1, `REFUSING: the downloaded tarball failed verification (${verified.code}): ${verified.message}`);
+  if (verified.version !== described.version || verified.tarballSha256 !== described.tarball_sha256 || verified.treeSha256 !== described.tree_sha256) {
+    return fail(1, `REFUSING: the download is not the ${described.version} the store described (version or hash differs).`);
+  }
+  log(`  ✓ verified ${verified.files.length} file(s), ${verified.bytes} bytes — tree ${verified.treeSha256.slice(0, 12)}…`);
+  return { ok: true, described, verified };
+}
+
+// Tell the store which exact version was placed. A failure here never undoes the
+// placement: the files are good, and the next install or update records it.
+async function recordPlaced(key, version, { call, errlog, verb }) {
+  let rec;
+  try { rec = await call('POST', `/store/modules/${encodeURIComponent(key)}/acquired`, { json: { version } }); }
+  catch (e) { rec = { ok: false, status: 0, data: { error: { message: e.message } } }; }
+  if (!rec.ok) {
+    errlog(`WARNING: "${key}" is ${verb === 'update' ? 'updated' : 'installed'}, but the store did not record the version (${storeError(rec)}). Nothing is lost; the next install or update records it.`);
+    return false;
+  }
+  return true;
+}
+
 // `bongos module install <key> [--version X.Y.Z]` — task 1003785. Acquires the
 // module (a free one is granted on the spot; a priced one waits on the buy action,
 // area 8), downloads its tarball, verifies it with verifyModuleArtifact — the one
 // checker the store itself uses on publish — and places it under the instance's
 // modules/. It never enables: the loader discovers what is on disk and the hall's
-// Modules tab decides what mounts. A module already on disk is refused; moving an
-// installed module to a newer version is `update` (task 1003786).
+// Modules tab decides what mounts. A key already on disk in ANY discovery root is
+// refused; moving an installed module to a newer version is `update` (task 1003786).
 async function cmdInstall(args, {
   log = console.log, errlog = console.error,
-  modulesDir, request, core,
+  modulesDir, roots, request, core,
 } = {}) {
-  const usage = 'usage: bongos module install <key> [--version X.Y.Z]';
-  const vIdx = args.indexOf('--version');
-  const wanted = vIdx !== -1 ? args[vIdx + 1] : null;
-  const key = args.find((a, i) => !a.startsWith('-') && args[i - 1] !== '--version');
-  if (!key || (vIdx !== -1 && (!wanted || wanted.startsWith('--')))) { errlog(usage); return 2; }
-  if (!KEY_RE.test(key)) { errlog(`REFUSING: "${key}" is not a module key (lowercase kebab-case).`); return 2; }
-  const { parseVersion, satisfies } = require('../../src/module-loader/semver');
-  if (wanted && !parseVersion(wanted)) { errlog(`REFUSING: --version must be exact X.Y.Z, not "${wanted}".`); return 2; }
+  const parsed = parseStoreArgs(args, 'install', errlog);
+  if (parsed.code) return parsed.code;
+  const { key, wanted } = parsed;
 
   const dir = modulesDir || instanceModulesDir();
   const target = path.join(dir, key);
-  if (fs.existsSync(target)) {
-    errlog(`REFUSING: "${key}" is already on disk at ${target}. Install only adds a new module; updating one is a separate command.`);
+  const taken = [dir, ...(roots || discoveryRoots())].map((r) => path.join(r, key)).find((p) => fs.existsSync(p));
+  if (taken) {
+    errlog(`REFUSING: "${key}" is already on disk at ${taken}. Install only adds a new module; to move an installed one forward, run \`bongos module update ${key}\`.`);
     return 1;
   }
 
@@ -956,47 +1031,99 @@ async function cmdInstall(args, {
   try { call = request || storeRequest(); }
   catch (e) { errlog(`bongos module install: ${e.message}`); return 1; }
 
-  const enc = encodeURIComponent(key);
-  let acq;
-  try { acq = await call('POST', `/store/modules/${enc}/acquire`, { json: wanted ? { version: wanted } : {} }); }
-  catch (e) { errlog(`bongos module install: the store could not be reached — ${e.message}`); return 1; }
-  if (!acq.ok) { errlog(`REFUSING: the store would not hand over "${key}" (HTTP ${acq.status}): ${storeError(acq)}`); return 1; }
-  const a = acq.data;
-  log(`bongos module install — "${key}" ${a.version} (needs core ${a.core_version})`);
+  const got = await fetchVerified(key, { wanted, call, core, log, errlog, verb: 'install' });
+  if (!got.ok) return got.code;
 
-  const coreV = core || require('../../src/module-api').CORE_VERSION;
-  if (!satisfies(coreV, a.core_version)) {
-    errlog(`REFUSING: "${key}" ${a.version} needs core ${a.core_version}; this core is ${coreV}, so it could not mount.`);
-    return 1;
-  }
+  try { placeModule(got.verified.files, target); }
+  catch (e) { errlog(`bongos module install: could not place the module — ${e.message}`); return 1; }
+  log(`  ✓ placed at ${target}`);
 
-  let dl;
-  try { dl = await call('GET', `/store/modules/${enc}/versions/${encodeURIComponent(a.version)}/tarball`, { binary: true }); }
-  catch (e) { errlog(`bongos module install: download failed — ${e.message}`); return 1; }
-  if (!dl.ok) { errlog(`REFUSING: the download was refused (HTTP ${dl.status}): ${storeError(dl)}`); return 1; }
+  if (!(await recordPlaced(key, got.described.version, { call, errlog, verb: 'install' }))) return 1;
+  log(`\n✓ Installed "${key}" ${got.described.version}. It is not switched on: enable it from the hall's Modules tab when you want it.`);
+  return 0;
+}
 
-  const artifact = require('./module-artifact');
-  const v = await artifact.verifyModuleArtifact(dl.buf, { key, includeFiles: true });
-  if (!v.ok) { errlog(`REFUSING: the downloaded tarball failed verification (${v.code}): ${v.message}`); return 1; }
-  if (v.version !== a.version || v.tarballSha256 !== a.tarball_sha256 || v.treeSha256 !== a.tree_sha256) {
-    errlog(`REFUSING: the download is not the ${a.version} the store described (version or hash differs).`);
-    return 1;
+// Replace an installed module's directory with a verified new one. The new files
+// are written to a staging dir first; the old dir is moved aside, the new one moved
+// in, and only then is the old one removed — so a failure at any step leaves the
+// previous version in place, never a half-written or missing module.
+function replaceModule(files, target) {
+  const aside = `${target}.previous-${process.pid}-${Date.now()}`;
+  const staging = `${target}.installing-${process.pid}-${Date.now()}`;
+  placeModule(files, staging);
+  try {
+    fs.renameSync(target, aside);
+  } catch (e) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw e;
+  }
+  try {
+    fs.renameSync(staging, target);
+  } catch (e) {
+    fs.renameSync(aside, target);
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw e;
   }
-  log(`  ✓ verified ${v.files.length} file(s), ${v.bytes} bytes — tree ${v.treeSha256.slice(0, 12)}…`);
+  fs.rmSync(aside, { recursive: true, force: true });
+}
 
-  try { placeModule(v.files, target); }
-  catch (e) { errlog(`bongos module install: could not place the module — ${e.message}`); return 1; }
-  log(`  ✓ placed at ${target}`);
+// `bongos module update <key> [--version X.Y.Z]` — task 1003786. Moves an installed
+// store module forward, through exactly the acquisition path install uses
+// (fetchVerified): the same calls whether the module was free or paid, and a module
+// the caller already holds is never charged again (the store's acquire route only
+// looks at price for a caller with no entitlement). Only forward: with no --version
+// it takes the newest, and says so without downloading when that is not newer; an
+// older --version is refused, since rolling back is a different act. Like install it
+// never enables or disables — the module keeps whatever switch it had.
+async function cmdUpdate(args, {
+  log = console.log, errlog = console.error,
+  modulesDir, roots, request, core,
+} = {}) {
+  const parsed = parseStoreArgs(args, 'update', errlog);
+  if (parsed.code) return parsed.code;
+  const { key, wanted } = parsed;
 
-  let rec;
-  try { rec = await call('POST', `/store/modules/${enc}/acquired`, { json: { version: a.version } }); }
-  catch (e) { rec = { ok: false, status: 0, data: { error: { message: e.message } } }; }
-  if (!rec.ok) {
-    errlog(`WARNING: "${key}" is installed, but the store did not record the version (${storeError(rec)}). Nothing is lost; the next install or update records it.`);
+  const dir = modulesDir || instanceModulesDir();
+  const target = path.join(dir, key);
+  if (!fs.existsSync(path.join(target, 'module.json'))) {
+    const bundled = (roots || discoveryRoots()).map((r) => path.join(r, key)).find((p) => p !== target && fs.existsSync(p));
+    errlog(bundled
+      ? `REFUSING: "${key}" at ${bundled} comes with the core, not the store. It updates when the core does (\`bongos upgrade\`).`
+      : `REFUSING: "${key}" is not installed here. Run \`bongos module install ${key}\` first.`);
     return 1;
   }
+  const { parseVersion, cmp } = require('../../src/module-loader/semver');
+  let installed;
+  try { installed = JSON.parse(fs.readFileSync(path.join(target, 'module.json'), 'utf8')).version; }
+  catch (e) { errlog(`REFUSING: could not read the installed ${key}/module.json — ${e.message}`); return 1; }
+  const have = parseVersion(String(installed));
+  if (!have) { errlog(`REFUSING: the installed "${key}" has no exact version in module.json, so there is nothing to compare against.`); return 1; }
+  if (wanted && cmp(parseVersion(wanted), have) < 0) {
+    errlog(`REFUSING: ${wanted} is older than the installed ${installed}. Update only moves forward.`);
+    return 1;
+  }
+
+  let call;
+  try { call = request || storeRequest(); }
+  catch (e) { errlog(`bongos module update: ${e.message}`); return 1; }
+
+  const got = await fetchVerified(key, {
+    wanted, call, core, log, errlog, verb: 'update',
+    shouldDownload: (d) => {
+      const next = parseVersion(String(d.version));
+      if (next && cmp(next, have) > 0) return true;
+      log(`\n✓ "${key}" is up to date at ${installed}.`);
+      return { code: 0, upToDate: true };
+    },
+  });
+  if (!got.ok) return got.code;
+
+  try { replaceModule(got.verified.files, target); }
+  catch (e) { errlog(`bongos module update: could not replace the module, ${installed} is still in place — ${e.message}`); return 1; }
+  log(`  ✓ replaced ${installed} with ${got.described.version} at ${target}`);
 
-  log(`\n✓ Installed "${key}" ${a.version}. It is not switched on: enable it from the hall's Modules tab when you want it.`);
+  if (!(await recordPlaced(key, got.described.version, { call, errlog, verb: 'update' }))) return 1;
+  log(`\n✓ Updated "${key}" ${installed} → ${got.described.version}. Its on/off switch is unchanged.`);
   return 0;
 }
 
@@ -1015,6 +1142,8 @@ function printHelp(out = console.log) {
   out('                              Pack a module version (tarball + hash manifest) and upload it to the module store');
   out('  bongos module install <key> [--version X.Y.Z]');
   out('                              Acquire a module from the store, verify it and place it under modules/ (not enabled)');
+  out('  bongos module update <key> [--version X.Y.Z]');
+  out('                              Move an installed store module to a newer version (same path, paid or free)');
 }
 
 async function main(argv) {
@@ -1027,6 +1156,7 @@ async function main(argv) {
   if (sub === 'submit') return cmdSubmit(args.slice(1));
   if (sub === 'publish') return cmdPublish(args.slice(1));
   if (sub === 'install') return cmdInstall(args.slice(1));
+  if (sub === 'update') return cmdUpdate(args.slice(1));
   if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
     printHelp();
     return sub ? 0 : 2;
@@ -1037,7 +1167,7 @@ async function main(argv) {
 }
 
 module.exports = {
-  main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, cmdPublish, cmdInstall, printHelp,
+  main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, cmdPublish, cmdInstall, cmdUpdate, printHelp,
   gatherCatalog, formatCatalog, ownProjectName,
   scaffoldModule, gatherUpgrade, evaluateUpgrade, buildManifest,
   formatMaintenanceHint, isPastRemoveAfter,

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.19.1079'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1080'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/module_update.mjs

@@ -0,0 +1,232 @@
+// tests/module_update.mjs — `bongos module update <key>` (task 1003786, ADR 0338 D1,
+// criterion wa5-module-economy). No network, no database: cmdUpdate runs against a
+// fake store serving REAL packed tarballs, so verification is the real
+// verifyModuleArtifact.
+//
+// The criterion's teeth are the parity tests: an update to a paid module the caller
+// holds and to a free one make the identical calls with the identical outcome, and
+// the shared acquisition path carries no price-conditional code at all.
+//
+// Run:  node tests/module_update.mjs
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { packModule, verifyModuleArtifact } = require('../scripts/gds/module-artifact.js');
+const { readTar, buildTar } = require('../scripts/gds/artifact-format.js');
+const { cmdUpdate, cmdInstall } = require('../scripts/gds/module.js');
+
+const NOW = () => new Date('2026-09-29T00:00:00Z');
+
+// A real packed tarball for weather@version, with `extra` files beside module.json.
+async function packed(version, extra = {}, mj = {}) {
+  const src = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-update-src-'));
+  const manifest = { key: 'weather', title: 'Weather', description: 'Shows the weather.', version, coreVersion: '^1.0.0', contributes: {}, ...mj };
+  const dir = path.join(src, 'weather');
+  const files = { 'module.json': JSON.stringify(manifest, null, 2), 'routes/weather.js': `module.exports = () => '${version}';\n`, ...extra };
+  for (const [rel, body] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(path.join(dir, rel)), { recursive: true });
+    fs.writeFileSync(path.join(dir, rel), body);
+  }
+  const { tgz } = packModule('weather', { modulesDir: src, now: NOW, modeOf: () => '644' });
+  const v = await verifyModuleArtifact(tgz, { key: 'weather' });
+  assert.ok(v.ok);
+  return { tgz, v };
+}
+
+// An installed weather@version in a fresh modules dir.
+function installedAt(version, extra = {}) {
+  const modulesDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-update-dest-'));
+  const dir = path.join(modulesDir, 'weather');
+  const files = { 'module.json': JSON.stringify({ key: 'weather', version }), 'routes/weather.js': `module.exports = () => '${version}';\n`, ...extra };
+  for (const [rel, body] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(path.join(dir, rel)), { recursive: true });
+    fs.writeFileSync(path.join(dir, rel), body);
+  }
+  return modulesDir;
+}
+
+// A fake store. `source` is how the caller came to hold the module; the store's own
+// acquire route never looks at price for a holder, so nothing else differs.
+function fakeStore({ tgz, v }, { source = 'free', over = {} } = {}) {
+  const calls = [];
+  const request = async (method, urlPath, opts = {}) => {
+    calls.push({ method, urlPath, json: opts.json });
+    if (urlPath.endsWith('/acquire')) {
+      return over.acquire || { ok: true, status: 200, data: {
+        ok: true, module_key: 'weather', version: v.version, core_version: v.coreVersion,
+        tarball_sha256: v.tarballSha256, tree_sha256: v.treeSha256, tarball_bytes: v.bytes, channel: 'general',
+        entitlement: { module_key: 'weather', holder_kind: 'builder', holder_ref: '42', source, version: '1.2.0' },
+      } };
+    }
+    if (urlPath.endsWith('/tarball')) return { ok: true, status: 200, buf: over.buf || tgz };
+    if (urlPath.endsWith('/acquired')) return { ok: true, status: 200, data: { ok: true } };
+    throw new Error(`unexpected ${method} ${urlPath}`);
+  };
+  return { calls, request };
+}
+
+const quiet = () => { const out = []; return { out, log: (m) => out.push(m), errlog: (m) => out.push(m) }; };
+const opts = (modulesDir, store, q = quiet()) => ({ ...q, modulesDir, roots: [], request: store.request, core: '1.19.0' });
+const route = (modulesDir) => fs.readFileSync(path.join(modulesDir, 'weather', 'routes', 'weather.js'), 'utf8');
+
+// ---- update ----
+
+test('updates an installed module to the newest version: files replaced, old-only files gone, version recorded', async () => {
+  const modulesDir = installedAt('1.2.0', { 'old-only.js': 'x' });
+  const store = fakeStore(await packed('1.3.0'));
+  const q = quiet();
+  assert.equal(await cmdUpdate(['weather'], opts(modulesDir, store, q)), 0, q.out.join('\n'));
+  assert.equal(route(modulesDir), "module.exports = () => '1.3.0';\n");
+  assert.ok(!fs.existsSync(path.join(modulesDir, 'weather', 'old-only.js')), 'the new version is exactly what was published');
+  assert.deepEqual(fs.readdirSync(modulesDir), ['weather'], 'no staging or previous dir left behind');
+  assert.deepEqual(store.calls.map((c) => `${c.method} ${c.urlPath}`), [
+    'POST /store/modules/weather/acquire',
+    'GET /store/modules/weather/versions/1.3.0/tarball',
+    'POST /store/modules/weather/acquired',
+  ]);
+  assert.deepEqual(store.calls[2].json, { version: '1.3.0' });
+  assert.match(q.out.join('\n'), /1\.2\.0 → 1\.3\.0\. Its on\/off switch is unchanged/);
+});
+
+test('already on the newest version: says so and downloads nothing', async () => {
+  const modulesDir = installedAt('1.3.0');
+  const store = fakeStore(await packed('1.3.0'));
+  const q = quiet();
+  assert.equal(await cmdUpdate(['weather'], opts(modulesDir, store, q)), 0);
+  assert.deepEqual(store.calls.map((c) => c.urlPath), ['/store/modules/weather/acquire']);
+  assert.match(q.out.join('\n'), /up to date at 1\.3\.0/);
+});
+
+test('an older --version is refused before the store is asked: update only moves forward', async () => {
+  const modulesDir = installedAt('1.3.0');
+  const store = fakeStore(await packed('1.2.0'));
+  assert.equal(await cmdUpdate(['weather', '--version', '1.2.0'], opts(modulesDir, store)), 1);
+  assert.equal(store.calls.length, 0);
+  assert.equal(route(modulesDir), "module.exports = () => '1.3.0';\n");
+});
+
+test('--version asks the store for that exact version', async () => {
+  const modulesDir = installedAt('1.2.0');
+  const store = fakeStore(await packed('1.4.0'));
+  assert.equal(await cmdUpdate(['weather', '--version', '1.4.0'], opts(modulesDir, store)), 0);
+  assert.deepEqual(store.calls[0].json, { version: '1.4.0' });
+});
+
+test('a module that is not installed is refused, pointing at install', async () => {
+  const modulesDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-update-empty-'));
+  const store = fakeStore(await packed('1.3.0'));
+  const q = quiet();
+  assert.equal(await cmdUpdate(['weather'], opts(modulesDir, store, q)), 1);
+  assert.match(q.out.join('\n'), /not installed here\. Run `bongos module install weather`/);
+  assert.equal(store.calls.length, 0);
+});
+
+test('a module bundled with the core is refused: it updates with the core', async () => {
+  const modulesDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-update-empty-'));
+  const coreRoot = installedAt('1.0.0');
+  const store = fakeStore(await packed('1.3.0'));
+  const q = quiet();
+  assert.equal(await cmdUpdate(['weather'], { ...opts(modulesDir, store, q), roots: [coreRoot] }), 1);
+  assert.match(q.out.join('\n'), /comes with the core, not the store/);
+  assert.equal(store.calls.length, 0);
+});
+
+test('a tampered download leaves the installed version untouched', async () => {
+  const modulesDir = installedAt('1.2.0');
+  const next = await packed('1.3.0');
+  const entries = readTar(next.tgz);
+  entries.find((e) => e.name.endsWith('routes/weather.js')).buf = Buffer.from('evil();\n');
+  const store = fakeStore(next, { over: { buf: buildTar(entries) } });
+  const q = quiet();
+  assert.equal(await cmdUpdate(['weather'], opts(modulesDir, store, q)), 1);
+  assert.match(q.out.join('\n'), /failed verification \(hash_mismatch\)/);
+  assert.equal(route(modulesDir), "module.exports = () => '1.2.0';\n");
+  assert.deepEqual(fs.readdirSync(modulesDir), ['weather']);
+  assert.ok(!store.calls.some((c) => c.urlPath.endsWith('/acquired')));
+});
+
+test('a version this core cannot mount is refused before download, the installed one kept', async () => {
+  const modulesDir = installedAt('1.2.0');
+  const store = fakeStore(await packed('2.0.0', {}, { coreVersion: '^2.0.0' }));
+  assert.equal(await cmdUpdate(['weather'], opts(modulesDir, store)), 1);
+  assert.equal(store.calls.length, 1);
+  assert.equal(route(modulesDir), "module.exports = () => '1.2.0';\n");
+});
+
+test('a store refusal (e.g. a delisted module) keeps the installed version', async () => {
+  const modulesDir = installedAt('1.2.0');
+  const store = fakeStore(await packed('1.3.0'), { over: { acquire: { ok: false, status: 409, data: { error: { code: 'module_delisted', message: 'delisted' } } } } });
+  const q = quiet();
+  assert.equal(await cmdUpdate(['weather'], opts(modulesDir, store, q)), 1);
+  assert.match(q.out.join('\n'), /HTTP 409\): delisted/);
+  assert.equal(route(modulesDir), "module.exports = () => '1.2.0';\n");
+});
+
+// ---- parity: paid and free take one path (criterion wa5-module-economy) ----
+
+test('a paid module the caller holds and a free one update through identical calls with an identical outcome', async () => {
+  const next = await packed('1.3.0');
+  const runs = {};
+  for (const source of ['free', 'purchase', 'grant', 'core']) {
+    const modulesDir = installedAt('1.2.0');
+    const store = fakeStore(next, { source });
+    const q = quiet();
+    const code = await cmdUpdate(['weather'], opts(modulesDir, store, q));
+    runs[source] = { code, calls: store.calls, out: q.out.join('\n').replaceAll(modulesDir, '<dir>'), route: route(modulesDir) };
+  }
+  for (const source of ['purchase', 'grant', 'core']) {
+    assert.deepEqual(runs[source], runs.free, `an update of a module held as '${source}' must not differ from a free one`);
+  }
+  assert.equal(runs.free.code, 0);
+});
+
+// Strip comments so only code is scanned; a word in an explanation is not a branch.
+function codeOf(src, fnName) {
+  const start = src.indexOf(`function ${fnName}(`);
+  assert.ok(start !== -1, `${fnName} exists`);
+  const next = src.indexOf('\nfunction ', start + 1);
+  const nextAsync = src.indexOf('\nasync function ', start + 1);
+  const end = [next, nextAsync].filter((i) => i > start).sort((a, b) => a - b)[0] ?? src.length;
+  return src.slice(start, end).replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
+}
+
+test('the shared acquisition path, install and update carry no price-conditional code', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'scripts/gds/module.js'), 'utf8');
+  for (const fn of ['fetchVerified', 'recordPlaced', 'cmdInstall', 'cmdUpdate', 'replaceModule', 'placeModule']) {
+    assert.doesNotMatch(codeOf(src, fn), /\b(price|priced|paid|cents|credits|free|purchase|source)\b/i, `${fn} must not read how the module was obtained`);
+  }
+  // Both commands go through the one path, not two copies of it.
+  assert.match(codeOf(src, 'cmdInstall'), /await fetchVerified\(key,/);
+  assert.match(codeOf(src, 'cmdUpdate'), /await fetchVerified\(key,/);
+});
+
+test('the store only looks at price for a caller who holds no entitlement, so a holder is never charged again', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'src/bongos/routes/modules.js'), 'utf8');
+  const start = src.indexOf("router.post('/store/modules/:key/acquire'");
+  const block = src.slice(start, src.indexOf('router.get(', start));
+  const priceAt = block.indexOf('r.free');
+  const guardAt = block.indexOf('if (!held.entitled) {');
+  assert.ok(guardAt !== -1 && priceAt > guardAt, 'the price check sits inside the not-entitled branch');
+  assert.equal(block.split('r.free').length - 1, 1, 'price is read in exactly one place');
+});
+
+// ---- install: the grader's finding on task 1003785 ----
+
+test('install refuses a key already present in another discovery root (a module bundled with the core)', async () => {
+  const modulesDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-install-empty-'));
+  const coreRoot = installedAt('1.0.0');
+  const store = fakeStore(await packed('1.3.0'));
+  const q = quiet();
+  assert.equal(await cmdInstall(['weather'], { ...opts(modulesDir, store, q), roots: [coreRoot] }), 1);
+  assert.match(q.out.join('\n'), /already on disk at .*run `bongos module update weather`/);
+  assert.equal(store.calls.length, 0);
+  assert.deepEqual(fs.readdirSync(modulesDir), []);
+});