@bongos/core 1.19.997 → 1.19.999

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.997",
-  "core_contract": "1.19.997",
-  "source_commit": "e3e7048278119785fc3a9a9ca14edefba9ecae54",
+  "core_version": "1.19.999",
+  "core_contract": "1.19.999",
+  "source_commit": "60aa46906678b6454efb0a03da809680add5dfb0",
   "source_ref": "HEAD",
-  "built_at": "2026-09-24T00:11:45.316Z",
+  "built_at": "2026-09-24T01:15:07.815Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 520,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2952,
-  "tree_sha256": "ce61953a922e8482ee9341329d06ba7a71aa4367e0449c4d9a9990de9ff82e23",
+  "tree_sha256": "72dc4200fb45a7287362a518d9c090f733a2102a337dfb44e799bccede6aac6b",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -222,7 +222,7 @@
     {
       "path": ".claude/skills/read-session-export/SKILL.md",
       "mode": "0000644",
-      "sha256": "060811040144266504a206156422b6166b6cf5c7a2cd1f38c52b117ab4b5e0d6"
+      "sha256": "594d32ef63be2b45c360210ad004fc14e6dae889af97d47d72aac6a738fe1878"
     },
     {
       "path": ".claude/skills/recall/SKILL.md",
@@ -2132,7 +2132,7 @@
     {
       "path": "docs/adr/0327-a-cloud-host-runs-on-the-owners-account-and-the-key-is-borrowed.md",
       "mode": "0000644",
-      "sha256": "2c80244a082fb8c907bc83690724dbfb775adc35da124977668d8e56425d99b2"
+      "sha256": "9ebd9e4b3cb71f3ee4c5e06cdad04471ab07988744263fef7cd40a403b296b0b"
     },
     {
       "path": "docs/adr/0328-a-hosted-projects-authority-is-its-membership-row-not-its-owner-column.md",
@@ -2717,7 +2717,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "1b16fcc54d5a5c01d44d93ff307eef44ddec9a993bd81db0d41db4b71f4e5654"
+      "sha256": "c86c94695d5011b11ecdccab22f443c99acd980521036c7137b3a4675477e285"
     },
     {
       "path": "docs/modules-contract.md",
@@ -8187,12 +8187,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "93a81b5f6bc16e21a3ad6abd52490ccfbefe0f2d11af8dfd6273f03dd0c91ca0"
+      "sha256": "998ead97b5036645157cf13f31f69b6d942c7734e4b333871921dc846f0a6892"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "fe2540636dec8118f88d3c037c991fb3f9f784a72edec9569ecce1f09ec4ab97"
+      "sha256": "4048e352f641c0e350cec53aa32fcbb2f5b7396fd88d3c0a1e87c26140eec28b"
     },
     {
       "path": "public-docs/index.html",
@@ -9147,7 +9147,7 @@
     {
       "path": "scripts/gds/provision-core-upgrade.js",
       "mode": "0000644",
-      "sha256": "9d6ef473dcf4b9d8bbaa8c5a796d8d21f761b3732a0279981ff9e60aadf25919"
+      "sha256": "70ee5d90d63c8b7de938bb22c7a2e49154f5e80ce7e4ac78d180148017a09e74"
     },
     {
       "path": "scripts/gds/provision-disconnect.js",
@@ -10237,7 +10237,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "aa4d373556efe35c070f90b0ff308b302fbb9887f06cd3655d0fb9df8b157faa"
+      "sha256": "90d976ef4d2c73ae26c2d8ea4d0db083e6105b6c385a3abcc17a8e853886975c"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11152,7 +11152,7 @@
     {
       "path": "tests/core_upgrade_runner.mjs",
       "mode": "0000644",
-      "sha256": "47618fa0dd42bfa8f542b6830c3e68b715e655280f9aaf6684085478b257d497"
+      "sha256": "104ff5419638902eb272d15040a8fe69c4e1d14c38c7a977b1c2fd64c3cadd11"
     },
     {
       "path": "tests/cosmos_token_contrast.mjs",

package/.claude/skills/read-session-export/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: read-session-export
 description: >-
-  Read a Claude Code /export zip — conversation, thinking, and tool calls — to answer questions about a past session. READS an existing export, never creates one. Local and read-only. Triggers: a dropped session-export-*.zip, "read this session", "what happened in this session", "what was I/you thinking here", "summarize this export", "read the latest session export", "/read-session-export".
+  Read a Claude Code /export zip — conversation, thinking, tool calls — to answer questions about a past session. READS an existing export, never creates one. Triggers: a dropped session-export-*.zip, "read/summarize this session", "what happened in this session", "what was I/you thinking", "/read-session-export".
 ---
 
-The user already has the zip — Claude Code's built-in `/export` made it. Your job is to **read it well**: a session export is the same shape every time, so don't go spelunking through it by hand or load the megabytes of debug logs. Run the reader, which prints a compact transcript (prompts + thinking + replies + one-line tool calls) to stdout, then answer whatever the user actually asked.
+The user already has the zip — Claude Code's built-in `/export` made it. Read it with the reader rather than by hand: it prints a compact transcript (prompts + thinking + replies + one-line tool calls) to stdout and skips the megabytes of debug logs.
 
 ```bash
-node scripts/gds/read-session-export.js <export.zip>     # read it (compact transcript → stdout)
+node scripts/gds/read-session-export.js <export.zip>     # compact transcript → stdout
 node scripts/gds/read-session-export.js --latest         # newest session-export-*.zip in ~/Downloads
 ```
 
-Then **read that output and respond to the user's real intent** — summarize the session, pull out the reasoning behind a decision, find where something went wrong, list what was built. Don't just paste the transcript back; that's the raw material, not the answer.
+Then **answer what the user actually asked** — summarize the session, pull out the reasoning behind a decision, find where something went wrong, list what was built. Don't paste the transcript back; that's the raw material, not the answer.
 
 ## Pick the right depth (it's fast either way)
 
@@ -22,38 +22,14 @@ Then **read that output and respond to the user's real intent** — summarize th
 | Normal "read / summarize this session" | _(no flag)_ — compact transcript, tool results clipped |
 | "I need the full tool output / exact text" | `--full` (loosens the result clipping) |
 
-For a long session (a `--meta` showing hundreds of tool calls / thousands of lines), start with `--meta`, then `--thoughts` or a targeted read — don't dump the whole thing into context if the user only wants the gist.
+**A long export is a file, not a dump.** Always open with `--meta`; if it reports hundreds of tool calls, redirect to your session's scratchpad directory and read it in slices, rather than pouring thousands of lines into context at once:
 
-## What you're reading (the constant layout)
-
-A `/export` zip is identical every time, which is why this is reliable:
-
-- `metadata.json` — model, effort, title, cwd, branch, timestamps.
-- `<cliSessionId>.jsonl` — **the transcript**, one JSON record per line. Assistant records carry `content[]` blocks of type `thinking` (the thoughts), `text` (the reply), and `tool_use`; the matching `tool_result` rides in the next `user` record. The reader stitches these together.
-- `<cliSessionId>/subagents/agent-*.jsonl` — subagent transcripts (rendered after the main one).
-- `<cliSessionId>/tool-results/*.txt` — outputs too big to inline.
-- `logs/*.log` — app debug logs. **Not the conversation** — ignored.
-
-You rarely need this — the reader handles it — but it's here so you can read a record by hand if you must.
-
-## The thinking may be redacted — and what to show instead
-
-Whether "the thoughts" are actually readable depends on the model that ran the session, not on this tool:
-
-- **Sonnet sessions** → thinking exports as plaintext; you'll see the real reasoning.
-- **Opus sessions** (e.g. `claude-opus-4-8`) → thinking is **redacted**: the export carries only an encrypted signature, not the words. The reader states this once in the header (`💭 0 thoughts (+N redacted)` + a one-line banner) and otherwise keeps the body clean.
-
-**The substitute for redacted thinking is already in the transcript — not in the logs.** When the thoughts are encrypted, lean on what Claude actually *said and did*: the **text replies** routinely state the reasoning in plain language ("the problem is X, so I'll Y"), and the **tool-call sequence** shows the investigation step by step. The reader surfaces both, so you can reconstruct the "why" of a redacted session from its actions. (The zip's `logs/*.log` are NOT a fallback: they're app-wide, multi-day rolling logs with no per-session correlation and no reasoning — ignore them.)
-
-So if the user exported an Opus session hoping to re-read the literal reasoning, tell them plainly it's redacted — then answer their question anyway from the text + actions, which usually makes the reasoning clear.
-
-## Constraints
+```bash
+node scripts/gds/read-session-export.js <zip> > <scratchpad>/transcript.md   # then sed -n '1,400p', '400,850p', …
+```
 
-- **Reads, never writes.** Output goes to stdout for you to consume; it creates no files and never modifies the zip.
-- **Local + zero-dependency.** Pure Node stdlib (a small `zlib` ZIP reader) — no Bongos session, no network, no install. Works on any builder machine.
-- ZIP64 archives (multi-GB) are refused with a clear message; no real session export hits that.
+## If the thinking is redacted
 
-## Files this skill touches
+Opus sessions export encrypted reasoning rather than words, and the reader says so in its header. Tell the user plainly — then answer their question anyway from the **text replies**, which routinely state the reasoning outright ("the problem is X, so I'll Y"), and the **tool-call sequence**, which shows the investigation step by step. The zip's `logs/*.log` are not a fallback: app-wide rolling debug logs, no per-session correlation, no reasoning.
 
-- Runs: `node scripts/gds/read-session-export.js` (the whole implementation).
-- Reads: the `session-export-*.zip` you point it at. Writes: nothing.
+Reads only — it creates no files and never modifies the zip.

package/docs/adr/0327-a-cloud-host-runs-on-the-owners-account-and-the-key-is-borrowed.md

@@ -1,6 +1,6 @@
 # ADR 0327 — A cloud-host runs on the owner's own account, and the key is borrowed, not stored
 
-- **Status:** accepted
+- **Status:** accepted — **one Context finding retracted 2026-09-23** ([task 1004186](https://cloudbongos.com/builders#/task/1004186)): `mercury` was *not* already on Render, and the first Consequences bullet that rested on it is retracted with it. Decisions 1–5 are unaffected and stand. See the correction in Context.
 - **Date:** 2026-09-22
 - **Task:** [task 1004175](https://cloudbongos.com/builders#/task/1004175) (goal 1000106 — working area 1, Project creation)
 - **Deciders:** Lars (Archon) — decisions 1, 3 and 4 are the owner's. Decision 2 is Claude's design answer to the owner's question "is there a simpler way", and decision 5 records a measurement.
@@ -14,9 +14,18 @@
 
 Standing that up exposed what the unexamined assumption costs. A Render API key is issued against a *user* and carries that user's rights in **every workspace they belong to**. The owner's key reached three workspaces, one of them another builder's, holding their live production services. We would have been one bug away from acting on a third party's infrastructure with a credential they never gave us.
 
-The same check found the second thing: **`mercury` was already on Render**, run by its own owner from their own repository. Under ADR 0323 we would have migrated a working project *off* a correct setup and onto our bill.
+The same check found what was recorded here as a second thing: "**`mercury` was already on Render**, run by its own owner from their own repository. Under ADR 0323 we would have migrated a working project *off* a correct setup and onto our bill."
 
-Both facts point the same way. The remaining landlord relationship was never the servers — it was the **account**.
+**Correction, 2026-09-23 ([task 1004186](https://cloudbongos.com/builders#/task/1004186)). That finding is wrong; the sentence above is kept only to show what was claimed.** The Bongos instance is on our own box, and always was. Measured against the live fleet and the live endpoint:
+
+- Fleet row 31: `hosting_shape='standalone'`, `domain=mercury.cloudbongos.com`, `db_name=mercury`, `port=3018`, `onboard_mode=adopt`, `target_ref=willHermesLines/mercury_bongos`, last verified up 2026-09-24.
+- `GET https://mercury.cloudbongos.com/healthz` → `200`, carrying the header **`via: 1.1 Caddy`** — our Caddy, our control-plane box, behind Cloudflare. `/version` reports core 1.19.312.
+
+**What was actually seen, and why it misled.** `mercury_bongos` is a *hybrid* repository: its owner's own Python warehouse application (`app.py`, plus a `Procfile` reading `web: gunicorn app:app`) with an **adopted** Bongos instance layered onto it (`package.json` depends on `@bongos/core` as `file:vendor/bongos-core-1.19.305.tgz` — the vendoring path). It carries no `render.yaml`. So the live production services in that workspace are most plausibly the owner's *Python app* — a real Render deployment that is simply not the Bongos instance. A workspace listing and an instance row were read as the same object; they are two systems sharing a name and a repository.
+
+That last step is the likeliest reading, not a measurement — confirming it needs the owner, or a look inside their workspace, and neither was available. What *is* measured is the half that matters: **the Bongos instance is on our box and has not moved.**
+
+**The decision below does not depend on the retracted half.** The first finding — that a Render API key carries its user's rights into every workspace they belong to — is measured, and on its own it is sufficient. The remaining landlord relationship was never the servers; it was the **account**.
 
 ## Decision
 
@@ -86,13 +95,13 @@ So the web tier process **can** read the DigitalOcean, Cloudflare and platform t
 
 ## Consequences
 
-- **The migration shrinks to an adoption.** `mercury` is already in the target state; its instance record needs pointing at a deployment its owner runs, not a move. <redacted> is a distinction `scripts/gds/provision-repo.js` already draws for repositories, and the platform leg needs it too. [task 1004142](https://cloudbongos.com/builders#/task/1004142) is re-scoped accordingly.
+- ~~**The migration shrinks to an adoption.** `mercury` is already in the target state; its instance record needs pointing at a deployment its owner runs, not a move.~~ **Retracted 2026-09-23 ([task 1004186](https://cloudbongos.com/builders#/task/1004186)) — see the correction in Context.** The migration does not shrink: `mercury`'s Bongos instance runs on our box and still has to move, like the other three. Because the project is someone else's, that move needs its owner's agreement and their own Render account, which makes it the courtesy call this ADR's closing thought was reaching for. <redacted> remains a real distinction — `scripts/gds/provision-repo.js` already draws it for repositories and the platform leg still needs it — but nothing in the fleet is currently an example of it, so it has to be built from the spec rather than from a live case. The pilot is [task 1004142](https://cloudbongos.com/builders#/task/1004142) and the moves are [task 1004184](https://cloudbongos.com/builders#/task/1004184).
 
 - **The fleet cost ledger's question changes, and it is no longer "what do we owe".** [ADR 0325](0325-the-managed-fleet-control-plane-is-the-hub-we-already-run.md) §6 filed [task 1004148](https://cloudbongos.com/builders#/task/1004148) because `costEstimateUsd` returns 0 for a project "the platform is about to be billed for". The platform is not going to be billed for it. A ledger reporting our spend should read ~$0 per `cloud-host` and be *correct*; what an owner is worth telling is **their** estimated Render cost, which is a different column with a different meaning. Reporting one as the other is the defect now.
 
 - **Metering and charging lose their forcing function.** [task 1001949](https://cloudbongos.com/builders#/task/1001949) was sized against recovering ~$14/project/month. There is nothing to recover. Cost *visibility* — showing an owner what their project costs them — survives as a product feature; billing for hosting does not, because we do not host.
 
-- **`dedicated` becomes dead data as well as dead code.** Its stored value must be migrated, not merely orphaned. That migration runs over live rows and belongs with the rest of the shape rename in [task 1004142](https://cloudbongos.com/builders#/task/1004142).
+- **`dedicated` becomes dead code, and — measured — no data at all.** Its stored value must be dropped rather than merely orphaned. Pointer corrected 2026-09-23: that work split out of task 1004142 into [task 1004182](https://cloudbongos.com/builders#/task/1004182). The same check found the fleet carries **zero** `dedicated` rows, so the "runs over live rows" caution belongs to the 22 `standalone` rows being renamed to `cloud-host`, not to `dedicated`, whose migration is a no-op. Re-verify before writing one.
 
 - **Our own token exposure is now the largest unmitigated item in this area.** Decision 5 is filed as its own task. It was not urgent while it protected only tokens we could rotate ourselves; it stays that way, but it should not stay unowned.
 

package/docs/module-api-changelog.md

@@ -2468,5 +2468,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.995 with no explicit bump. run 35934673169. (task 1002620)
   1.19.997 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.996 with no explicit bump. run 35937246865. (task 1002620)
+  1.19.998 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.997 with no explicit bump. run 35940192900. (task 1002620)
+  1.19.999 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.998 with no explicit bump. run 35942048393. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.997",
+  "version": "1.19.999",
   "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/scripts/gds/provision-core-upgrade.js

@@ -520,29 +520,141 @@ function parseChangeRecords(stdout) {
  * is interpolated into a command is checked where it is interpolated — the rule
  * upgradeInvocation states about the slug.
  */
+/**
+ * Classify a git command that did not succeed. PURE.
+ *
+ * "COULD NOT LOOK" AND "LOOKED AND DID NOT FIND" ARE DIFFERENT ANSWERS (task 1004212).
+ * The first cut collapsed both into "could not find those releases in the core history on
+ * this machine", and that sentence sent the investigation at the history for an hour when
+ * the history was never the problem — the directory was. A message that names the wrong
+ * cause is worse than a vague one, because it is followed.
+ */
+function gitFault(r, dir) {
+  const said = `${(r && r.stdout) || ''}\n${(r && r.stderr) || ''}`;
+  if (/dubious ownership|safe\.directory/i.test(said)) {
+    return `the core checkout at ${dir} belongs to another account, so this could not read it`;
+  }
+  if (/not a git repository/i.test(said)) return `${dir} is not a git checkout`;
+  const tail = said.trim().split('\n').filter(Boolean).slice(-1)[0] || '';
+  return `could not read ${dir}${tail ? ` — ${tail.slice(0, 160)}` : ''}`;
+}
+
+/**
+ * Where the CORE's own git history lives on this machine, if anywhere (task 1004212).
+ *
+ * WHAT THE FIRST CUT GOT WRONG, and it was not a small thing. It read `selfInstanceRoot()`
+ * on the assumption that the control plane's instance root is a checkout of the core. On
+ * the live box it is not: `/version` there reports a commit that does not exist in the core
+ * repository at all, because the instance root is a checkout of the INSTANCE's own repo
+ * with the core vendored in at node_modules (the task 1004123 shape). So every lookup
+ * searched the wrong repository's history.
+ *
+ * THAT IS A CORRECTNESS BUG, NOT ONLY A MISSING FEATURE. On a box whose instance repo
+ * happened to carry `Merge <branch>: <summary>` commits — which any repo built this way
+ * does — the page would have shown ANOTHER project's changelog as the core's, with no
+ * error at all. Which is why a candidate is not trusted for being a git repo: it has to
+ * prove it carries core RELEASE history, and `looksLikeCore` is that proof.
+ *
+ * NO PATH IS HARDCODED. `audit-authorship.sh` forbids naming the founder's directories,
+ * and a guessed path is how this got here. The candidates are: an explicit operator
+ * setting, the directory the CLI is executing from, and the instance root — each checked,
+ * none assumed.
+ */
+function coreCheckoutCandidates(deps) {
+  const selfRoot = deps.selfInstanceRoot || selfInstanceRoot;
+  const env = deps.env || process.env;
+  const out = [];
+  const add = (dir, why) => { if (dir && !out.some((c) => c.dir === dir)) out.push({ dir, why }); };
+  add(String(env.PROVISION_CORE_CHECKOUT || '').trim() || null, 'PROVISION_CORE_CHECKOUT');
+  add(REPO_ROOT, 'the directory this core is running from');
+  add(selfRoot(), "this project's own root");
+  return out;
+}
+
+/**
+ * Read the core's release history, or say precisely why it cannot be. Returns
+ * `{ dir }` on success, or `{ error }` — never a directory it has not verified.
+ */
+function findCoreCheckout(deps, git) {
+  const tried = [];
+  for (const { dir, why } of coreCheckoutCandidates(deps)) {
+    const probe = git(dir, 'rev-parse --is-shallow-repository');
+    if (!probe.ok) { tried.push(`${why}: ${gitFault(probe, dir)}`); continue; }
+    if (probe.stdout.trim() === 'true') {
+      // A depth-limited clone resolves HEAD perfectly well — which is why /version reports
+      // `resolvedVia: git` on a box that cannot answer this — and carries no old releases.
+      tried.push(`${why}: ${dir} is a shallow clone, so it carries no release history`);
+      continue;
+    }
+    // THE PROOF THAT THIS IS THE CORE. Any repository answers `rev-parse`; only the core's
+    // carries release commits, and accepting a repo without asking is how the wrong
+    // project's changelog would have been shown as this one's.
+    const marker = git(dir, "log --format=%H --max-count=1 -E --grep='^release: core [0-9]+\\.[0-9]+\\.[0-9]+ '");
+    if (!marker.ok) { tried.push(`${why}: ${gitFault(marker, dir)}`); continue; }
+    if (!marker.stdout.trim()) { tried.push(`${why}: ${dir} is a git checkout, but not of the core`); continue; }
+    return { dir };
+  }
+  return { error: `no core checkout is reachable on this machine (${tried.join('; ')}). Set PROVISION_CORE_CHECKOUT to one.` };
+}
+
+/**
+ * What landed between two core releases, as the summaries their ships wrote.
+ *
+ * Returns `{ from, to, entries, more }`, or `{ from, to, error }` — NEVER an empty
+ * `entries` for a range it could not resolve. An empty list reads as "nothing changed",
+ * which on a page whose job is to say what a restart buys is the one wrong impression it
+ * must not give, and it is exactly what a missing checkout produces.
+ *
+ * Every version reaching a shell is re-checked against the strict three-number form
+ * FIRST. They arrive from an intent row whose column has the same CHECK, but a value that
+ * is interpolated into a command is checked where it is interpolated — the rule
+ * upgradeInvocation states about the slug.
+ */
 function changesBetween(fromVersion, toVersion, deps) {
   const bad = [fromVersion, toVersion].find((v) => !CORE_VERSION_RE.test(String(v || '')));
   if (bad !== undefined) return { from: fromVersion || null, to: toVersion || null, error: 'could not work out which releases this covers' };
-  // The CONTROL PLANE's executor and the CONTROL PLANE's checkout, never the previewed
-  // instance's: under PROVISION_REMOTE_HOST `exec` is the remote box, and a tenant's own
-  // directory holds no core history at all.
+  // The CONTROL PLANE's executor, never the previewed instance's: under
+  // PROVISION_REMOTE_HOST `exec` is the remote box, while the core history — and the whole
+  // question of what changed in the CORE — belongs to the machine that builds it.
   const exec = deps.controlExec || deps.exec;
-  const selfRoot = deps.selfInstanceRoot || selfInstanceRoot;
-  const dir = selfRoot();
+  // AS THE ACCOUNT THAT OWNS THE CHECKOUT, for the same reason the dry run beside this one
+  // does (task 1004128). `appUser()` is defined as "the unprivileged account that owns this
+  // checkout" and throws rather than return root, so a runner executing as root reads the
+  // files through the account that may actually read them instead of tripping git's
+  // ownership check. Unprivileged runners are unchanged — there is nothing to escalate to.
+  let runAs = null;
+  if (deps.privileged) {
+    try { runAs = (deps.appUser || appUser)(); } catch { runAs = null; }
+  }
+  const git = (dir, args) => {
+    const r = exec(`${runAs ? `sudo -u ${runAs} ` : ''}git -C ${dir} ${args}`, { allowFail: true });
+    return {
+      ok: !!(r && r.softFailed !== true && r.ok !== false),
+      stdout: String((r && r.stdout) || ''),
+      stderr: String((r && r.stderr) || ''),
+    };
+  };
+  const found = findCoreCheckout(deps, git);
+  if (found.error) return { from: fromVersion, to: toVersion, error: found.error };
+  const dir = found.dir;
   const shaOf = (v) => {
-    const r = exec(`git -C ${dir} log --format=%H --max-count=1 -F --grep='release: core ${v} '`, { allowFail: true });
-    const sha = String((r && r.stdout) || '').trim().split('\n')[0] || '';
-    return /^[0-9a-f]{7,40}$/.test(sha) ? sha : null;
+    const r = git(dir, `log --format=%H --max-count=1 -F --grep='release: core ${v} '`);
+    if (!r.ok) return { fault: gitFault(r, dir) };
+    const sha = r.stdout.trim().split('\n')[0] || '';
+    return /^[0-9a-f]{7,40}$/.test(sha) ? { sha } : {};
   };
   const from = shaOf(fromVersion);
   const to = shaOf(toVersion);
-  if (!from || !to) {
-    return { from: fromVersion, to: toVersion, error: 'could not find those releases in the core history on this machine' };
-  }
-  const r = exec(`git -C ${dir} log --merges --format=%s%x1f%b%x1e ${from}..${to}`, { allowFail: true });
-  if (!r || r.softFailed === true || r.ok === false) {
-    return { from: fromVersion, to: toVersion, error: 'could not read the core history on this machine' };
+  if (from.fault || to.fault) return { from: fromVersion, to: toVersion, error: from.fault || to.fault };
+  // LOOKED, AND DID NOT FIND — a different sentence from "could not look", and it names
+  // WHICH version is missing so the reader can tell a not-yet-published target from a
+  // checkout that has not been fetched.
+  const missing = [!from.sha && fromVersion, !to.sha && toVersion].filter(Boolean);
+  if (missing.length) {
+    return { from: fromVersion, to: toVersion, error: `core ${missing.join(' and ')} ${missing.length > 1 ? 'are' : 'is'} not in the core history on this machine yet` };
   }
+  const r = git(dir, `log --merges --format=%s%x1f%b%x1e ${from.sha}..${to.sha}`);
+  if (!r.ok) return { from: fromVersion, to: toVersion, error: gitFault(r, dir) };
   const all = parseChangeRecords(r.stdout);
   return { from: fromVersion, to: toVersion, entries: all.slice(0, CHANGE_CAP), more: Math.max(0, all.length - CHANGE_CAP) };
 }
@@ -668,4 +780,4 @@ async function snapshotAllCoreVersions(deps) {
   return { seen };
 }
 
-module.exports = { UPGRADE_SHAPES, CHANGE_CAP, parseChangeRecords, changesBetween, resolveRunAs, versionCmd, parseServedVersion, parseSchemaPending, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };
+module.exports = { UPGRADE_SHAPES, CHANGE_CAP, parseChangeRecords, changesBetween, coreCheckoutCandidates, findCoreCheckout, gitFault, resolveRunAs, versionCmd, parseServedVersion, parseSchemaPending, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.997'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.999'; // 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('dev-box'); log.info('mounted');

package/tests/core_upgrade_runner.mjs

@@ -883,16 +883,36 @@ await t('a paragraph-long summary is bounded — it reaches a DOM', () => {
 
 // --- the range, and every way it can fail to resolve ------------------------------
 
-const changeDeps = ({ shas = { '1.19.900': 'a'.repeat(40), '1.19.949': 'b'.repeat(40) }, log = LOG, logOk = true } = {}) => {
+// A box that really does hold a core checkout. `repos` maps a directory to what git
+// there answers: `core` (a real core checkout), `notCore` (a git repo of something else),
+// `shallow`, `owned` (git refuses on ownership) or absent (not a git repo).
+const changeDeps = ({
+  shas = { '1.19.900': 'a'.repeat(40), '1.19.949': 'b'.repeat(40) },
+  log = LOG, logOk = true, repos = { '/srv/core': 'core' }, env = {}, privileged = false,
+} = {}) => {
   const ran = [];
   return {
-    ran,
+    ran, env, privileged,
     selfInstanceRoot: () => '/srv/core',
+    appUser: () => 'appacct',
     exec: (cmd) => {
       ran.push(cmd);
-      const m = /--grep='release: core ([0-9.]+) '/.exec(cmd);
+      const dir = (/git -C (\S+) /.exec(cmd) || [])[1];
+      const kind = repos[dir];
+      if (!kind) return { ok: false, softFailed: true, stdout: '', stderr: `fatal: not a git repository: '${dir}'` };
+      if (kind === 'owned') {
+        return { ok: false, softFailed: true, stdout: '', stderr: `fatal: detected dubious ownership in repository at '${dir}'` };
+      }
+      if (/rev-parse --is-shallow-repository/.test(cmd)) {
+        return { ok: true, stdout: `${kind === 'shallow' ? 'true' : 'false'}\n` };
+      }
+      // The marker probe: does this repo carry core RELEASE commits at all?
+      if (/-E --grep='\^release: core/.test(cmd)) {
+        return { ok: true, stdout: kind === 'core' ? `${'c'.repeat(40)}\n` : '\n' };
+      }
+      const m = /-F --grep='release: core ([0-9.]+) '/.exec(cmd);
       if (m) return { ok: true, stdout: `${shas[m[1]] || ''}\n` };
-      if (!logOk) return { ok: false, softFailed: true, stdout: '' };
+      if (!logOk) return { ok: false, softFailed: true, stdout: '', stderr: 'fatal: bad revision' };
       return { ok: true, stdout: log };
     },
   };
@@ -908,29 +928,85 @@ await t('the range resolves through the release commits and lists what landed be
   assert.ok(d.ran.some((c) => /--merges/.test(c) && /a{40}\.\.b{40}/.test(c)), 'the log is asked for the resolved range');
 });
 
-await t('IT READS THE CONTROL PLANE’S OWN CHECKOUT, whichever instance is previewed', () => {
-  // A tenant's directory is a checkout of the TENANT's repo with the core vendored in
-  // from npm — no core history in it, and the wrong history if you squint. Under
-  // PROVISION_REMOTE_HOST `exec` is the remote box, so the executor matters too.
+await t('IT USES THE CONTROL PLANE’S EXECUTOR, whichever instance is previewed', () => {
+  // Under PROVISION_REMOTE_HOST `exec` is the remote box, while the core history belongs
+  // to the machine that builds the core.
   const d = changeDeps();
   d.controlExec = d.exec;
   d.exec = () => { throw new Error('the instance executor must not be used for core history'); };
+  assert.equal(R.changesBetween('1.19.900', '1.19.949', d).entries.length, 2);
+});
+
+// ---- WHICH checkout, and the bug that made this task (task 1004212) ---------------
+
+await t('A GIT REPO THAT IS NOT THE CORE IS REFUSED, not read as if it were', () => {
+  // THE BUG THIS TASK EXISTS FOR. The first cut trusted selfInstanceRoot() to be a core
+  // checkout. On the live box it is the INSTANCE's own repo with the core vendored in at
+  // node_modules — its /version commit does not exist in the core repository at all. Any
+  // repo built that way carries `Merge <branch>: <summary>` commits, so without this the
+  // page would have shown ANOTHER project's changelog as the core's, with no error.
+  const d = changeDeps({ repos: { '/srv/core': 'notCore' } });
   const r = R.changesBetween('1.19.900', '1.19.949', d);
-  assert.equal(r.entries.length, 2);
-  for (const c of d.ran) assert.match(c, /git -C \/srv\/core /, 'always the control plane’s own core checkout');
+  assert.equal(r.entries, undefined, 'nothing is listed from the wrong repository');
+  assert.match(r.error, /not of the core/);
+  assert.ok(!d.ran.some((c) => /--merges/.test(c)), 'and its log is never even read');
+});
+
+await t('the candidates are tried in order, and an operator setting wins', () => {
+  const d = changeDeps({
+    repos: { '/opt/corerepo': 'core', '/srv/core': 'core' },
+    env: { PROVISION_CORE_CHECKOUT: '/opt/corerepo' },
+  });
+  assert.equal(R.changesBetween('1.19.900', '1.19.949', d).entries.length, 2);
+  assert.ok(d.ran.every((c) => /git -C \/opt\/corerepo /.test(c)), 'only the named checkout is touched');
+});
+
+await t('a candidate that is not a core checkout FALLS THROUGH to one that is', () => {
+  const d = changeDeps({
+    repos: { '/opt/notcore': 'notCore', '/srv/core': 'core' },
+    env: { PROVISION_CORE_CHECKOUT: '/opt/notcore' },
+  });
+  assert.equal(R.changesBetween('1.19.900', '1.19.949', d).entries.length, 2);
+  assert.ok(d.ran.some((c) => /git -C \/srv\/core /.test(c)), 'the next candidate is reached');
+});
+
+await t('NO reachable core checkout names every candidate it tried, and the way out', () => {
+  const d = changeDeps({ repos: {} });
+  const r = R.changesBetween('1.19.900', '1.19.949', d);
+  assert.equal(r.entries, undefined);
+  assert.match(r.error, /no core checkout is reachable/);
+  assert.match(r.error, /PROVISION_CORE_CHECKOUT/, 'and the setting that fixes it');
+});
+
+// ---- "could not look" vs "looked and did not find" -------------------------------
+
+await t('AN OWNERSHIP REFUSAL SAYS SO — it is not a missing release', () => {
+  // The misdiagnosis this replaces: every one of these used to print "could not find
+  // those releases in the core history", which sends the reader at the history when the
+  // history was never the problem.
+  const d = changeDeps({ repos: { '/srv/core': 'owned' } });
+  const r = R.changesBetween('1.19.900', '1.19.949', d);
+  assert.match(r.error, /belongs to another account/);
+  assert.doesNotMatch(r.error, /not in the core history/);
+});
+
+await t('a shallow clone says so — it resolves HEAD fine and carries no releases', () => {
+  const d = changeDeps({ repos: { '/srv/core': 'shallow' } });
+  assert.match(R.changesBetween('1.19.900', '1.19.949', d).error, /shallow clone/);
 });
 
-await t('A RANGE THAT CANNOT BE RESOLVED IS AN ERROR, NEVER AN EMPTY LIST', () => {
-  // An empty list reads as "nothing changed", which over ninety-one releases is the one
-  // wrong impression this section could give — and it is the shape a missing checkout,
-  // a shallow clone or an unknown release all take.
-  const missing = R.changesBetween('1.19.900', '9.9.9', changeDeps());
-  assert.equal(missing.entries, undefined, 'no list at all');
-  assert.match(missing.error, /could not find those releases/);
+await t('a release the checkout has not fetched NAMES which one', () => {
+  const d = changeDeps();
+  const r = R.changesBetween('1.19.900', '9.9.9', d);
+  assert.equal(r.entries, undefined, 'no list at all');
+  assert.match(r.error, /core 9\.9\.9 is not in the core history on this machine yet/);
+  assert.doesNotMatch(r.error, /could not read/, 'it looked successfully — it just did not find it');
+});
 
-  const unreadable = R.changesBetween('1.19.900', '1.19.949', changeDeps({ logOk: false }));
-  assert.equal(unreadable.entries, undefined);
-  assert.match(unreadable.error, /could not read the core history/);
+await t('a log that fails after the range resolved is reported as a read failure', () => {
+  const r = R.changesBetween('1.19.900', '1.19.949', changeDeps({ logOk: false }));
+  assert.equal(r.entries, undefined);
+  assert.match(r.error, /could not read \/srv\/core/);
 });
 
 await t('a version that is not three numbers never reaches the shell', () => {
@@ -941,6 +1017,33 @@ await t('a version that is not three numbers never reaches the shell', () => {
   assert.match(R.changesBetween(null, '1.19.949', changeDeps()).error, /could not work out/, 'an unknown starting point too');
 });
 
+// ---- as WHICH account ------------------------------------------------------------
+
+await t('a privileged runner reads git as the account that owns the checkout', () => {
+  // The same move the dry run beside this one makes (task 1004128). appUser() is defined
+  // as "the unprivileged account that owns this checkout", so a runner executing as root
+  // reads through an account that may actually read the files.
+  const d = changeDeps({ privileged: true });
+  R.changesBetween('1.19.900', '1.19.949', d);
+  assert.ok(d.ran.length > 0);
+  for (const c of d.ran) assert.match(c, /^sudo -u appacct git -C /, `every read is escalated: ${c}`);
+});
+
+await t('an UNPRIVILEGED runner escalates nothing — there is nothing to escalate to', () => {
+  const d = changeDeps();
+  R.changesBetween('1.19.900', '1.19.949', d);
+  for (const c of d.ran) assert.doesNotMatch(c, /sudo/);
+});
+
+await t('an app user that cannot be resolved does not take the whole read down', () => {
+  // appUser() THROWS when it would return root or an unusable name. That is a reason to
+  // read unescalated and let git say whether it could, not a reason to return no answer.
+  const d = changeDeps({ privileged: true });
+  d.appUser = () => { throw new Error('the app user "root" is root'); };
+  assert.equal(R.changesBetween('1.19.900', '1.19.949', d).entries.length, 2);
+  for (const c of d.ran) assert.doesNotMatch(c, /sudo/);
+});
+
 await t('a long range is capped, and says how many it did not list', () => {
   const many = Array.from({ length: R.CHANGE_CAP + 5 }, (_, i) => REC(`Merge b-${i}: summary number ${i}`)).join('');
   const r = R.changesBetween('1.19.900', '1.19.949', changeDeps({ log: many }));