@bongos/core 1.20.36 → 1.20.37

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.20.36",
-  "core_contract": "1.20.36",
-  "source_commit": "ef99e051581c54bf82390637612645c6843c1a89",
+  "core_version": "1.20.37",
+  "core_contract": "1.20.37",
+  "source_commit": "f1e5bf27f6d26ab0ac34690a4dc1d8d77bf664b3",
   "source_ref": "HEAD",
-  "built_at": "2026-09-30T23:00:27.650Z",
+  "built_at": "2026-09-30T23:18:11.929Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 562,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2673,
+    "functional_verbatim": 2675,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3261,
-  "tree_sha256": "f5c36910af4994519b2992104681279da50a6e91bac57f5d05457f50d795153a",
+  "file_count": 3263,
+  "tree_sha256": "8c656cd221547b1969984338b6271ddd489b2aee573810eb5bb563c2db9e4f11",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2272,7 +2272,7 @@
     {
       "path": "docs/architecture.md",
       "mode": "0000644",
-      "sha256": "4149011e96acb427e32a55b0e48026ad0aa5a5ac2d3fa5054da9e5ef0e4f9a3f"
+      "sha256": "e73b5883090da09febf6fcbb3b23ccc6582623eb864b385b759687c061ea4cd3"
     },
     {
       "path": "docs/branding-contract.md",
@@ -2802,7 +2802,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "c47bc356e4e0b51f670d88d07c5996ba6cf899572516ede0d76fa7048784f297"
+      "sha256": "8473af383b4c8cc856d7bfd61404ea7d0c76953de98cdb2838a06094ba775587"
     },
     {
       "path": "docs/modules-contract.md",
@@ -8997,12 +8997,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "094e54a0001c11e30b43314ab7158d28a90e01307c158ce7349849c03794512d"
+      "sha256": "071e1c2aa6ecec48b6aa07cfb8b548a0658b9812066a0f0bcb9f555310ce07ef"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "d8b6832d3d9283d028c516cb646cb0d8ef677913c45f1ac84f45675f84d1017e"
+      "sha256": "8ada5651cfc648a3cafd4f3571e4cf3e30d3f58a82d0f9a4ca3febd32d6f1638"
     },
     {
       "path": "public-docs/index.html",
@@ -9022,7 +9022,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "60f91c3b0b103ee76210b8501b1b7bb1e1c3b250705628c79c8383354602a0b3"
+      "sha256": "5b7e70fb99324b9f0568c77f388646d11b897f6886b1d67e4536ce3a871df971"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -9182,7 +9182,7 @@
     {
       "path": "scripts/gds/autobongos-run.js",
       "mode": "0000644",
-      "sha256": "ac0d77b54920e50205546db4269957fd6a0fc2f1ba1aca9c097abc920fa04f2a"
+      "sha256": "bb633909f9547e67809d474f4198ce1146ae2044d70e2c84424870fa179c0a96"
     },
     {
       "path": "scripts/gds/autobongos-service.cmd",
@@ -9864,6 +9864,11 @@
       "mode": "0000644",
       "sha256": "09211dcd5bae4b935b5f80a2c021a1c10a376236b1c7ea7ebc1f53b84d1ead40"
     },
+    {
+      "path": "scripts/gds/module-assess-tests.js",
+      "mode": "0000644",
+      "sha256": "b86d6b3b98534c91b2dffe67f6c5335a09d2ef7c571c70e3a0871ab4929bc490"
+    },
     {
       "path": "scripts/gds/module.js",
       "mode": "0000644",
@@ -11162,7 +11167,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "8d3d3bbb64ab3138e8d2f25e6bd6b1f6158c720d700d3d7388e63e5bf12276f5"
+      "sha256": "e36b04da83d53169550b5897dead018db39ac197d25c2b0f034db6faf05b2715"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11622,7 +11627,7 @@
     {
       "path": "tests/autobongos_loop.mjs",
       "mode": "0000644",
-      "sha256": "91e92c46fe27a4382a762029418437642b038a77286de0977ac694397759a0b6"
+      "sha256": "c7f0131e2182c967d90b3df6aef74121f1ea8746fcb7e8e848cb6747f1a4d965"
     },
     {
       "path": "tests/autobongos_service_ps1.mjs",
@@ -14129,6 +14134,11 @@
       "mode": "0000644",
       "sha256": "9183d78e4d195428afbee8c71746e12db2455f8529ac1223d690a7b8f7ded538"
     },
+    {
+      "path": "tests/module_assess_tests.mjs",
+      "mode": "0000644",
+      "sha256": "eb2c6167ee1dc57274ace741a75852140ff2614d9b35234918f45d1b41414d6f"
+    },
     {
       "path": "tests/module_assessments_migration.mjs",
       "mode": "0000644",

package/docs/architecture.md

@@ -272,6 +272,8 @@ module_assessment_scores(id, version_id, kind IN (computed|override), overall 0-
               -- and is a new row on the computed history, never an edit (D6)
 ```
 
+Signals that fill it: **Tests** — `scripts/gds/module-assess-tests.js <version id>` (task 1003791) unpacks the published tarball to `<core root>/.module-assess-<run>/<key>/` (gitignored, removed after), runs each `tests/*.mjs` in its own node process with a timeout and a credential-free environment — regardless of `isModuleEnabled`, which skips every default-off catalog module in the unit gate — and appends one `tests` row: `scored` = % of test files passing (sample_size = files), `no_data` = declares no tests, `not_scored` = tarball unreadable. The store path **refuses unless `MODULE_TEST_SANDBOX=1`** — a published module's tests run only in a separate testing environment with no secrets on disk, never on the control plane (owner, 2026-09-30). `--dir modules/<key>` is a DB-free dry run on your own checkout. Nothing calls it on publish yet (task 1003794 wires that).
+
 Code: `src/bongos/module-entitlements.js` (`grantEntitlement`, `recordAcquired`, `revokeEntitlement`, `checkEntitlement`, `listEntitlements`). Read routes (own-scoped, `requireBuilder`): `GET /store/entitlements`, `GET /store/modules/:key/entitlement`. Install (task 1003785) grants a free module through `POST /store/modules/:key/acquire`; the buy action (area 8) will grant a paid one.
 
 Bongos views: `claimable_tasks` (rebuilt in 006 to use SELECT t.*; rebuilt again in 014 so the new `discipline` column flows through), `version_progress` (rebuilt in 006 to count only leaf tasks for forward-compat with task hierarchy), `tasks_session_fit` (new in 006: derives `fits_session_modes[]` and `credits_per_minute`; rebuilt in 014 for the same SELECT t.* refresh), `task_grades_with_context` (new in 016: joins task_grades × tasks × builders × cost_log so the V4 optimizer has quality-per-dollar in one read).

package/docs/module-api-changelog.md

@@ -2729,5 +2729,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.20.34 with no explicit bump. run 36787635391. (task 1002620)
   1.20.36 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.20.35 with no explicit bump. run 36788696388. (task 1002620)
+  1.20.37 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.36 with no explicit bump. run 36790298715. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.36",
+  "version": "1.20.37",
   "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",

package/release-notes.json

@@ -8303,5 +8303,15 @@
       "id": "1004450",
       "text": "The deploy page now explains why an update stopped in plain words, says when it will try again, and offers a one-click fix when the only thing in the way is your own update setting. You can also see and change how far a projec"
     }
+  ],
+  "1.20.37": [
+    {
+      "id": "1003791",
+      "text": "A module's own tests can now be run and scored: the store records what share of them pass, and a module with no tests shows as 'no data yet' instead of failing."
+    },
+    {
+      "id": "1004406",
+      "text": "The unattended runner stops restarting every time anyone merges: it now updates its code in place and only restarts when its own code has changed."
+    }
   ]
 }

package/scripts/gds/autobongos-run.js

@@ -359,7 +359,7 @@ const MAX_CLAIM_ATTEMPTS = 5;
 const LIMIT_UNKNOWN_RESET_MS = 30 * 60 * 1000;
 
 function newRunnerState() {
-  return { setAside: new Map(), queueGate: null, limitUntil: null };
+  return { setAside: new Map(), queueGate: null, limitUntil: null, diskHead: null };
 }
 const RUNNER_STATE = newRunnerState();
 
@@ -666,13 +666,16 @@ function heartbeatPath() {
 // output, reddening `unit` on main and blocking every PR. Use a regular FILE as the
 // parent directory instead: mkdir under it is ENOTDIR immediately, everywhere, and it
 // does not depend on the caller's permissions.
-function writeHeartbeat(now = Date.now()) {
+function writeHeartbeat(now = Date.now(), runnerState = RUNNER_STATE) {
   try {
     const p = heartbeatPath();
     fs.mkdirSync(path.dirname(p), { recursive: true });
     // `head` is what this process is RUNNING, not what is on disk (task 1004374).
     // Alive and alive-on-stale-code look identical from a check-in age alone.
-    fs.writeFileSync(p, JSON.stringify({ pid: process.pid, at: now, head: LOADED_HEAD }));
+    // `disk_head` appears only when the checkout was refreshed in place past what
+    // is running (task 1004406): "up to date on disk, old supervisor" is visible.
+    const disk = runnerState && runnerState.diskHead && runnerState.diskHead !== LOADED_HEAD ? runnerState.diskHead : undefined;
+    fs.writeFileSync(p, JSON.stringify({ pid: process.pid, at: now, head: LOADED_HEAD, ...(disk ? { disk_head: disk } : {}) }));
     return true;
   } catch (_) { return false; }
 }
@@ -851,10 +854,79 @@ async function codeDrifted(deps = {}) {
   // the comparison untestable in isolation.
   const mine = deps.loadedHead ? await deps.loadedHead(deps) : await loadedHead(deps);
   if (!mine) return null;
+  // Measured from what is on DISK once the checkout has been refreshed in place
+  // (task 1004406), or every loop after a refresh would see the same drift again.
+  const base = ((deps.state || RUNNER_STATE).diskHead) || mine;
   let tip = null;
   try { tip = await runFetchHead(deps); } catch (_) { return null; }
   if (!tip) return null;
-  return tip !== mine ? { from: mine.slice(0, 8), to: String(tip).slice(0, 8) } : false;
+  return tip !== base ? { from: base.slice(0, 8), to: String(tip).slice(0, 8) } : false;
+}
+
+// ── pull always, restart rarely (task 1004406) ──────────────────────────────
+//
+// Owner-approved 2026-09-30. Main moves every time ANY session lands, and a
+// relaunch per merge meant a busy day of restarts (four in fourteen minutes on
+// 2026-09-29). But a restart only refreshes code THIS process holds in memory:
+// every worker, and every claim.js / worktree.js / release.js the loop shells
+// out to, is a fresh process that runs whatever is on disk. So on drift the
+// checkout is updated in place, and the process exits for the wrapper only when
+// a change touches code it has actually loaded.
+//
+// SUPERVISOR_PATH_RES catch the supervisor's own files even before they are
+// required (autobongos-verify.js is loaded lazily on the first ship), so a change
+// to a file the loop is ABOUT to load cannot mix old callers with a new callee.
+const SUPERVISOR_PATH_RES = [/^scripts\/gds\/autobongos-[^/]+$/, /^modules\/autonomy\//];
+
+// The repo files this process has loaded, repo-relative with forward slashes.
+function loadedFiles() {
+  const root = REPO_ROOT + path.sep;
+  const nm = path.sep + 'node_modules' + path.sep;
+  return Object.keys(require.cache)
+    .filter((p) => p.startsWith(root) && !p.includes(nm))
+    .map((p) => path.relative(REPO_ROOT, p).split(path.sep).join('/'));
+}
+
+// The changed files that force a restart: ones this process holds, or ones under
+// the supervisor's own paths. Everything else is picked up by the next child.
+function supervisorTouched(changed = [], loaded = loadedFiles()) {
+  const held = new Set(loaded);
+  return changed.filter((f) => held.has(f) || SUPERVISOR_PATH_RES.some((re) => re.test(f)));
+}
+
+// refreshCheckout — the wrapper's fetch + reset, done from inside the process.
+//
+// THE MAIN CHECKOUT ONLY. It runs `git reset --hard`, and a linked worktree is a
+// claim somebody is building in; resetting one would destroy their work. The
+// check compares git-dir to git-common-dir, which are equal only in the main
+// checkout. Armed only by main() (`opts.refreshInPlace`), so a test driving
+// forever() can never reach it — in CI that reset would wipe the code under test.
+//
+// The diff is from the LOADED commit, not the last refresh, so a supervisor
+// change that landed several refreshes ago still forces the restart it needs.
+async function refreshCheckout(deps = {}) {
+  const runCmd = deps.run || run;
+  const git = (args) => runCmd('git', args, { cwd: REPO_ROOT });
+  try {
+    const [gd, cd] = await Promise.all([git(['rev-parse', '--git-dir']), git(['rev-parse', '--git-common-dir'])]);
+    if (!gd.ok || !cd.ok) return { ok: false, reason: 'could not tell which checkout this is' };
+    if (path.resolve(REPO_ROOT, String(gd.stdout).trim()) !== path.resolve(REPO_ROOT, String(cd.stdout).trim())) {
+      return { ok: false, reason: 'not the main checkout — refusing to reset a linked worktree' };
+    }
+    const loaded = deps.loadedHead ? await deps.loadedHead(deps) : await loadedHead(deps);
+    if (!loaded) return { ok: false, reason: 'the running commit is unknown' };
+    if (!(await git(['fetch', '--quiet', 'origin', 'main'])).ok) return { ok: false, reason: 'fetch failed' };
+    const fh = await git(['rev-parse', 'FETCH_HEAD']);
+    const to = fh.ok ? String(fh.stdout).trim() : '';
+    if (!/^[0-9a-f]{40}$/.test(to)) return { ok: false, reason: 'could not read the fetched commit' };
+    const diff = await git(['diff', '--name-only', loaded, to]);
+    if (!diff.ok) return { ok: false, reason: 'could not diff the running commit against main' };
+    if (!(await git(['reset', '--quiet', '--hard', to])).ok) return { ok: false, reason: 'reset failed' };
+    const changed = String(diff.stdout).split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    return { ok: true, to, changed };
+  } catch (e) {
+    return { ok: false, reason: e && e.message ? e.message : String(e) };
+  }
 }
 
 // The head of origin/main, or null. `git ls-remote` rather than `fetch`: it moves
@@ -932,7 +1004,9 @@ async function forever(opts, deps = {}) {
   // reports itself anyway: the hall reads the AGE of the last check-in, so a
   // failed beat shows up as silence, which is the signal.
   const beat = async (fields) => {
-    try { beatFile(); } catch (_) { /* a runner that cannot write its file still runs */ }
+    // The runner state is passed, not defaulted: the file names `disk_head` from
+    // it (task 1004406), and an injected state must reach the beat that reports it.
+    try { beatFile(Date.now(), deps.state || RUNNER_STATE); } catch (_) { /* a runner that cannot write its file still runs */ }
     try { await beatServer(fields, deps); } catch (_) { /* and one that cannot reach the instance still runs */ }
   };
   // The running commit, read ONCE, BEFORE the first beat (task 1004397). It used
@@ -993,14 +1067,35 @@ async function forever(opts, deps = {}) {
     // spends nearly all of its time and an upgrade should not sit behind it.
     const upMs = (deps.now ? deps.now() : Date.now()) - Date.parse(RUNNER_STARTED_AT);
     const mayUpgrade = upMs >= MIN_UPTIME_BEFORE_UPGRADE_MS;
-    const drift = mayUpgrade
+    let drift = mayUpgrade
       ? (deps.codeDrifted ? await deps.codeDrifted(deps) : await codeDrifted(deps))
       : false;
     if (drift) {
-      log({ event: 'upgrade_exit', from: drift.from, to: drift.to,
-        reason: `main moved from ${drift.from} to ${drift.to} — exiting so the wrapper can relaunch on the new code` });
-      await beat({ mode: state.mode, last_event: 'upgrade_exit' });
-      return UPGRADE_EXIT_CODE;
+      // Pull always, restart rarely (task 1004406). Only main() arms the refresh.
+      let why = 'exiting so the wrapper can relaunch on the new code';
+      if (opts.refreshInPlace) {
+        const refreshed = await (deps.refreshCheckout || refreshCheckout)(deps);
+        if (refreshed && refreshed.ok) {
+          const touched = supervisorTouched(refreshed.changed, deps.loadedFiles ? deps.loadedFiles() : loadedFiles());
+          if (!touched.length) {
+            (deps.state || RUNNER_STATE).diskHead = refreshed.to;
+            log({ event: 'code_refreshed', from: drift.from, to: refreshed.to.slice(0, 8), changed: refreshed.changed.length,
+              reason: `main moved from ${drift.from} to ${refreshed.to.slice(0, 8)} — checkout updated in place; none of the ${refreshed.changed.length} changed file(s) is code this process runs, so no restart` });
+            await beat({ mode: state.mode, last_event: 'code_refreshed' });
+            drift = null;
+          } else {
+            const more = touched.length > 5 ? `, +${touched.length - 5} more` : '';
+            why = `it changed code this process runs (${touched.slice(0, 5).join(', ')}${more}) — exiting so the wrapper can relaunch on it`;
+          }
+        } else {
+          why = `the in-place refresh did not run (${(refreshed && refreshed.reason) || 'no result'}) — exiting so the wrapper's own refresh can`;
+        }
+      }
+      if (drift) {
+        log({ event: 'upgrade_exit', from: drift.from, to: drift.to, reason: `main moved from ${drift.from} to ${drift.to} — ${why}` });
+        await beat({ mode: state.mode, last_event: 'upgrade_exit' });
+        return UPGRADE_EXIT_CODE;
+      }
     }
 
     const { waited, jumped } = await wait(state.waitS, { ...deps, beat }, opts.cadence);
@@ -1015,7 +1110,7 @@ async function main(argv) {
   // it lived on the machine being fenced; the database owns that now, and an empty
   // `--goal` means "every allowlisted goal" rather than "anything claimable". The
   // refusal did not disappear — it moved somewhere the runner host cannot edit.
-  if (opts.forever) return forever(opts);
+  if (opts.forever) return forever({ ...opts, refreshInPlace: true });
 
   // The one-shot path, kept for an operator running a single task by hand. It
   // still reconciles first: a leftover claim is a leftover claim whoever is
@@ -1043,5 +1138,5 @@ module.exports = {
   worktreeName, readFence, reconcileLeftoverClaims, pollSignals, waitOrJump, forever, CLAIM_PREFIX, codeDrifted, loadedHead, UPGRADE_EXIT_CODE, MIN_UPTIME_BEFORE_UPGRADE_MS,
   heartbeatPath, writeHeartbeat, readHeartbeat, pidAlive, anotherRunnerIsAlive, HEARTBEAT_STALE_MS,
   isRunnerTree, RUNNER_TREE_RE, postHeartbeat, RUNNER_STARTED_AT, failureReason,
-  newRunnerState, LIMIT_UNKNOWN_RESET_MS, QUEUE_GATED_EXIT, CLAIM_SET_ASIDE_MS, MAX_CLAIM_ATTEMPTS, owedTaskIds,
+  newRunnerState, loadedFiles, supervisorTouched, refreshCheckout, LIMIT_UNKNOWN_RESET_MS, QUEUE_GATED_EXIT, CLAIM_SET_ASIDE_MS, MAX_CLAIM_ATTEMPTS, owedTaskIds,
 };

package/scripts/gds/module-assess-tests.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+// scripts/gds/module-assess-tests.js — the Tests part of a module's assessment:
+// run a published module version's OWN test suite and record the pass rate as a
+// module_assessment_signals row (task 1003791, ADR 0343; table from core_265).
+//
+// Why this cannot reuse the unit gate. run-unit-tests.js discovers
+// modules/<key>/tests/*.mjs but runs them only when isModuleEnabled(key) — and a
+// catalog module ships default:false (ADR 0107 §6), so every store module's tests
+// are skipped there by construction (the trap task 1003630 documented). This runs
+// the tests straight from the published TARBALL, with no enabled/disabled check at
+// all, so what is measured is exactly the build a buyer would install.
+//
+// Outcomes (core_265's vocabulary — a missing part is never a zero):
+//   scored      the module has tests and they ran: score = round(100 × files that
+//               passed / files run), sample_size = files run. The unit is a test
+//               FILE (one process, its exit code), the same unit the core gate uses.
+//   no_data     the module declares no tests — NOT a fail (the task says the two
+//               must not score the same).
+//   not_scored  the tarball could not be read or verified, so nothing could run.
+//
+// Where the tests run. A module's tests reach into the core by relative path
+// (`../../../docs/…`) and resolve packages from the core's node_modules, so the
+// module is unpacked at the same depth modules/<key>/ sits at:
+// <core root>/.module-assess-<run>/<key>/ — node's walk-up resolution then finds
+// the core with no junctions to create (and so none a cleanup could follow; see
+// worktree.js). Each file runs in its own node process, serially, with a timeout
+// and a stripped environment: no DATABASE_URL, tokens or keys are handed to
+// third-party code. That is a floor, not a sandbox: a test process can still read
+// any file the OS user can (the core's own .env sits two directories up) and reach
+// the network.
+//
+// SO A PUBLISHED MODULE'S TESTS RUN ONLY IN A SEPARATE TESTING ENVIRONMENT
+// (owner, 2026-09-30): never on the control plane, where the secrets live. The
+// store path (recordTestsSignal) refuses unless the process declares it is that
+// environment with MODULE_TEST_SANDBOX=1 — set only on the isolated test box, no
+// secrets on disk, which is its own task. `--dir` stays open: it runs a module
+// from your own checkout, i.e. code you already chose to run.
+//
+//   node scripts/gds/module-assess-tests.js <store_module_versions.id>   run + record
+//   node scripts/gds/module-assess-tests.js --dir modules/<key>          dry run on a
+//                                                                        local module
+//                                                                        (prints; no DB)
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFile } = require('node:child_process');
+const { isCleanTeardownAbort } = require('./run-unit-tests');
+
+const CORE_ROOT = path.resolve(__dirname, '..', '..');
+const PER_FILE_TIMEOUT_MS = 90_000; // the unit gate's own per-file cap
+const SANDBOX_PREFIX = '.module-assess-';
+// The only variables a module's test process inherits. PATH to find tools; the
+// Windows ones node needs to start at all; nothing that names a credential.
+const ENV_KEEP = ['PATH', 'Path', 'SystemRoot', 'SYSTEMROOT', 'windir', 'TEMP', 'TMP', 'TMPDIR', 'COMSPEC', 'PATHEXT'];
+
+// The module's test files: tests/*.mjs at the top of tests/, exactly what
+// run-unit-tests.js discovers for a module on disk. `files` is module-relative paths.
+function discoverTestFiles(paths) {
+  return paths.filter((p) => /^tests\/[^/]+\.mjs$/.test(p)).sort();
+}
+
+function testEnv(sandbox) {
+  const env = {};
+  for (const k of ENV_KEEP) if (process.env[k] !== undefined) env[k] = process.env[k];
+  env.NODE_ENV = 'test';
+  env.HOME = sandbox;
+  env.USERPROFILE = sandbox;
+  return env;
+}
+
+// Run one file; resolve { file, passed, timedOut, code, tail }. Never rejects.
+function runFile(file, { cwd, env, timeoutMs, exec = execFile }) {
+  return new Promise((resolve) => {
+    exec(process.execPath, [file], { cwd, env, timeout: timeoutMs, maxBuffer: 8 * 1024 * 1024, windowsHide: true },
+      (err, stdout, stderr) => {
+        const out = String(stdout || '');
+        const errText = String(stderr || '');
+        // A suite that passed but aborted in libuv teardown on Windows passed (task 1003845).
+        const passed = !err || isCleanTeardownAbort(out, errText);
+        const timedOut = !!(err && err.killed);
+        // Why it failed: the suite's last stdout lines (its verdict) and the HEAD of
+        // stderr, where node puts the thrown error — its tail is only the stack and version.
+        const lines = (t, n, fromEnd) => { const ls = t.split(/\r?\n/).filter((l) => l.trim()); return (fromEnd ? ls.slice(-n) : ls.slice(0, n)).join('\n'); };
+        const tail = passed ? '' : [lines(out, 3, true), lines(errText, 4, false)].filter(Boolean).join('\n').slice(0, 600);
+        resolve({ passed, timedOut, code: err ? (err.code ?? null) : 0, tail });
+      });
+  });
+}
+
+// Remove a sandbox this file made. It holds only real files written by placeFiles
+// (never a link), and the name check means a bad argument cannot aim this anywhere else.
+function removeSandbox(dir, root) {
+  if (!path.basename(dir).startsWith(SANDBOX_PREFIX) || path.dirname(dir) !== root) {
+    throw new Error(`refusing to remove ${dir}: not a module-assess sandbox`);
+  }
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+function placeFiles(files, target) {
+  for (const f of files) {
+    const dest = path.join(target, ...f.path.split('/'));
+    if (!dest.startsWith(target + path.sep)) throw new Error(`"${f.path}" would land outside the module`);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, f.buf);
+  }
+}
+
+// The gate in front of running module code. `trusted` is only for code you
+// already chose to run (a module in your own checkout, `--dir`). Anything else — a
+// published, third-party module — runs only where the process declares itself the
+// separate testing environment (MODULE_TEST_SANDBOX=1) AND nothing secret is
+// visible: no credential-looking variable in the environment, no .env at the core
+// root. The second half is what stops a mis-set flag on a real server from
+// quietly reopening the hole. Returns null (go) or { code, message }.
+const SECRET_ENV_RE = /(^DATABASE_URL$|^PG(PASSWORD|PASSFILE)$|TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY|_KEY$)/i;
+function inTestSandbox(env = process.env) {
+  return env.MODULE_TEST_SANDBOX === '1';
+}
+function runRefusal({ trusted = false, env = process.env, root = CORE_ROOT } = {}) {
+  if (trusted) return null;
+  if (!inTestSandbox(env)) {
+    return { code: 'not_in_test_sandbox', message: "refusing to run a published module's tests here: they run only in the separate testing environment (MODULE_TEST_SANDBOX=1), never on a server holding secrets" };
+  }
+  const leaked = Object.keys(env).filter((k) => SECRET_ENV_RE.test(k) && env[k]);
+  if (leaked.length || fs.existsSync(path.join(root, '.env'))) {
+    return { code: 'secrets_present', message: `refusing: MODULE_TEST_SANDBOX=1 is set but secrets are visible here (${leaked.length ? leaked.sort().join(', ') : '.env at the core root'}) — the testing environment must hold none` };
+  }
+  return null;
+}
+
+// Run a module's own tests from its files ([{ path, buf }], module-relative) and
+// return the signal fields: { outcome, score, sample_size, reason, detail }.
+// Pure apart from the sandbox it writes and removes; `exec` is injectable for tests.
+async function assessTests(key, files, { root = CORE_ROOT, timeoutMs = PER_FILE_TIMEOUT_MS, exec, trusted = false, env = process.env } = {}) {
+  // Checked here too, not only in recordTestsSignal, so no caller can reach the
+  // code that runs a module without passing the gate.
+  const refused = runRefusal({ trusted, env, root });
+  if (refused) throw Object.assign(new Error(refused.message), { code: refused.code });
+  const tests = discoverTestFiles(files.map((f) => f.path));
+  if (tests.length === 0) {
+    return { outcome: 'no_data', score: null, sample_size: 0, reason: 'the module declares no tests (no tests/*.mjs)', detail: { files: [] } };
+  }
+  const sandbox = path.join(root, `${SANDBOX_PREFIX}${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+  const moduleDir = path.join(sandbox, key);
+  try {
+    placeFiles(files, moduleDir);
+    const env = testEnv(sandbox);
+    const results = [];
+    for (const t of tests) {
+      // Serial on purpose, like the unit gate: tests share the core tree around them.
+      const r = await runFile(path.join(moduleDir, ...t.split('/')), { cwd: moduleDir, env, timeoutMs, exec });
+      results.push({ file: t, ...r });
+    }
+    const passed = results.filter((r) => r.passed).length;
+    const failed = results.filter((r) => !r.passed);
+    return {
+      outcome: 'scored',
+      score: Math.round((100 * passed) / results.length),
+      sample_size: results.length,
+      reason: failed.length ? `${failed.length} of ${results.length} test file(s) failed` : `all ${results.length} test file(s) passed`,
+      detail: { files: results.map(({ file, passed: ok, timedOut, tail }) => ({ file, passed: ok, ...(timedOut ? { timed_out: true } : {}), ...(tail ? { tail } : {}) })) },
+    };
+  } finally {
+    removeSandbox(sandbox, root);
+  }
+}
+
+// Append one Tests signal row for a store version. Never UPDATEs (core_265 is
+// append-only: the current result is the newest row per (version, part)).
+async function insertSignal(versionId, s, { db }) {
+  const { rows: [row] } = await db.query(
+    `INSERT INTO module_assessment_signals (version_id, part, outcome, score, sample_size, reason, detail)
+     VALUES ($1, 'tests', $2, $3, $4, $5, $6)
+     RETURNING id, version_id, part, outcome, score, sample_size, reason, measured_at`,
+    [versionId, s.outcome, s.score, s.sample_size, s.reason, JSON.stringify(s.detail || {})]);
+  return row;
+}
+
+// Read, verify and test one published version, then record the result. A tarball
+// that is missing or fails verification is recorded as not_scored — the part could
+// not be measured, which is not the same as the module failing its tests.
+async function recordTestsSignal(versionId, { db, storeDir, root, timeoutMs, exec, env = process.env } = {}) {
+  const refused = runRefusal({ env, root });
+  if (refused) return { ok: false, ...refused };
+  const pool = db || require('../../src/bongos/pool').pool;
+  const { versionArtifactFile } = require('../../src/bongos/module-store');
+  const { verifyModuleArtifact } = require('./module-artifact');
+  const { rows: [ver] } = await pool.query(
+    'SELECT id, module_key, version, artifact_path FROM store_module_versions WHERE id = $1', [versionId]);
+  if (!ver) return { ok: false, code: 'version_not_found', message: `no store_module_versions row ${versionId}` };
+
+  let signal;
+  try {
+    const file = versionArtifactFile(ver, storeDir ? { dir: storeDir } : {});
+    const tgz = await fs.promises.readFile(file);
+    const v = await verifyModuleArtifact(tgz, { key: ver.module_key, includeFiles: true });
+    signal = v.ok
+      ? await assessTests(ver.module_key, v.files, { root, timeoutMs, exec, env })
+      : { outcome: 'not_scored', score: null, sample_size: null, reason: `the tarball failed verification (${v.code}): ${v.message}`, detail: {} };
+  } catch (e) {
+    signal = { outcome: 'not_scored', score: null, sample_size: null, reason: `the tests could not run (${e.code || 'error'})`, detail: {} };
+  }
+  const row = await insertSignal(ver.id, signal, { db: pool });
+  return { ok: true, version: ver, signal: row };
+}
+
+// Local dry run: read modules/<key>/ from disk and print what the signal would be.
+function readModuleDir(dir) {
+  const out = [];
+  const walk = (rel) => {
+    for (const e of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
+      if (e.name === 'node_modules' || e.name === '.git') continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(r);
+      else if (e.isFile()) out.push({ path: r, buf: fs.readFileSync(path.join(dir, r)) });
+    }
+  };
+  walk('');
+  return out;
+}
+
+async function main(argv) {
+  const i = argv.indexOf('--dir');
+  if (i !== -1) {
+    const dir = path.resolve(argv[i + 1] || '');
+    const key = JSON.parse(fs.readFileSync(path.join(dir, 'module.json'), 'utf8')).key;
+    const s = await assessTests(key, readModuleDir(dir), { trusted: true });
+    console.log(JSON.stringify(s, null, 2));
+    return 0;
+  }
+  const id = argv[0];
+  if (!/^\d+$/.test(String(id || ''))) {
+    console.error('usage: node scripts/gds/module-assess-tests.js <store_module_versions.id> | --dir modules/<key>');
+    return 2;
+  }
+  const res = await recordTestsSignal(id);
+  if (!res.ok) { console.error(res.message); return 1; }
+  const s = res.signal;
+  console.log(`${res.version.module_key} ${res.version.version}: tests ${s.outcome}${s.score !== null ? ` ${s.score}/100` : ''} — ${s.reason} (signal ${s.id})`);
+  return 0;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => process.exit(code), (e) => { console.error(e.stack || e.message); process.exit(1); });
+}
+
+module.exports = { discoverTestFiles, assessTests, recordTestsSignal, insertSignal, runRefusal, testEnv, SANDBOX_PREFIX };

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.20.36'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.37'; // 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/autobongos_loop.mjs

@@ -1084,6 +1084,211 @@ test('a runner that just started will NOT upgrade-exit, so a failed fetch cannot
   assert.equal(askedForDrift, false, 'and not even ask — the check costs a network call');
 });
 
+// --- pull always, restart rarely (task 1004406) -----------------------------
+//
+// Owner-approved 2026-09-30: restart only when the supervisor's OWN code changes.
+// Every worker is a fresh process in its own tree, so it runs whatever is on disk
+// already; the only code a restart refreshes is what THIS process has loaded.
+// So on drift the checkout is updated in place, and the process exits for the
+// wrapper only when a change touches a file it holds in memory.
+
+const loopDeps = (over = {}) => ({
+  iteration: async () => ({ event: 'hold', reason: 'test' }),
+  reconcileLeftoverClaims: async () => ({ event: 'boot_reconcile', ok: true }),
+  waitOrJump: async () => ({ waited: 0, jumped: false }),
+  writeHeartbeat: () => true,
+  postHeartbeat: async () => true,
+  emit: () => {},
+  loadedHead: async () => 'a'.repeat(40),
+  now: () => Date.now() + runner.MIN_UPTIME_BEFORE_UPGRADE_MS + 1000,
+  codeDrifted: async () => ({ from: 'aaaaaaaa', to: 'cccccccc' }),
+  loadedFiles: () => ['scripts/gds/autobongos-run.js', 'scripts/gds/sequence.js'],
+  state: runner.newRunnerState(),
+  ...over,
+});
+
+test('main moving with none of the supervisor\'s code refreshes the checkout IN PLACE and does not restart', async () => {
+  const rows = [];
+  let refreshed = 0;
+  const d = loopDeps({
+    record: (r) => { rows.push(r); return r; },
+    refreshCheckout: async () => { refreshed += 1; return { ok: true, to: 'c'.repeat(40), changed: ['docs/recipes/x.md', 'src/bongos/routes/tasks.js'] }; },
+  });
+  const code = await runner.forever({ goals: [], maxTasks: 1, maxLoops: 2, refreshInPlace: true }, d);
+  assert.equal(code, 0, 'no restart for code the supervisor does not run');
+  assert.ok(refreshed >= 1, 'the checkout is brought current, so workers run the new code');
+  assert.ok(rows.some((r) => r.event === 'code_refreshed'), 'and the refresh is logged');
+  assert.ok(!rows.some((r) => r.event === 'upgrade_exit'));
+  assert.equal(d.state.diskHead, 'c'.repeat(40), 'the on-disk commit is remembered apart from the loaded one');
+});
+
+test('a change to a file the supervisor has LOADED restarts, and says which file', async () => {
+  const rows = [];
+  const code = await runner.forever({ goals: [], maxTasks: 1, maxLoops: 2, refreshInPlace: true }, loopDeps({
+    record: (r) => { rows.push(r); return r; },
+    refreshCheckout: async () => ({ ok: true, to: 'c'.repeat(40), changed: ['docs/x.md', 'scripts/gds/sequence.js'] }),
+  }));
+  assert.equal(code, runner.UPGRADE_EXIT_CODE);
+  const exit = rows.find((r) => r.event === 'upgrade_exit');
+  assert.match(exit.reason, /scripts\/gds\/sequence\.js/);
+  assert.ok(!/docs\/x\.md/.test(exit.reason), 'only the files that force the restart are named');
+});
+
+test('a change under the supervisor\'s own paths restarts even before that file was loaded', async () => {
+  const code = await runner.forever({ goals: [], maxTasks: 1, maxLoops: 2, refreshInPlace: true }, loopDeps({
+    record: (r) => r,
+    loadedFiles: () => [],
+    refreshCheckout: async () => ({ ok: true, to: 'c'.repeat(40), changed: ['modules/autonomy/cadence.js'] }),
+  }));
+  assert.equal(code, runner.UPGRADE_EXIT_CODE);
+});
+
+test('an in-place refresh that fails falls back to the restart, which re-runs the wrapper\'s refresh', async () => {
+  const rows = [];
+  const code = await runner.forever({ goals: [], maxTasks: 1, maxLoops: 2, refreshInPlace: true }, loopDeps({
+    record: (r) => { rows.push(r); return r; },
+    refreshCheckout: async () => ({ ok: false, reason: 'fetch failed' }),
+  }));
+  assert.equal(code, runner.UPGRADE_EXIT_CODE);
+  assert.match(rows.find((r) => r.event === 'upgrade_exit').reason, /fetch failed/);
+});
+
+test('the real --forever entry point is the one place that arms the in-place refresh', () => {
+  // main() is the production call shape and is not driven by these tests (it
+  // would run the real loop), so its one line is pinned by source. Without it the
+  // refresh is dead code and every merge to main restarts the runner again.
+  const src = readFileSync(new URL('../scripts/gds/autobongos-run.js', import.meta.url), 'utf8');
+  const line = src.split('\n').find((l) => l.includes('if (opts.forever) return forever('));
+  assert.ok(line, 'main() must still hand --forever to forever()');
+  assert.ok(line.includes('refreshInPlace: true'), `and arm the refresh there: ${line}`);
+});
+
+test('without refreshInPlace, forever never touches the checkout — tests and one-shot runs stay safe', async () => {
+  // refreshCheckout runs `git reset --hard`. A suite that reached it would wipe
+  // the tree it is testing, in CI or on a laptop, so only main() arms it.
+  const code = await runner.forever({ goals: [], maxTasks: 1, maxLoops: 2 }, loopDeps({
+    record: (r) => r,
+    refreshCheckout: async () => { throw new Error('refreshed a checkout it was never told it owns'); },
+  }));
+  assert.equal(code, runner.UPGRADE_EXIT_CODE);
+});
+
+test('after a refresh, drift is measured from the REFRESHED commit, so it does not refresh every loop', async () => {
+  const tip = 'c'.repeat(40);
+  const run = async () => ({ ok: true, stdout: `${tip}\trefs/heads/main\n` });
+  assert.equal(await runner.codeDrifted({ run, loadedHead: async () => 'a'.repeat(40), state: { diskHead: tip } }), false);
+  const moved = await runner.codeDrifted({ run, loadedHead: async () => 'a'.repeat(40), state: { diskHead: 'b'.repeat(40) } });
+  assert.deepEqual(moved, { from: 'bbbbbbbb', to: 'cccccccc' });
+});
+
+test('supervisorTouched: loaded files and the supervisor\'s own paths count; nothing else does', () => {
+  const loaded = ['scripts/gds/sequence.js'];
+  assert.deepEqual(runner.supervisorTouched(['docs/a.md', 'src/x.js'], loaded), []);
+  assert.deepEqual(runner.supervisorTouched(['scripts/gds/sequence.js'], loaded), ['scripts/gds/sequence.js']);
+  assert.deepEqual(runner.supervisorTouched(['scripts/gds/autobongos-verify.js'], []), ['scripts/gds/autobongos-verify.js']);
+  assert.deepEqual(runner.supervisorTouched(['modules/autonomy/fence.js'], []), ['modules/autonomy/fence.js']);
+  assert.deepEqual(runner.supervisorTouched(['scripts/gds/claim.js'], loaded), [], 'claim.js runs as a child process, so it is always fresh');
+});
+
+test('loadedFiles lists this process\'s own repo modules, repo-relative with forward slashes', () => {
+  const files = runner.loadedFiles();
+  assert.ok(files.includes('scripts/gds/autobongos-run.js'));
+  assert.ok(files.every((f) => !f.includes('\\') && !f.startsWith('/') && !f.includes('node_modules/')));
+});
+
+test('refreshCheckout refuses to reset anything but the MAIN checkout', async () => {
+  const calls = [];
+  // Everything else answers as a healthy main checkout would, so the ONLY thing
+  // that can stop the reset is the worktree check itself.
+  const run = async (bin, args) => {
+    calls.push(args.join(' '));
+    if (args[1] === '--git-dir') return { ok: true, stdout: '/repo/.git/worktrees/some-claim\n' };
+    if (args[1] === '--git-common-dir') return { ok: true, stdout: '/repo/.git\n' };
+    if (args[0] === 'rev-parse' && args[1] === 'FETCH_HEAD') return { ok: true, stdout: `${'c'.repeat(40)}\n` };
+    if (args[0] === 'diff') return { ok: true, stdout: 'docs/a.md\n' };
+    return { ok: true, stdout: '' };
+  };
+  const r = await runner.refreshCheckout({ run, loadedHead: async () => 'a'.repeat(40) });
+  assert.equal(r.ok, false);
+  assert.ok(!calls.some((c) => c.startsWith('reset')), 'a linked worktree is somebody\'s claim — never reset it');
+});
+
+test('refreshCheckout in the main checkout fetches, diffs from the LOADED commit, then resets', async () => {
+  const calls = [];
+  const tip = 'c'.repeat(40);
+  const run = async (bin, args) => {
+    calls.push(args.join(' '));
+    if (args[1] === '--git-dir' || args[1] === '--git-common-dir') return { ok: true, stdout: '.git\n' };
+    if (args[0] === 'rev-parse' && args[1] === 'FETCH_HEAD') return { ok: true, stdout: `${tip}\n` };
+    if (args[0] === 'diff') return { ok: true, stdout: 'docs/a.md\r\nscripts/gds/sequence.js\n' };
+    return { ok: true, stdout: '' };
+  };
+  const r = await runner.refreshCheckout({ run, loadedHead: async () => 'a'.repeat(40) });
+  assert.deepEqual(r, { ok: true, to: tip, changed: ['docs/a.md', 'scripts/gds/sequence.js'] });
+  const order = ['fetch', 'diff', 'reset'].map((v) => calls.findIndex((c) => c.startsWith(v)));
+  assert.ok(order.every((i) => i >= 0) && order[0] < order[1] && order[1] < order[2], `fetch → diff → reset, got ${calls.join(' | ')}`);
+  assert.ok(calls.find((c) => c.startsWith('diff')).includes('a'.repeat(40)), 'the diff is from what the process LOADED, so a change that landed several refreshes ago still counts');
+});
+
+// Each way the refresh can bail must bail BEFORE the reset: a half-done refresh
+// that resets to an unread or undiffed commit would lose the restart decision.
+for (const [name, failAt] of [
+  ['the running commit is unknown', 'loaded'],
+  ['fetch failed', 'fetch'],
+  ['could not read the fetched commit', 'FETCH_HEAD'],
+  ['could not diff the running commit against main', 'diff'],
+]) {
+  test(`refreshCheckout bails without resetting when: ${name}`, async () => {
+    const calls = [];
+    const run = async (bin, args) => {
+      calls.push(args.join(' '));
+      if (args[1] === '--git-dir' || args[1] === '--git-common-dir') return { ok: true, stdout: '.git\n' };
+      if (args[0] === 'fetch') return { ok: failAt !== 'fetch', stdout: '' };
+      if (args[0] === 'rev-parse' && args[1] === 'FETCH_HEAD') return { ok: true, stdout: failAt === 'FETCH_HEAD' ? 'not-a-sha\n' : `${'c'.repeat(40)}\n` };
+      if (args[0] === 'diff') return { ok: failAt !== 'diff', stdout: 'docs/a.md\n' };
+      return { ok: true, stdout: '' };
+    };
+    const r = await runner.refreshCheckout({ run, loadedHead: async () => (failAt === 'loaded' ? null : 'a'.repeat(40)) });
+    assert.deepEqual(r, { ok: false, reason: name });
+    assert.ok(!calls.some((c) => c.startsWith('reset')), `no reset after "${name}"`);
+  });
+}
+
+test('a refresh in place reaches the heartbeat FILE through the real beat — disk_head end to end', async () => {
+  // The grader's catch: every forever() test stubbed writeHeartbeat, so the
+  // state never had to travel from the refresh to the file. This one does not.
+  const dir = mkdtempSync(join(tmpdir(), 'ab-diskhead-e2e-'));
+  const prev = process.env.AUTOBONGOS_HEARTBEAT_FILE;
+  process.env.AUTOBONGOS_HEARTBEAT_FILE = join(dir, 'beat.json');
+  try {
+    const d = loopDeps({
+      record: (r) => r,
+      refreshCheckout: async () => ({ ok: true, to: 'e'.repeat(40), changed: ['docs/a.md'] }),
+    });
+    delete d.writeHeartbeat;
+    await runner.forever({ goals: [], maxTasks: 1, maxLoops: 2, refreshInPlace: true }, d);
+    const beat = JSON.parse(readFileSync(process.env.AUTOBONGOS_HEARTBEAT_FILE, 'utf8'));
+    assert.equal(beat.disk_head, 'e'.repeat(40));
+  } finally {
+    if (prev === undefined) delete process.env.AUTOBONGOS_HEARTBEAT_FILE; else process.env.AUTOBONGOS_HEARTBEAT_FILE = prev;
+  }
+});
+
+test('the heartbeat file names the on-disk commit when it differs from the running one', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'ab-diskhead-'));
+  const prev = process.env.AUTOBONGOS_HEARTBEAT_FILE;
+  process.env.AUTOBONGOS_HEARTBEAT_FILE = join(dir, 'beat.json');
+  try {
+    runner.writeHeartbeat(Date.now(), { diskHead: 'd'.repeat(40) });
+    const beat = JSON.parse(readFileSync(process.env.AUTOBONGOS_HEARTBEAT_FILE, 'utf8'));
+    assert.equal(beat.disk_head, 'd'.repeat(40), '"up to date on disk, old supervisor" must be visible');
+    runner.writeHeartbeat(Date.now(), { diskHead: null });
+    assert.equal(JSON.parse(readFileSync(process.env.AUTOBONGOS_HEARTBEAT_FILE, 'utf8')).disk_head, undefined);
+  } finally {
+    if (prev === undefined) delete process.env.AUTOBONGOS_HEARTBEAT_FILE; else process.env.AUTOBONGOS_HEARTBEAT_FILE = prev;
+  }
+});
+
 test('past the uptime floor, a drift still exits', async () => {
   const code = await runner.forever({ goals: [], maxTasks: 1, maxLoops: 2 }, {
     iteration: async () => ({ event: 'hold', reason: 'test' }),

package/tests/module_assess_tests.mjs

@@ -0,0 +1,232 @@
+// tests/module_assess_tests.mjs — the Tests assessment signal (task 1003791, ADR 0343).
+// No database: the module's tests really run (real node child processes, from a REAL
+// packed tarball verified by module-artifact.js), and the signal row goes to a fake
+// pg client, so what is pinned is the outcome vocabulary core_265 stores:
+//   no tests      -> no_data, never a fail
+//   tests ran     -> scored, round(100 x passing files / files), sample_size = files
+//   unreadable    -> not_scored
+// plus the two safety properties: the sandbox is always removed, and a module's test
+// process never inherits the parent's credentials. And it runs regardless of whether
+// the module is enabled — nothing here consults isModuleEnabled.
+//
+// Run:  node tests/module_assess_tests.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';
+
+const require = createRequire(import.meta.url);
+const { discoverTestFiles, assessTests, recordTestsSignal, insertSignal, runRefusal, testEnv, SANDBOX_PREFIX } = require('../scripts/gds/module-assess-tests.js');
+const { packModule, verifyModuleArtifact } = require('../scripts/gds/module-artifact.js');
+const { relativeArtifactPath } = require('../src/bongos/module-store.js');
+
+const PASS = "import assert from 'node:assert'; assert.equal(1 + 1, 2); console.log('1 passed, 0 failed');\n";
+const FAIL = "import assert from 'node:assert'; assert.equal(1 + 1, 3);\n";
+const file = (p, text) => ({ path: p, buf: Buffer.from(text) });
+const tmpRoot = () => fs.mkdtempSync(path.join(os.tmpdir(), 'mod-assess-root-'));
+const sandboxesIn = (root) => fs.readdirSync(root).filter((n) => n.startsWith(SANDBOX_PREFIX));
+
+test('only tests/*.mjs at the top of tests/ count, as in the unit gate', () => {
+  assert.deepEqual(
+    discoverTestFiles(['module.json', 'tests/b.mjs', 'tests/a.mjs', 'tests/fixtures/x.mjs', 'tests/helper.js', 'lib/tests/c.mjs']),
+    ['tests/a.mjs', 'tests/b.mjs']);
+});
+
+test('a module that declares no tests is no_data, not a fail', async () => {
+  const root = tmpRoot();
+  const s = await assessTests('weather', [file('module.json', '{}'), file('index.js', '')], { trusted: true, root });
+  assert.equal(s.outcome, 'no_data');
+  assert.equal(s.score, null, 'no_data carries no number (core_265: score exactly when scored)');
+  assert.equal(s.sample_size, 0);
+  assert.match(s.reason, /declares no tests/);
+  assert.deepEqual(sandboxesIn(root), [], 'nothing is unpacked when there is nothing to run');
+});
+
+test('all passing scores 100; one of two failing scores 50', async () => {
+  const root = tmpRoot();
+  const all = await assessTests('weather', [file('tests/a.mjs', PASS), file('tests/b.mjs', PASS)], { trusted: true, root });
+  assert.equal(all.outcome, 'scored');
+  assert.equal(all.score, 100);
+  assert.equal(all.sample_size, 2);
+
+  const half = await assessTests('weather', [file('tests/a.mjs', PASS), file('tests/b.mjs', FAIL)], { trusted: true, root });
+  assert.equal(half.outcome, 'scored');
+  assert.equal(half.score, 50);
+  assert.equal(half.sample_size, 2);
+  assert.match(half.reason, /1 of 2/);
+  const failed = half.detail.files.find((f) => f.file === 'tests/b.mjs');
+  assert.equal(failed.passed, false);
+  assert.match(failed.tail, /AssertionError|assert/i, 'a failing file keeps a bounded tail of why');
+  assert.deepEqual(sandboxesIn(root), [], 'the sandbox is removed after every run');
+});
+
+test('every failing still scores 0 — distinct from no_data', async () => {
+  const s = await assessTests('weather', [file('tests/a.mjs', FAIL)], { trusted: true, root: tmpRoot() });
+  assert.equal(s.outcome, 'scored');
+  assert.equal(s.score, 0);
+});
+
+test('a module test reaches its own files by relative path, at the modules/<key>/ depth', async () => {
+  const s = await assessTests('weather', [
+    file('lib/add.js', 'module.exports = (a, b) => a + b;\n'),
+    file('tests/a.mjs', "import { createRequire } from 'node:module'; import assert from 'node:assert';\nconst add = createRequire(import.meta.url)('../lib/add.js'); assert.equal(add(2, 2), 4);\n"),
+  ], { trusted: true, root: tmpRoot() });
+  assert.equal(s.score, 100, JSON.stringify(s.detail));
+});
+
+test('a module test process never inherits the parent\'s credentials', async () => {
+  process.env.DATABASE_URL = 'postgres://secret@host/db';
+  process.env.BONGOS_TOKEN = 'secret-token';
+  try {
+    const s = await assessTests('weather', [file('tests/env.mjs',
+      "import assert from 'node:assert'; assert.equal(process.env.DATABASE_URL, undefined); assert.equal(process.env.BONGOS_TOKEN, undefined); assert.equal(process.env.NODE_ENV, 'test');\n")],
+      { trusted: true, root: tmpRoot() });
+    assert.equal(s.score, 100, JSON.stringify(s.detail));
+  } finally {
+    delete process.env.DATABASE_URL;
+    delete process.env.BONGOS_TOKEN;
+  }
+});
+
+test('a hung test file is killed at the timeout and counted as failed', async () => {
+  const s = await assessTests('weather', [file('tests/hang.mjs', 'setInterval(() => {}, 1000);\n'), file('tests/ok.mjs', PASS)],
+    { trusted: true, root: tmpRoot(), timeoutMs: 1500 });
+  assert.equal(s.score, 50);
+  assert.equal(s.detail.files.find((f) => f.file === 'tests/hang.mjs').timed_out, true);
+});
+
+// ---- recordTestsSignal: tarball in, one appended row out ----
+
+const SANDBOX_ENV = { MODULE_TEST_SANDBOX: '1', PATH: process.env.PATH, SystemRoot: process.env.SystemRoot };
+
+test('outside the separate testing environment, a published module is never run', async () => {
+  let ran = false;
+  const db = { async query() { ran = true; return { rows: [] }; } };
+  for (const env of [{}, { MODULE_TEST_SANDBOX: 'true' }, { MODULE_TEST_SANDBOX: '0' }]) {
+    const res = await recordTestsSignal(42, { db, env, root: tmpRoot() });
+    assert.equal(res.ok, false);
+    assert.equal(res.code, 'not_in_test_sandbox');
+  }
+  assert.equal(ran, false, 'refused before reading the store or the tarball');
+});
+
+test('the test environment keeps no credential and pins HOME to the sandbox', () => {
+  process.env.SOME_API_KEY = 'x';
+  try {
+    const env = testEnv('/sb');
+    assert.equal(env.SOME_API_KEY, undefined);
+    assert.equal(env.HOME, '/sb');
+    assert.equal(env.NODE_ENV, 'test');
+  } finally { delete process.env.SOME_API_KEY; }
+});
+
+function fakeDb(versionRow) {
+  const inserts = [];
+  return {
+    inserts,
+    async query(sql, params) {
+      if (/FROM store_module_versions/.test(sql)) return { rows: versionRow ? [versionRow] : [] };
+      if (/INSERT INTO module_assessment_signals/.test(sql)) {
+        assert.doesNotMatch(sql, /UPDATE/i, 'append-only');
+        inserts.push(params);
+        const [version_id, outcome, score, sample_size, reason] = params;
+        return { rows: [{ id: 7, version_id, part: 'tests', outcome, score, sample_size, reason, measured_at: new Date() }] };
+      }
+      throw new Error(`unexpected query: ${sql}`);
+    },
+  };
+}
+
+function publishedFixture(extraFiles) {
+  const src = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-assess-src-'));
+  const dir = path.join(src, 'weather');
+  fs.mkdirSync(path.join(dir, 'tests'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'module.json'), JSON.stringify({ key: 'weather', title: 'Weather', description: 'x', version: '1.2.0', coreVersion: '^1.0.0', contributes: {} }));
+  for (const [p, text] of Object.entries(extraFiles)) fs.writeFileSync(path.join(dir, ...p.split('/')), text);
+  const { tgz } = packModule('weather', { modulesDir: src, now: () => new Date('2026-09-30T00:00:00Z'), modeOf: () => '644' });
+  const storeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-assess-store-'));
+  const final = path.join(storeDir, 'weather', 'weather-1.2.0.tgz');
+  fs.mkdirSync(path.dirname(final), { recursive: true });
+  fs.writeFileSync(final, tgz);
+  return { storeDir, final, row: { id: 42, module_key: 'weather', version: '1.2.0', artifact_path: relativeArtifactPath(final, { dir: storeDir }) } };
+}
+
+test('a published version is tested from its tarball and one tests row is appended', async () => {
+  const { storeDir, row } = publishedFixture({ 'tests/a.mjs': PASS, 'tests/b.mjs': FAIL });
+  const db = fakeDb(row);
+  const res = await recordTestsSignal(42, { db, storeDir, root: tmpRoot(), env: SANDBOX_ENV });
+  assert.equal(res.ok, true);
+  assert.equal(db.inserts.length, 1);
+  const [versionId, outcome, score, sample, , detail] = db.inserts[0];
+  assert.equal(versionId, 42);
+  assert.equal(outcome, 'scored');
+  assert.equal(score, 50);
+  assert.equal(sample, 2);
+  assert.equal(JSON.parse(detail).files.length, 2);
+});
+
+test('a version whose tarball is missing or tampered is not_scored, not failed', async () => {
+  const { storeDir, final, row } = publishedFixture({ 'tests/a.mjs': PASS });
+  fs.writeFileSync(final, Buffer.from('not a tarball'));
+  const db = fakeDb(row);
+  const res = await recordTestsSignal(42, { db, storeDir, root: tmpRoot(), env: SANDBOX_ENV });
+  assert.equal(res.ok, true);
+  const [, outcome, score] = db.inserts[0];
+  assert.equal(outcome, 'not_scored');
+  assert.equal(score, null);
+
+  fs.rmSync(final);
+  const db2 = fakeDb(row);
+  await recordTestsSignal(42, { db: db2, storeDir, root: tmpRoot(), env: SANDBOX_ENV });
+  assert.equal(db2.inserts[0][1], 'not_scored');
+  assert.doesNotMatch(db2.inserts[0][4], /[\/]/, 'the stored reason carries an error code, never a local path');
+});
+
+test('an unknown version writes nothing', async () => {
+  const db = fakeDb(null);
+  const res = await recordTestsSignal(99, { db, root: tmpRoot(), env: SANDBOX_ENV });
+  assert.equal(res.ok, false);
+  assert.equal(res.code, 'version_not_found');
+  assert.equal(db.inserts.length, 0);
+});
+
+test('the runner never consults whether the module is enabled', () => {
+  const src = fs.readFileSync(new URL('../scripts/gds/module-assess-tests.js', import.meta.url), 'utf8').replace(/\/\/.*$/gm, '');
+  assert.doesNotMatch(src, /isModuleEnabled/);
+});
+
+test('the sandbox dir is gitignored in case a run is killed mid-way', () => {
+  const gi = fs.readFileSync(new URL('../.gitignore', import.meta.url), 'utf8');
+  assert.match(gi, /^\/\.module-assess-\*\/$/m);
+});
+
+test('the gate lives in the runner itself: assessTests refuses untrusted code outside the testing environment', async () => {
+  const root = tmpRoot();
+  await assert.rejects(assessTests('weather', [file('tests/a.mjs', PASS)], { root, env: {} }), { code: 'not_in_test_sandbox' });
+  assert.deepEqual(sandboxesIn(root), [], 'refused before anything is unpacked');
+});
+
+test('a mis-set flag on a machine that holds secrets is still refused', async () => {
+  const root = tmpRoot();
+  for (const k of ['DATABASE_URL', 'BONGOS_TOKEN', 'STRIPE_SECRET', 'OPENAI_API_KEY']) {
+    assert.equal(runRefusal({ env: { ...SANDBOX_ENV, [k]: 'x' }, root }).code, 'secrets_present', k);
+  }
+  assert.equal(runRefusal({ env: SANDBOX_ENV, root }), null, 'a clean testing environment may run');
+  fs.writeFileSync(path.join(root, '.env'), 'DATABASE_URL=x\n');
+  assert.equal(runRefusal({ env: SANDBOX_ENV, root }).code, 'secrets_present', 'a .env at the core root counts');
+  await assert.rejects(assessTests('weather', [file('tests/a.mjs', PASS)], { root, env: SANDBOX_ENV }), { code: 'secrets_present' });
+  assert.equal(runRefusal({ trusted: true, env: {}, root }), null, 'your own checkout (--dir) is trusted');
+});
+
+test('insertSignal appends exactly one tests row with the signal fields', async () => {
+  const seen = [];
+  const db = { async query(sql, params) { seen.push({ sql, params }); return { rows: [{ id: 1 }] }; } };
+  await insertSignal(5, { outcome: 'scored', score: 80, sample_size: 5, reason: 'r', detail: { files: [] } }, { db });
+  assert.equal(seen.length, 1);
+  assert.match(seen[0].sql, /INSERT INTO module_assessment_signals[\s\S]*'tests'/);
+  assert.doesNotMatch(seen[0].sql, /UPDATE/i);
+  assert.deepEqual(seen[0].params, [5, 'scored', 80, 5, 'r', '{"files":[]}']);
+});