@bongos/core 1.19.681 → 1.19.683

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.681",
-  "core_contract": "1.19.681",
-  "source_commit": "e31ae913044e78d0b2b8202995eb551dad418a9e",
+  "core_version": "1.19.683",
+  "core_contract": "1.19.683",
+  "source_commit": "40eeb484085efb69d5aaa3645233d23854e2bbc1",
   "source_ref": "HEAD",
-  "built_at": "2026-09-12T02:05:45.659Z",
+  "built_at": "2026-09-12T17:02:13.044Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 476,
+    "docs_redacted": 477,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2124,
+    "functional_verbatim": 2125,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2624,
-  "tree_sha256": "f249c4df05688bdb744709b348940982241ccc686471029262564d9b79bdd140",
+  "file_count": 2626,
+  "tree_sha256": "aa8a467c8dcd7322882229d5b60da130eb5b67e726e38a0dde2b34d2ce6bfa4a",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -322,7 +322,7 @@
     {
       "path": ".gitattributes",
       "mode": "0000644",
-      "sha256": "72bc38b553e34bc652f0b5b5b2ab24999b4b11c2d6fc3699489e157fd0127a11"
+      "sha256": "38bf33dd14a7bff6545f961c4f30172ac850f6a0578900a3c10295c4fc0f27e9"
     },
     {
       "path": "CLAUDE.md",
@@ -1909,10 +1909,15 @@
       "mode": "0000644",
       "sha256": "46e65d06711ad356563b01b824c416d03cecf135f9f69a60e469710e91cb3f62"
     },
+    {
+      "path": "docs/adr/0280-the-unattended-lane-may-drive-a-co-tenant-because-the-roster-is-the-decision.md",
+      "mode": "0000644",
+      "sha256": "630f6460b3484f4cc629cce9c431f824bb8363d30a249db9e21e89863995c7ac"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "6766d2b792da65e6cebc79adf4261b710d6f5ce113a8a84953cf1c643e20a0b7"
+      "sha256": "49273e63c50c201cd70200a4f0db7f233e496827823adb9449638eb5a0c1d030"
     },
     {
       "path": "docs/api-reference.md",
@@ -2797,7 +2802,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "244cffb195592c644ad06262ed1a0f610e7744fd62e634a35c5cddd954c9def6"
+      "sha256": "abe1e67ec7bd2d5d4bf27a2b5d8b4337fc1d4b7374c1edab6c5392016a83fde3"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5642,7 +5647,7 @@
     {
       "path": "modules/lifecycle/conflict-resolve.js",
       "mode": "0000644",
-      "sha256": "1a281a4233b3805550a05ed6bd38b163ab18db658d48675f055b90d2ba722a16"
+      "sha256": "3e20f4965d1d83d17f8e777201bd7e4fd7857843295180542914de16ae51e936"
     },
     {
       "path": "modules/lifecycle/criterion-suggest.js",
@@ -7777,12 +7782,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "fd92e4204b64289d8404adb924c9142b47c10b0a6c73d709583cbbad01cd6e0a"
+      "sha256": "81888175ae0227d30c633c8f51a25936418cfdbf1d36c77bdd7c329d41d0c429"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "242ae038fbdb23f8d375f04e794c87100df9df4c250b93942ca4eaed82017ca3"
+      "sha256": "b5cd5f5c6b24980f4b85986be1919f4cb2697c3ba219277d51b1ef07de72343b"
     },
     {
       "path": "public-docs/index.html",
@@ -8282,7 +8287,7 @@
     {
       "path": "scripts/gds/gen-api-client.js",
       "mode": "0000644",
-      "sha256": "d363c76caf379a051faea40a2497db8bbba18effd68e9cd9922e9445638c57c5"
+      "sha256": "2d8b35709e19b339bc55c57237f2add36fa6bdeb83a9b036faa902b0c4b8e3f9"
     },
     {
       "path": "scripts/gds/gen-api-docs.js",
@@ -8332,7 +8337,7 @@
     {
       "path": "scripts/gds/git-merge-regen.js",
       "mode": "0000644",
-      "sha256": "9896dc201aaa7186838fe4dcecf5226fdb0736b1b7094a98649e2f8fcbfc4d1a"
+      "sha256": "9d65420d85f20d10dba3af63c45d8dd0425ee11dd3d5cfa14d3019abf7354aed"
     },
     {
       "path": "scripts/gds/go-live.js",
@@ -8372,7 +8377,7 @@
     {
       "path": "scripts/gds/init.js",
       "mode": "0000644",
-      "sha256": "1d63c1485820ad2e81e97979402eabd3829e86503f4c06318a251dc3a6874047"
+      "sha256": "b0971625852fca93ca474d2f9e31e3601397f1b9efbef3241a0b0c47f17d925f"
     },
     {
       "path": "scripts/gds/install-git-hooks.js",
@@ -9112,7 +9117,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "642d0ade55c203d6b07478a07d3c21c26fa4635dc8a92e4fe989434e635abbbb"
+      "sha256": "4f30ee3036846f449f6fc8143da32b3767376352743d373c39ace2f50f66e913"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -9142,7 +9147,7 @@
     {
       "path": "scripts/gds/worktree.js",
       "mode": "0000644",
-      "sha256": "56549d4c288f55699ceb1fea10f4f65756a9114b4628b3f2b6c44fed0ec6ab26"
+      "sha256": "849cd462b9c50866ca1582ed2156fb68ac76699c8270796d1daf6942c09713dc"
     },
     {
       "path": "scripts/hall-preview/README.md",
@@ -9542,7 +9547,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b06c931aa58a7997f7733e13d2850d290540647c4a7d243cc07d27c20d5b812e"
+      "sha256": "2adaf10cbc0a2e65aeaa820f95b2b789c8e66c398c5f56299e9d1f52e82b86a1"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10212,7 +10217,7 @@
     {
       "path": "tests/conflict_resolve.mjs",
       "mode": "0000644",
-      "sha256": "e36410c3288ec8c38c22bd5fd285d7abc6e0cadc4433ce87028bb7f9c7d54806"
+      "sha256": "da8182c4235c7735bdee351cfa7dc1146f7ded33b9d594dc0ba498a3b5206d83"
     },
     {
       "path": "tests/connections_api.mjs",
@@ -10642,7 +10647,7 @@
     {
       "path": "tests/git_merge_regen.mjs",
       "mode": "0000644",
-      "sha256": "52f02bc7f0da86b29d4b39da78a34f9677f7bdd93e24a4e5365ffb1af64fc413"
+      "sha256": "a55ae255245a53429cc7948e35ea0515bf58307f826d605d6ffd52cc60196ef8"
     },
     {
       "path": "tests/github_push_ancestry.mjs",
@@ -12984,10 +12989,15 @@
       "mode": "0000644",
       "sha256": "9debf9ecdb02b986c882f3d29bdf4b5fe2154cb4e7639db0fd0a0336cd4bdc3b"
     },
+    {
+      "path": "tests/update_subscription_engine.mjs",
+      "mode": "0000644",
+      "sha256": "a2ba2dca70c6192313c7a64e6dcbb5d7f9dbf2dc457592e643f1d59154b2665f"
+    },
     {
       "path": "tests/upgrade.mjs",
       "mode": "0000644",
-      "sha256": "106735a9ab28b4a23e2f25269030d982798da3fa39e31d40a1ec78277ac971bc"
+      "sha256": "492b9dc7efdd6f63b81f1662d5fdc9a7541b7f8ccc6c0ec77a456ad3f574ee74"
     },
     {
       "path": "tests/upgrade_persist_pin.mjs",

package/.gitattributes

@@ -112,6 +112,34 @@ src/bongos/routes/CLAUDE.md   merge=otb-regen
 docs/copy-registry.json    merge=otb-regen
 docs/copy-inventory.md     merge=otb-regen text eol=lf
 
+# Generated API contract + client (task 1003537). gen-api-docs.js writes the first
+# three of these wholesale from a scan of the route files; gen-api-client.js writes the
+# six client files wholesale from that spec. Nothing is hand-authored in any of the
+# nine, so they are the same whole-file shape as docs/session-log-index.md above — and
+# any branch that adds or changes a route regenerates all nine differently and conflicts
+# on ordinary text. Measured on task 1002334: main took 41 commits in 3 hours and four
+# consecutive merge -> regenerate -> reship cycles each lost the race to a fresh conflict
+# in exactly these files, with a PASSING grade the whole time. REGENERABLE in
+# git-merge-regen.js carries the matching rules, and tests/git_merge_regen.mjs pins the
+# two lists as one set.
+#
+# EVERY PATH IS LISTED EXPLICITLY -- deliberately no `clients/bongos-client/*` glob, for
+# two independent reasons. The lockstep test compares these tokens against REGENERABLE as
+# literal path strings, and the driver is handed git's %P, so a glob would match nothing
+# on either side. And clients/bongos-client/examples/hello-world.mjs is HAND-WRITTEN (the
+# generator owns only the six files below): a glob that captured it would route it through
+# a driver that has no rule for it, forcing a conflict git would otherwise merge cleanly --
+# the same trap the leading slash on /CLAUDE.md above exists to avoid.
+docs/api/openapi.json         merge=otb-regen
+docs/api-reference.md         merge=otb-regen
+docs/routes-permissions.md    merge=otb-regen
+clients/bongos-client/index.mjs               merge=otb-regen
+clients/bongos-client/index.cjs               merge=otb-regen
+clients/bongos-client/bongos-client.global.js merge=otb-regen
+clients/bongos-client/index.d.ts              merge=otb-regen
+clients/bongos-client/package.json            merge=otb-regen
+clients/bongos-client/README.md               merge=otb-regen
+
 # Append-only index tables (task 1385 / ADR 0082). docs/adr/README.md is a
 # hand-maintained ADR index whose ONLY recurring conflict is two branches each
 # appending a new row — there is no generator to regen it from, so `otb-regen`

package/docs/adr/0280-the-unattended-lane-may-drive-a-co-tenant-because-the-roster-is-the-decision.md

@@ -0,0 +1,63 @@
+# ADR 0280 — The unattended lane may drive a co-tenant, because the roster entry *is* the per-instance decision
+
+- **Status:** accepted
+- **Date:** 2026-09-12
+- **Task:** [1003843](https://cloudbongos.com/builders#/task/1003843) (goal 1000106) — from [task 1003521](https://cloudbongos.com/builders#/task/1003521), which built co-tenant mode into `go-live.js` and deliberately left this caller alone.
+- **Adjacent:** [ADR 0279](<redacted>.md) (why this lane prefers `go-live.js` at all) · [ADR 0136](<redacted>.md) (the subscription policy core).
+
+## Context
+
+`go-live.js` grew **co-tenant mode** in task 1003521: `deployTimer` became optional (a provisioned instance under `/srv/<host>/<slug>` has no pull-deploy timer to stop), and `pinMode: local-commit | leave-dirty` stopped it pushing the pin into the **customer's own** GitHub repo.
+
+The nightly auto-subscription lane (`.claude/scheduled-tasks/core-update-subscription/subscribe.js`) could not reach any of it, because it keeps a **second copy of go-live's target contract**:
+
+1. `GO_LIVE_REQUIRED` still listed `deployTimer`, so `goLiveTargetFor()` returned `{ok: false, missing: ['deployTimer']}` for every co-tenant.
+2. `rawTopologyFor()` reads a fixed field list off `config/update-subscriptions.json`, and `pinMode` was not in it — the same stale-normalizer trap that function's own comment was written to fix, one field later.
+
+Task 1003521 deferred the fix on the grounds that widening it "would have meant changing the unattended lane's policy about which instances it may deploy, which is a judgement call." **That premise does not survive reading the fallback.** `mapped.ok === false` does not mean "skip this instance" — it means "deploy it the *weaker* way": a bare `bongos upgrade` with no backup and no deploy-timer guard, and, because the roster's `--commit-pin` support is independent of all this, a pin **committed and pushed** — into the co-tenant's own repo, which is precisely what `pinMode` exists to prevent.
+
+So the lane was already auto-deploying co-tenants. The only question ever open was whether it did so well.
+
+A third defect sat behind the other two, and would have turned the reported silent downgrade into a hard failure if only the first had been fixed: the normalizer yields `deployTimer: null` for an absent field, an explicit `null` **survives `JSON.stringify`** into `--target-json`, and go-live's `validateTarget` runs `isSafeToken(null)` on it and rejects the whole target. Dropping `deployTimer` from `GO_LIVE_REQUIRED` alone would have handed go-live a target it refuses.
+
+**The remaining defects sat outside the go-live call entirely, and they are what made "reachable" different from "safe".** The lane writes the instance's pin in **three** places, and every one of them decided whether to push without asking what mode it was in:
+
+1. **The durability net after the upgrade** — `commitPin()` commits the pin files and **pushes to `origin`**. Under `local-commit` go-live leaves the tree clean, so the net no-ops and is correct by luck. Under **`leave-dirty`** the pin is in the working tree *by design*, so the net committed it and pushed it into the customer's repo.
+2. **The HEAL-FIRST step before the upgrade**, which is the worst of the three because it fires on the **happy path**. A `leave-dirty` co-tenant's steady state after a *successful* upgrade IS a dirty pin — so the next scheduled sweep read it as "a leftover from an earlier sweep", committed it and pushed it. Reliably, every sweep, not just after a crash. (Found by the grader; it shipped past a green suite on the first round because the decision was an inline `if` inside a 250-line loop that no test could reach.)
+3. **The direct-upgrade fallback**, which passes `--commit-pin` to `upgrade.js` — and that flag commits *and pushes*. So a co-tenant on an older core had its pin pushed anyway, by the very path taken when go-live's co-tenant support was missing.
+
+Reaching co-tenant mode without closing all three would have been worse than not reaching it at all: the lane would honour `pinMode` at the one site that names it and undo it at the two that do not.
+
+## Decision
+
+**The nightly lane may drive a co-tenant, and needs no new gate to do it — because enrolling an instance in `config/update-subscriptions.json` already IS the explicit, per-instance operator decision.** The roster ships empty, an instance is touched only after an operator lists it, and the whole routine is behind the autonomy flag (`requiresAutonomy: true`, default OFF). Adding a second consent gate in front of that would be asking the same person the same question twice.
+
+The change therefore makes the *existing* behaviour correct rather than widening it. Concretely, in `subscribe.js`:
+
+- `GO_LIVE_REQUIRED` now **mirrors** go-live's `REQUIRED_FIELDS` exactly, and a test reads **both source files** and fails on drift. The contract is someone else's; the copy is the liability.
+- `deployTimer` moves into the optional-field loop, which drops falsy values, so a co-tenant **omits the key** rather than carrying a `null` that go-live would reject.
+- `rawTopologyFor` carries `pinMode`, and `goLiveTargetFor` passes it through.
+- The capability probe in `resolveGoLive` gains a **`needsCoTenant`** leg, checked **only when the target actually needs it** — a target with no `deployTimer`, or one naming `pinMode`. Both are rejected outright by a go-live.js predating 1003521 (the missing required field; the unknown-field check), so the fail-closed rule of task 1003212 applies: probe the capability, fall back if absent.
+- `goLiveEngineFor()` makes that decision **once**, for both the dry run and the apply path. They previously re-derived it separately, and the co-tenant probe gave them a third thing to keep in step — a preview that promises an engine the real sweep will not use is its own quiet failure.
+- **All three pin-writing sites obey one policy, read from the roster.** `pinModeOf()` reads the **roster entry** — the operator's declared intent — not the go-live target, because deriving it from the target would silently revert a co-tenant to `push` on exactly the runs that fall back to a direct upgrade. `commitPin()` takes `push` (default `true`, so the platform instance is unchanged); the fallback withholds `--commit-pin` unless the mode is `push`; and the "pin is not durable" advice no longer tells an operator to `git push` a repo we do not own.
+- **The heal decision is a named function, `healDecision(pre, pinMode)`.** Under `leave-dirty` a dirty pin is `by-design`, not a leftover — go-live's dirty-checkout halt reads the **core** checkout, not the instance, so leaving it dirty wedges nothing. Extracting it is the point as much as the fix: all three bugs were a site deciding without asking, and an inline `if` in a long loop is exactly what no test can reach. Non-pin changes still `halt` in **every** mode — a human's uncommitted work stops the lane regardless of pin policy, and the test pins that ordering.
+- **An unknown `pinMode` is refused, not defaulted.** Every unrecognised value would otherwise fall through to the push branch, so a typo in the roster degrades to the *most* dangerous behaviour. The instance is skipped with the expected values named. `PIN_MODES` mirrors go-live's enum, pinned by the same read-both-sources test as `GO_LIVE_REQUIRED`.
+
+**Why the probe is conditional and not unconditional.** Probing for `pinMode` on every target would strip the go-live path from any instance sitting on a core between the `--target-json` release and 1003521's — a live regression traded for a hypothetical one. The capability is demanded only where it is used.
+
+## Consequences
+
+- A provisioned co-tenant listed in the roster now takes the **stronger** deploy path: pg_dump backup, the served-version read-back of ADR 0279, and a pin that is committed locally instead of pushed into a repo we do not own — end to end, including the lane's own net after go-live returns.
+- A co-tenant on an older core **falls back and says so**, naming co-tenant support specifically, so an operator can tell it apart from a malformed roster entry.
+- Ordinary instances are unchanged — including the mid-generation ones the conditional probe protects.
+- `GO_LIVE_REQUIRED` and `PIN_MODES` drifting from go-live's contract are now **test failures**, not silent downgrades. This is the second time this copy has drifted; the next time it moves, CI says so.
+- A source-level test asserts that **every** `commitPin` call site names `push`, and that the fallback gates `--commit-pin`. The recurring bug was never one site — it was the absence of anything that could see all of them at once.
+
+## Rejected
+
+- **A second consent gate** (an opt-in `allowCoTenant` roster flag, or an operator-only command): the roster entry already carries that consent, and the routine is autonomy-gated on top of it.
+- **Deferring to the fleet control plane** ([task 1001948](https://cloudbongos.com/builders#/task/1001948)): that epic is unspecced, and leaving this until then does not leave co-tenants alone — it leaves them on the weaker path, pushing pins into customer repos.
+- **Dropping `deployTimer` from `GO_LIVE_REQUIRED` and nothing else** (the fix as originally proposed): it trades a silent downgrade for a hard target rejection, because of the surviving `null`.
+- **Probing for co-tenant support unconditionally:** regresses every instance on a mid-generation core.
+- **Reaching co-tenant mode without teaching the durability net about it:** `leave-dirty` would have been committed and pushed to the customer's remote by the net running seconds after go-live deliberately did not — nominal support that breaks its own promise.
+- **Teaching `loadSubscriptions()` about `pinMode`** instead of `rawTopologyFor`: that normalizer ships in the *control plane's* vendored core, which nobody bumps — trusting it is the exact trap `rawTopologyFor` was written to route around.

package/docs/adr/README.md

@@ -371,3 +371,4 @@ This keeps the decision history honest and traceable.
 | 0277 | [**A box is "in use" only while a human is attached, and the claim expires** ([task 1003507](https://cloudbongos.com/builders#/task/1003507) · goal 1000095 — *Working area 6*, criterion `wa6-role-experience`). `sweep-idle` skipped any box with `claude_active = true` at ANY age, and `claude_active` is a LATCH, not a level: only a heartbeat ping writes it, and `infra/box-heartbeat.sh` exits WITHOUT pinging when it sees nothing — so silence, the very signal the sweep exists to act on, could never clear it. Reproduced against the shipped selector: skipped at `idleMinutes` of 10, 120, 1440 and **5,256,000** (ten years). Not reaped late; never. The second leg is that `load > 0.2` kept `last_activity_at` bumping every 5 minutes anyway (a devcontainer plus an idle `claude` clears that floor on its own), so EITHER leg alone kept a box alive — which is why bounding only the veto looks like a fix and is not: the incident box's heartbeat was FRESH. Measured: `example-owner`'s box up since 2026-08-12, tmux `otb` UNATTACHED since 2026-08-15 18:01 UTC, `claude` burning 16 min of CPU across 25h of wall clock, **$20.21** of mostly-unattended compute. A THIRD defect, found while testing this and confirmed on clean `origin/main`, made the sweep inert regardless: `loadDeps()` read `_deps` before anything declared it, so it threw `ReferenceError` on first call and every command resolving a DigitalOcean client went with it — including `sweep-idle --apply`, which builds that client before the park loop. **The idle sweep could not park any box at all**, hidden because the suite's only `apply: true` test relied on the veto emptying the idle set before `makeDo()` was reached: one bug shielded by the other. **Decision: a box may not stay active longer than `BOX_UNATTENDED_MAX_HOURS` (12) without evidence a HUMAN was attached.** The heartbeat already computed that signal and folded it into one boolean; it now reports `attached` separately (login session, inbound SSH, open ttyd, or an ATTACHED tmux client via `#{session_attached}` — the signal that separates this box from a working one) and the server stamps `last_attached_at`. `claude_active` keeps its veto but it EXPIRES, bounded by a `claude_active_since` edge stamp. `pgrep -x claude` and the load floor remain reasons the box PINGS, never evidence anyone is THERE — a running process is not a person, and that distinction is the whole decision. The two `NULL` defaults deliberately DISAGREE: `last_attached_at` NULL means "no data" and keeps a pre-1003507 box on the old behaviour (core_238 pointedly does NOT backfill it — a backfilled `now()` starts a clock nothing can advance and parks every un-upgraded box one cap later, and box source sync is not prompt: idea 1000745 records 257 commits behind for three days), while `claude_active_since` NULL is REFUSED because an unknown latch age is the forever-latch itself, and is backfilled so the state is unreachable after deploy. 12h because parking is reversible since task 1002726 (snapshot kept), so a false positive costs one wake against $20.21 for no cap. Both clocks clear at park/wake/deprovision, or a woken box inherits an expired latch and is parked instantly — the fix reintroducing the bug from the far side. Rejected: tracking attachment INSTEAD of bounding the latch (the silent box keeps `true` forever, so the reported hole survives); bounding the latch alone (built first, and the verification probe caught it — the fresh heartbeat meant lifting the veto changed nothing); deleting the load floor (it is what makes an autonomous run count); measuring from `active_since` (that is uptime — parks a box worked on for days); raising `BOX_IDLE_MINUTES` (no threshold reaches an unbounded veto).](<redacted>.md) | dev box / cost / idle sweep |
 | 0278 | [**A gated project still takes applications, and the exemption is scoped to the verb** ([task 1003525](https://cloudbongos.com/builders#/task/1003525) · the apply write itself in [task 1003624](https://cloudbongos.com/builders#/task/1003624) · goal 1000106 — *Working area 1, Project creation*; owner decision 2026-09-11). A project's owner sets who may SEE it (`platformVisibility`, [ADR 0192](<redacted>.md)) and who may JOIN it (`joinability`, [ADR 0194](<redacted>.md)) independently — and set to their middle values, members-only AND apply-to-join, the project took no applications at all: the member door refused every cookie-less request with `401` before the public `POST <api>/access-requests` could answer, because that write was not on the exempt list. The two settings composed into **"nobody can apply"**, which nobody chose. It survived because nothing LIED about it — the hub's join box relayed the project's own `401` honestly as `members_only`, and the hall's landing, where the apply form lives, is itself behind the door; the composition was simply unreachable. Found by the R14 proof ([task 1002333](https://cloudbongos.com/builders#/task/1002333)). ADR 0192 §3 had fixed the exempt list at "the door, the manifest, the probes and the downloads — and nothing wider" and left widening it as an owner call, which is what this is. **Decision: yes — and BOTH halves are exempted, each scoped to one path and one verb.** `POST <api>/access-requests` (it grants nothing — an application is a row in a queue the owner still reviews, [ADR 0201](<redacted>.md), already public on every non-gated project) and `GET <api>/access-requests/status` (without it the answer is half an answer: `bongos login` cannot re-poll the device flow after a `not_approved` — the `device_code` is spent — so an applicant would file a request and then wait on an approval they can never observe). `EXEMPT` entries may now be `{ re, methods }` beside the bare `RegExp`s, and `isExempt(path, method)` takes the verb as an OPTIONAL second argument that **fails closed** for a scoped entry when none is given, so the one-argument static callers cannot accidentally widen. **The verb is load-bearing, not tidiness:** the bare `GET` on `<api>/access-requests` is the OWNER'S QUEUE (`requireBuilder` + `access_request.review`), the surface listing would-be builders by name with their vouch state — a path-only exemption would have silently taken the member door off the front of it, leaving one layer where there were two, and the queue's own `requirePermission` still holding is exactly what makes that loss easy to miss. **It opens no oracle the gate was closing:** the status route's boolean twin `GET <api>/auth/web/admission-status` is ALREADY reachable on a gated project inside the `auth/*` subtree §3 exempts whole (§3 records that cost in as many words), and the two share ONE per-IP budget on purpose ([ADR 0209](<redacted>.md)) so neither can be alternated against the other. What it DOES add, stated as the honest cost: applicant detail — `pending`/`dismissed`/`none` over the twin's bare `admitted`. Whether that answer should collapse is ADR 0209's still-open owner question and is deliberately NOT decided here. No hub change: `joinRelayOutcome` maps the RELAYED status, so it carries the project's real answer the moment the `401` stops. Rejected: "gated means gated" — hide *Apply to join* and say so in the manage blurb (coherent, and the call went the other way); exempting the path without the verb; exempting the write alone; collapsing the status response while the route happened to be open (that is how a deferred decision gets made by accident).](<redacted>.md) | project visibility / join door / member door |
 | 0279 | [**An upgrade is proven by the served version, not by a health check** ([task 1002884](https://cloudbongos.com/builders#/task/1002884) · goal 1000090 — *Working area 4, Bongos Core distribution*; from idea 1000682). On 2026-08-11 the auto-upgrade sweep printed `✓ upgrade complete — core 1.19.13 → 1.19.56`, wrote a success row to `core_upgrades` and exited 0 while live kept serving **1.19.13**. Three shipped checks formed a closed loop that could not see the failure they existed to catch: the `systemctl restart` failed with `Interactive authentication required` (a `User=` unit, no TTY) and `upgrade.js` treated it as a WARNING and fell through; `readInstalledCoreVersion()` then confirmed the version on **disk**, where `npm install` had correctly put it; and `pollHealth()` got a 200 from the **still-running old process**, because a health check confirms a port is served, never *what* serves it. A lying tool is worse than a broken one — nothing goes looking. The damage outlived the incident: `subscribe.js` had already routed the unattended lane around `bongos upgrade` in favour of `go-live.js`, citing this false-pass in a comment. **Decision: a bump is confirmed by asking the running process what version it is.** (1) A failed restart enters the same auto-rollback path as a failed install/migrate/health and exits non-zero — rolling back rather than merely erroring keeps disk and process consistent, since disk-ahead-of-process is the state that made the incident invisible. (2) The served version is read back from `/version` (`coreVersion`, since 1.17.2, prelaunch-gate exempt), defaulting to the `--health-url` origin and overridable via `--version-url` — derived rather than opt-in because every existing call site passes only `--health-url`, and a check you must opt into is off exactly where it is needed. (3) A **mismatch** fails (proof of failure → roll back); an **unreadable** endpoint only warns (absence of proof — refusing every such bump would regress harder than the false-pass), except under an explicit `--version-url`, which asks for proof and therefore gets a failure. That strict mode is what the unattended subscription lane now passes, its roster already carrying the URL. **Escalation is `sudo -n`, not a hand-placed polkit rule:** `restartService()` retries a failed restart through `sudo -n` when not root — the idiom `dev.js`/`dev-lib.js` already use and consistent with `provision.js`, `upgrade.js` having been the one place that restarted without escalating. The live `/etc/polkit-1/rules.d/<redacted>.rules` mitigation is superseded: a rebuilt box inherits code, not hand-placed `/etc` files (polkit route kept in [`docs/recipes/instance-service-restart.md`](../recipes/instance-service-restart.md)). `--no-health-check` stays the single escape hatch and now waives the read-back too. Rejected: comparing `startedAt` (cannot distinguish a restart onto the same old core from one onto the new); making an unreadable endpoint fatal by default; requiring `--version-url` everywhere (absent from every current call site — the same "off where it matters" failure in a new costume); keeping polkit as the answer.](<redacted>.md) | core distribution / upgrade verification |
+| 0280 | [**The unattended lane may drive a co-tenant, because the roster entry IS the per-instance decision** ([task 1003843](https://cloudbongos.com/builders#/task/1003843) · goal 1000106; from [task 1003521](https://cloudbongos.com/builders#/task/1003521), which built co-tenant mode into `go-live.js` and deliberately left this caller alone). `subscribe.js` keeps a SECOND COPY of go-live's target contract, and it drifted: `GO_LIVE_REQUIRED` still listed `deployTimer` after 1003521 made it optional, so `goLiveTargetFor()` returned `missing: ['deployTimer']` for every provisioned co-tenant, and `rawTopologyFor()`'s fixed field list dropped `pinMode` before the target was built — the same stale-normalizer trap that function's own comment was written to fix, one field later. **1003521 deferred this as a policy judgement call; reading the fallback shows the premise was wrong.** `mapped.ok === false` never meant "skip this instance" — it meant "deploy it the WEAKER way": a bare `bongos upgrade`, no backup, no deploy-timer guard, and a pin COMMITTED AND PUSHED into the co-tenant's own repo, which is exactly what `pinMode` exists to prevent. The lane was already auto-deploying co-tenants; the only open question was whether it did so well. A THIRD defect sat behind the other two and would have turned the silent downgrade into a hard failure had only the first been fixed: the normalizer yields `deployTimer: null`, an explicit null SURVIVES `JSON.stringify` into `--target-json`, and go-live's `validateTarget` runs `isSafeToken(null)` on it and rejects the whole target. A FOURTH sat PAST the go-live call and is what separates "reachable" from "safe": after any successful upgrade the lane runs its own pin net, `commitPin()`, which commits the pin files and PUSHES them to `origin` — a net that predates `pinMode`. Under `local-commit` go-live leaves the tree clean so it no-ops by luck; under **`leave-dirty`** the pin is in the working tree BY DESIGN, so the net committed it and pushed it into the customer's own repo — the lane honouring `pinMode` right up to the moment it undid it. **Decision: the lane may drive a co-tenant and needs no new gate, because listing an instance in `config/update-subscriptions.json` already IS the explicit per-instance operator decision** — the roster ships empty, nothing is touched until an operator lists it, and the routine is autonomy-gated (`requiresAutonomy: true`, default OFF) on top of that; a second consent gate asks the same person the same question twice. So: `GO_LIVE_REQUIRED` now MIRRORS go-live's `REQUIRED_FIELDS`, with a test reading BOTH source files and failing on drift; `deployTimer` moves to the optional-field loop so a co-tenant OMITS the key rather than carrying a null; `rawTopologyFor` carries `pinMode`; `resolveGoLive` gains a `needsCoTenant` probe leg; and `goLiveEngineFor()` makes the decision ONCE for both the dry run and the apply path, which had re-derived it separately. The pin net now obeys the same `pinMode` go-live was given — `commitPin()` takes `push` (default true, so the platform instance is unchanged), `local-commit` commits without pushing, `leave-dirty` skips the net, the rollback tidy follows the same rule, and the "not durable" advice stops telling an operator to `git push` a repo we do not own; its refusal to touch a worktree carrying NON-pin changes is unchanged in every mode. **The probe is CONDITIONAL on purpose** — demanding `pinMode` of every target would strip the go-live path from any instance between the `--target-json` release and 1003521's, trading a live regression for a hypothetical one. Rejected: a second consent gate (an `allowCoTenant` flag); deferring to the unspecced fleet control plane ([task 1001948](https://cloudbongos.com/builders#/task/1001948)) — which does not leave co-tenants alone, it leaves them pushing pins into customer repos; dropping `deployTimer` from `GO_LIVE_REQUIRED` and nothing else (the fix as proposed — trades a silent downgrade for a hard rejection); probing unconditionally; reaching co-tenant mode WITHOUT teaching the durability net about it (nominal support that breaks its own promise seconds later); and teaching `loadSubscriptions()` about `pinMode` instead, since that normalizer ships in the control plane's vendored core that nobody bumps — the exact trap `rawTopologyFor` routes around.](<redacted>.md) | core distribution / unattended deploy |

package/docs/module-api-changelog.md

@@ -1821,5 +1821,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.679 with no explicit bump. run 34665216511. (task 1002620)
   1.19.681 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.680 with no explicit bump. run 34666648354. (task 1002620)
+  1.19.682 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.681 with no explicit bump. run 34704993368. (task 1002620)
+  1.19.683 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.682 with no explicit bump. run 34706984747. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/conflict-resolve.js

@@ -311,6 +311,19 @@ const GENERATOR_SCRIPTS = [
   // burned the attempt cap, and announceStrand flagged the task needs_rebase
   // (PR #536 / task 1003544).
   'scripts/gds/copy-inventory.js',
+  // task 1003537: the generated API contract + client. gen-api-docs.js writes
+  // docs/api/openapi.json + docs/api-reference.md + docs/routes-permissions.md from a
+  // scan of the route files; gen-api-client.js then writes the six
+  // clients/bongos-client files FROM that spec. Both are `--check` gates on the merge
+  // ref, so the same trap copy-inventory.js fell into applies verbatim: covered by the
+  // merge driver, regenerated by nobody, and the resulting staleness reported as
+  // `no_regen_diff` — "a real check failure" — rather than as drift.
+  //
+  // ORDER IS LOAD-BEARING: gen-api-client.js reads docs/api/openapi.json off disk, so
+  // it must run AFTER gen-api-docs.js has rewritten it for the merged tree. This list
+  // is walked in order, one await at a time, which is what makes that safe.
+  'scripts/gds/gen-api-docs.js',
+  'scripts/gds/gen-api-client.js',
 ];
 
 // Run the CLONE's generator scripts in WRITE mode against the merged working tree.

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.681",
+  "version": "1.19.683",
   "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/gen-api-client.js

@@ -487,8 +487,13 @@ function renderReadme(spec, ops) {
   ].join('\n');
 }
 
-function build() {
-  const spec = JSON.parse(fs.readFileSync(SPEC_PATH, 'utf8'));
+// injectedSpec (task 1003537): the otb-regen merge driver regenerates this client
+// DURING a merge, when docs/api/openapi.json on disk may be the conflicted file git has
+// just written markers into — JSON.parse would throw on it. Passing a spec built in
+// memory keeps the heal working and keeps the client consistent with the api-reference.md
+// the same merge resolves. Omitted everywhere else, so the CLI path is unchanged.
+function build(injectedSpec) {
+  const spec = injectedSpec || JSON.parse(fs.readFileSync(SPEC_PATH, 'utf8'));
   const ops = buildModel(spec);
   const esm = renderClientJs(spec, ops);
   return {

package/scripts/gds/git-merge-regen.js

@@ -54,9 +54,40 @@ const G = require('./gen-repo-map');
 const FM = require('./gen-file-map');
 const SI = require('./gen-session-index');
 const CI = require('./copy-inventory');
+// gen-api-docs / gen-api-client are required LAZILY, inside the two rules that use them —
+// deliberately NOT here (task 1003537). gen-api-docs pulls src/bongos/routes/_helpers.js
+// for its LIMITS caps, and ship.js requires this module, so an eager require put a server
+// route file into the boot of every `bongos` subcommand. tests/module_api_lazy.mjs catches
+// exactly that. require() is cached, so the merge path pays the load once and the CLI
+// path never pays it at all.
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
+// The generated API contract (task 1003537). gen-api-docs.js writes all three of these
+// wholesale from a scan of the route files, so one build() call answers whichever of
+// them git hands us.
+const API_DOC_FILES = new Set([
+  'docs/api/openapi.json',
+  'docs/api-reference.md',
+  'docs/routes-permissions.md',
+]);
+
+// The generated client (task 1003537), written wholesale from the spec by
+// gen-api-client.js. These six names mirror the keys of its build().files; the
+// lockstep is asserted in tests/git_merge_regen.mjs rather than derived here, because
+// deriving it would mean running the generator at require time. NOTE what is absent:
+// clients/bongos-client/examples/hello-world.mjs is hand-written and must stay out of
+// this set, or the driver would force a conflict on a file git can merge by itself.
+const API_CLIENT_DIR = 'clients/bongos-client';
+const API_CLIENT_FILES = new Set([
+  'index.mjs',
+  'index.cjs',
+  'bongos-client.global.js',
+  'index.d.ts',
+  'package.json',
+  'README.md',
+].map((n) => `${API_CLIENT_DIR}/${n}`));
+
 // The files this driver knows how to regenerate. docs/repo-map.md and
 // docs/session-log-index.md are whole-file; each NESTED_DIRS CLAUDE.md is
 // hand-written prose with one generated block; docs/file-map.md is hand-written
@@ -73,6 +104,10 @@ const REPO_ROOT = path.resolve(__dirname, '..', '..');
 // that each add a session-log file regenerate that block differently and ALWAYS conflict
 // there, and nothing healed it: the driver did not know the file, and `merge=union` would be
 // wrong for prose. Same shape as docs/file-map.md (3-way-merge the prose, re-render the block).
+// task 1003537: the two API sets above are spread in whole — every one of those nine files
+// is generated end to end, so they take the docs/repo-map.md path (ignore all three merge
+// sides, rebuild). They are named up there rather than inline here because the rules below
+// test set membership, and tests/git_merge_regen.mjs cross-checks them against .gitattributes.
 const REGENERABLE = new Set([
   'CLAUDE.md',
   'docs/repo-map.md',
@@ -81,6 +116,8 @@ const REGENERABLE = new Set([
   'docs/copy-inventory.md',
   'docs/copy-registry.json',
   ...G.NESTED_DIRS.map((d) => `${d}/CLAUDE.md`),
+  ...API_DOC_FILES,
+  ...API_CLIENT_FILES,
 ]);
 
 // A line that begins with a git conflict marker. If any survives our resolution,
@@ -137,6 +174,33 @@ function regenerateResolved(relpath, { base = '', ours = '', theirs = '' } = {})
     return { content: CI.renderReport(CI.buildRegistry()), ok: true };
   }
 
+  // The generated API contract (task 1003537): gen-api-docs.js writes openapi.json,
+  // api-reference.md and routes-permissions.md wholesale from a scan of the route files
+  // — nothing hand-authored in any of them — so like docs/repo-map.md below they ignore
+  // all three merge sides and rebuild. One build() yields all three; take the one asked
+  // for. This is the rule that ends the task-1002334 stall, where four merge → reship
+  // cycles each lost the race to a fresh textual conflict in exactly these files.
+  if (API_DOC_FILES.has(relpath)) {
+    const AD = require('./gen-api-docs'); // lazy — see the require block up top
+    const f = AD.build().files.find((x) => x.rel === relpath);
+    return { content: f.content, ok: true };
+  }
+
+  // The generated client (task 1003537): gen-api-client.js renders all six files from
+  // the spec, so it heals the same way. Hand it a FRESHLY BUILT spec instead of letting
+  // build() read docs/api/openapi.json off disk — mid-merge that file is very often the
+  // one git has just written conflict markers into, and JSON.parse would throw on them
+  // (an uncaught throw here exits non-zero, which git reads as "unresolved", so the
+  // failure would be a silent fallback to a textual conflict on the very files this
+  // rule exists to heal). Rebuilding also keeps the client consistent with the
+  // api-reference.md the same merge is healing.
+  if (API_CLIENT_FILES.has(relpath)) {
+    const AD = require('./gen-api-docs');   // lazy — see the require block up top
+    const AC = require('./gen-api-client'); // lazy — same reason
+    const { files } = AC.build(AD.buildOpenapi(AD.extractModel()));
+    return { content: files[relpath.slice(API_CLIENT_DIR.length + 1)], ok: true };
+  }
+
   // The ROOT CLAUDE.md (task 1001431): hand-written prose carrying ONE generated block, the
   // §13 session-log snippet. 3-way-merge the prose, then re-render the snippet from the
   // session-log files on disk. Must be handled BEFORE the nested-CLAUDE.md fallthrough below,

package/scripts/gds/init.js

@@ -943,7 +943,7 @@ async function main(argv) {
       console.error(`init: could not derive the core version from ${path.basename(tgz)} — expected a tarball named ${upgrade.ARTIFACT}-<version>.tgz (produced by \`node scripts/gds/package-core.js\`).`);
       return 1;
     }
-    const vendorRel = path.join('vendor', `${upgrade.ARTIFACT}-${version}.tgz`);
+    const vendorRel = upgrade.vendorRelFor(version);
     coreDep = `file:${vendorRel}`;
     vendorPlan = { tgz, version, vendorRel };
   }

package/scripts/gds/upgrade.js

@@ -34,6 +34,16 @@ const { writeNpmrc, hasNpmToken, resolveNpmToken } = require('./npmrc'); // ADR
 
 const CORE_PKG = '@bongos/core';
 const ARTIFACT = 'bongos-core';
+// WHERE THE VENDORED TARBALL SITS, as a package.json `file:` specifier — and the reason
+// this is not a path.join(). The same string is spent two ways: it is joined onto an
+// absolute dir for an fs check (path.join normalises a forward slash on every platform,
+// so that direction is free), and it is WRITTEN INTO package.json as `file:<vendorRel>`.
+// npm specifiers are POSIX. A path.join() here emits `file:vendor\\bongos-core-x.y.z.tgz`
+// on a Windows builder's machine, and that pin is then COMMITTED to the instance repo —
+// where the provisioner runs `npm ci` on Linux and reads a literal backslash in the
+// filename. One copy, POSIX by construction, so a scaffold cannot be platform-stamped
+// by the box that happened to run the scaffolder (task 1003839).
+function vendorRelFor(version) { return path.posix.join('vendor', `${ARTIFACT}-${version}.tgz`); }
 
 // ---- pure helpers (no I/O side effects beyond the injected fs) --------------
 
@@ -245,7 +255,7 @@ function vendorTarball({ instanceDir, fromTgz, targetVersion }, fsImpl = fs) {
   if (fsImpl.existsSync(fromManifest)) {
     fsImpl.copyFileSync(fromManifest, path.join(vendorDir, `${ARTIFACT}-${targetVersion}.manifest.json`));
   }
-  return path.join('vendor', destName);
+  return path.posix.join('vendor', destName);
 }
 
 // Lightweight module-compat pre-check reusing module.js against the TARGET core version. Best-effort:
@@ -940,10 +950,10 @@ async function runUpgrade(opts, deps = {}) {
     if (!dryRun) { writeNpmrc(instanceDir, { fsImpl, overwrite: false, log }); snapshot = { prevPin, prevVersion: fromVersion }; }
     log(`  ${dryRun ? '[dry-run] would pin' : '✓ pinned'} ${CORE_PKG} → ${targetVersion} (registry)${dryRun ? ' + write an env-fed .npmrc' : ''}${prevPin ? `  (was ${prevPin})` : ''}`);
   } else {
-    let vendorRel = opts.pinPath || (opts.from ? null : path.join('vendor', `${ARTIFACT}-${targetVersion}.tgz`));
+    let vendorRel = opts.pinPath || (opts.from ? null : vendorRelFor(targetVersion));
     if (opts.from) {
       if (!fsImpl.existsSync(opts.from)) return { ok: false, error: `--from tarball not found: ${opts.from}` };
-      if (dryRun) { log(`  [dry-run] would vendor ${opts.from} → vendor/${ARTIFACT}-${targetVersion}.tgz`); vendorRel = path.join('vendor', `${ARTIFACT}-${targetVersion}.tgz`); }
+      if (dryRun) { log(`  [dry-run] would vendor ${opts.from} → vendor/${ARTIFACT}-${targetVersion}.tgz`); vendorRel = vendorRelFor(targetVersion); }
       else vendorRel = vendorTarball({ instanceDir, fromTgz: path.resolve(opts.from), targetVersion }, fsImpl);
     }
     if (!fsImpl.existsSync(path.join(instanceDir, vendorRel)) && !dryRun) {
@@ -1225,7 +1235,7 @@ module.exports = {
   versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
   vendorTarball, gitTreeClean, persistPin, dirtyPinFiles, gitCurrentBranch, PIN_FILES, preflightDbIdentity, resolveInstanceDb, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth, deriveVersionUrl, pollServedVersion,
   readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification
-  CORE_PKG, ARTIFACT,
+  CORE_PKG, ARTIFACT, vendorRelFor,
 };
 
 if (require.main === module) {

package/scripts/gds/worktree.js

@@ -31,6 +31,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const { arg, hasFlag } = require('./cli-lib');
+const { registerMergeDriver, MERGE_DRIVER_NAME } = require('./install-git-hooks');
 
 // -- pure helpers (exported for tests/worktree_helper.mjs) --------------------
 
@@ -145,6 +146,25 @@ function cmdAdd(root, argv) {
     process.exit(1);
   }
 
+  // Register the otb-regen merge driver (task 1003537). .gitattributes routes the
+  // generated files through it, but git honours that ONLY where merge.otb-regen.driver is
+  // configured — which install-git-hooks.js does per CLONE, on /builder-setup. A builder
+  // who never ran the installer got a silent TEXTUAL merge of files no textual merge can
+  // resolve: measured on task 1002334, a scripts/gds/CLAUDE.md symbol block matching
+  // neither generator, clean enough that nothing flagged it until fitness ran in CI.
+  // Worktree-per-claim is the default path to a new tree, so doing it here is what closes
+  // that gap for a clone whose owner never ran setup. git config is shared with every
+  // linked worktree, so registering against the main root covers this tree and all later
+  // ones. Idempotent, and best-effort on purpose: failing to register only restores the
+  // pre-existing fallback-to-conflict behaviour, which must never fail `worktree add`.
+  const driver = registerMergeDriver(root);
+  if (driver.ok) {
+    console.log(`  merge driver '${MERGE_DRIVER_NAME}' registered (generated files auto-regenerate on merge)`);
+  } else {
+    console.log(`  ⚠ could not register the '${MERGE_DRIVER_NAME}' merge driver: ${driver.error}`);
+    console.log('    (generated files will merge textually here; ship.js still self-heals the same set)');
+  }
+
   if (needsJunction({ wtPath, repoRoot: root, platform: process.platform })) {
     const target = path.join(root, 'node_modules');
     if (!fs.existsSync(target)) {

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

@@ -562,6 +562,19 @@ test('1003546 every REGENERABLE artifact has a producer, and every producer is i
     [CI.REGISTRY_REL, 'scripts/gds/copy-inventory.js'],
     [CI.REPORT_REL, 'scripts/gds/copy-inventory.js'],
     ...G.NESTED_DIRS.map((d) => [`${d}/CLAUDE.md`, 'scripts/gds/gen-repo-map.js']),
+    // task 1003537 — the generated API contract + client joined REGENERABLE. Mapped by
+    // PATH PREFIX rather than by calling the generators: this suite deliberately sets
+    // *_INSTANCE_ROOT (see the env-hardening case above), which repoints their docs root
+    // at a fake server checkout, so a build() here reads a file that does not exist.
+    // Nothing is lost by not running them — drift between REGENERABLE and what they
+    // actually write is pinned by tests/git_merge_regen.mjs case 11, and a future entry
+    // under either prefix is picked up here automatically.
+    ...[...regen.REGENERABLE]
+      .filter((p) => p.startsWith('docs/api/') || p === 'docs/api-reference.md' || p === 'docs/routes-permissions.md')
+      .map((p) => [p, 'scripts/gds/gen-api-docs.js']),
+    ...[...regen.REGENERABLE]
+      .filter((p) => p.startsWith('clients/bongos-client/'))
+      .map((p) => [p, 'scripts/gds/gen-api-client.js']),
   ]);
 
   for (const p of regen.REGENERABLE) {

package/tests/git_merge_regen.mjs

@@ -28,6 +28,12 @@
 //      the merge's OWNER must regenerate afterwards (conflict-resolve.js step 7b).
 //      Needs a real clone (the driver's __dirname must BE the merging tree), so it
 //      skips where the environment cannot host that.
+//  11. The generated API contract + client (task 1003537) — docs/api/openapi.json,
+//      docs/api-reference.md, docs/routes-permissions.md and the six
+//      clients/bongos-client files regenerate clean from the merged tree, the client
+//      heals even when the on-disk spec is the conflicted file, and the driver's file
+//      list still matches what gen-api-client actually writes. Also pins the ABSENCE of
+//      clients/bongos-client/examples/hello-world.mjs, which is hand-written.
 //
 // Run:  node tests/git_merge_regen.mjs
 
@@ -46,6 +52,8 @@ const regen = require('../scripts/gds/git-merge-regen.js');
 const G = require('../scripts/gds/gen-repo-map.js');
 const CI = require('../scripts/gds/copy-inventory.js');
 const SI = require('../scripts/gds/gen-session-index.js'); // task 1001431 — the root CLAUDE.md's §13 snippet
+const AD = require('../scripts/gds/gen-api-docs.js');   // task 1003537 — the generated API contract
+const AC = require('../scripts/gds/gen-api-client.js'); // task 1003537 — the generated client
 
 const MARKERS = /^(<{7}|={7}|>{7})/m;
 
@@ -438,4 +446,56 @@ function withBlockBody(src, body) {
   }
 }
 
+// ── 11) the generated API contract + client (task 1003537) ─────────────────────
+// gen-api-docs.js and gen-api-client.js write nine fully generated files that used to
+// merge textually, so any branch touching a route conflicted with every concurrent land
+// (task 1002334: four merge → reship cycles, each beaten by a fresh conflict). They heal
+// like docs/repo-map.md — all three merge sides ignored, rebuilt from the merged tree.
+{
+  const conflicted = (a, b) => `<<<<<<< ours\n${a}\n=======\n${b}\n>>>>>>> theirs\n`;
+
+  // (a) the three doc artifacts rebuild to exactly what the generator would write.
+  const fresh = new Map(AD.build().files.map((f) => [f.rel, f.content]));
+  for (const rel of ['docs/api/openapi.json', 'docs/api-reference.md', 'docs/routes-permissions.md']) {
+    const r = regen.regenerateResolved(rel, {
+      base: 'base\n', ours: conflicted('{"a":1}', '{"b":2}'), theirs: 'nonsense\n',
+    });
+    assert.equal(r.ok, true, `${rel} heal must succeed`);
+    assert.ok(!MARKERS.test(r.content), `${rel} heal must leave no conflict markers`);
+    assert.equal(r.content, fresh.get(rel), `${rel} heal must equal a fresh generation`);
+  }
+
+  // (b) the six client files do too. The driver rebuilds the spec in memory rather than
+  // reading docs/api/openapi.json, so this must hold no matter what is on disk.
+  const freshClient = AC.build().files;
+  for (const [name, content] of Object.entries(freshClient)) {
+    const rel = `clients/bongos-client/${name}`;
+    const r = regen.regenerateResolved(rel, {
+      base: 'base\n', ours: conflicted('one', 'two'), theirs: 'nonsense\n',
+    });
+    assert.equal(r.ok, true, `${rel} heal must succeed`);
+    assert.ok(!MARKERS.test(r.content), `${rel} heal must leave no conflict markers`);
+    assert.equal(r.content, content, `${rel} heal must equal a fresh generation`);
+  }
+
+  // (c) LOCKSTEP: the driver's hardcoded client list must be exactly what the generator
+  // writes. Without this, a seventh generated client file would be added to
+  // gen-api-client.js and silently fall back to a textual merge — the original defect.
+  const declared = [...regen.REGENERABLE]
+    .filter((f) => f.startsWith('clients/bongos-client/'))
+    .map((f) => f.slice('clients/bongos-client/'.length))
+    .sort();
+  assert.deepEqual(declared, Object.keys(freshClient).sort(),
+    'REGENERABLE\'s clients/bongos-client entries must match gen-api-client build().files exactly');
+
+  // (d) the hand-written example must stay OUT. A `clients/bongos-client/*` glob would
+  // have swept it in, and the driver has no rule for it — so git would be forced into a
+  // conflict on a file it can merge by itself (the /CLAUDE.md leading-slash trap again).
+  assert.ok(!regen.REGENERABLE.has('clients/bongos-client/examples/hello-world.mjs'),
+    'the hand-written example must never be routed through the regenerating driver');
+  assert.equal(regen.regenerateResolved('clients/bongos-client/examples/hello-world.mjs',
+    { base: 'a\n', ours: 'b\n', theirs: 'c\n' }).content, null,
+    'a non-generated path under the client dir must not resolve');
+}
+
 console.log('git_merge_regen: all assertions passed');

package/tests/update_subscription_engine.mjs

@@ -0,0 +1,415 @@
+// tests/update_subscription_engine.mjs
+//
+// task 1003843 — the nightly update lane can drive a CO-TENANT.
+//
+// `.claude/scheduled-tasks/core-update-subscription/subscribe.js` decides, per roster
+// entry, whether the bump goes through go-live.js (backup + timer guard + box-side
+// read-back) or falls back to a bare `bongos upgrade`. That decision reads a second,
+// hand-maintained copy of go-live's own target contract — and a copy drifts:
+//
+//   1. CONTRACT DRIFT. go-live made `deployTimer` optional for co-tenant mode (task
+//      1003521); GO_LIVE_REQUIRED here kept requiring it, so every provisioned
+//      co-tenant was told its entry "lacks deployTimer" and silently took the weaker
+//      path forever. The first test pins the two lists TOGETHER, at the source, so the
+//      next move of go-live's contract fails here instead of degrading a live deploy.
+//   2. A NULL IS NOT AN ABSENT FIELD. The normalizer yields `deployTimer: null`, and
+//      that null survives JSON.stringify into --target-json, where go-live's
+//      validateTarget runs isSafeToken(null) and rejects the whole target. Dropping
+//      the field from GO_LIVE_REQUIRED alone would have traded a silent downgrade for
+//      a hard failure, so the target must OMIT the key, not carry a null.
+//   3. THE STALE NORMALIZER, ONE FIELD LATER. rawTopologyFor reads topology straight
+//      off disk precisely because the control plane's vendored normalizer drops fields
+//      it predates. `pinMode` was the next field it predated.
+//   4. FAIL-CLOSED, BUT NOT OVER-CLOSED. An older go-live.js REJECTS a co-tenant target
+//      outright, so the capability probe must refuse it — while an instance on a
+//      mid-generation core must KEEP the go-live path it already has for ordinary
+//      targets.
+//
+// Every external is injected (readFile, resolveFrom) or written to a temp dir, so this
+// is DB-free, network-free and platform-independent. The source-reading test comes
+// FIRST: it is the half that pins the cross-file contract, and it must run even if a
+// later case trips.
+//
+// Run:  node --test tests/update_subscription_engine.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const S = require('../.claude/scheduled-tasks/core-update-subscription/subscribe.js');
+
+// A roster entry as loadSubscriptions() normalizes it: absent topology is an explicit
+// null, which is the shape that makes case 2 above possible.
+function entry(over = {}) {
+  return {
+    slug: 'demo', dir: '/srv/demo', service: 'demo.service',
+    healthUrl: 'http://127.0.0.1:3002/healthz', channel: 'patch',
+    versionUrl: null, deployTimer: null, deployService: null,
+    backupDb: null, backupDir: null, registryPackage: null, env: {},
+    ...over,
+  };
+}
+
+// Stand-ins for the two generations of go-live.js the probe has to tell apart. What
+// matters is only which capability markers the SOURCE carries.
+const GO_LIVE_OLD = 'usage: go-live.js --target-json <json> --to <version>\n';
+const GO_LIVE_NEW = `${GO_LIVE_OLD}const OPTIONAL_FIELDS = ['deployTimer', 'pinMode'];\n`;
+const GO_LIVE_ANCIENT = 'usage: go-live.js --target <name>   // ssh only, no local mode\n';
+
+function rosterDir(rows) {
+  const dir = mkdtempSync(path.join(tmpdir(), 'subscribe-engine-'));
+  mkdirSync(path.join(dir, 'config'), { recursive: true });
+  writeFileSync(path.join(dir, 'config', 'update-subscriptions.json'), JSON.stringify({ instances: rows }));
+  return dir;
+}
+
+// ---------------------------------------------------------------------------
+// 1. the cross-file contract — STATIC, reads both sources
+// ---------------------------------------------------------------------------
+
+test('GO_LIVE_REQUIRED mirrors go-live.js REQUIRED_FIELDS exactly', () => {
+  const src = readFileSync(path.join(ROOT, 'scripts', 'gds', 'go-live.js'), 'utf8');
+  const m = src.match(/const REQUIRED_FIELDS = \[([^\]]*)\]/);
+  assert.ok(m, 'could not find REQUIRED_FIELDS in scripts/gds/go-live.js');
+  const required = m[1].split(',').map((x) => x.trim().replace(/^'|'$/g, '')).filter(Boolean);
+
+  assert.deepEqual(
+    [...S.GO_LIVE_REQUIRED].sort(), [...required].sort(),
+    'subscribe.js keeps its own copy of go-live\'s required fields; they have drifted apart '
+    + '— a roster entry go-live would accept is being refused here (or the reverse)',
+  );
+  // Named outright, so the regression that started this task cannot come back quietly.
+  assert.ok(!S.GO_LIVE_REQUIRED.includes('deployTimer'), 'deployTimer is OPTIONAL — requiring it locks out every co-tenant');
+});
+
+test('go-live.js still accepts the pinMode the lane now sends', () => {
+  const src = readFileSync(path.join(ROOT, 'scripts', 'gds', 'go-live.js'), 'utf8');
+  const m = src.match(/const OPTIONAL_FIELDS = \[([^\]]*)\]/);
+  assert.ok(m, 'could not find OPTIONAL_FIELDS in scripts/gds/go-live.js');
+  // go-live reports UNKNOWN keys as errors rather than ignoring them, so sending a field
+  // it does not list is a hard rejection of the whole target, not a no-op.
+  assert.ok(m[1].includes("'pinMode'"), 'go-live no longer lists pinMode — the lane would now be sending an unknown field');
+});
+
+// ---------------------------------------------------------------------------
+// 2. the target a co-tenant produces
+// ---------------------------------------------------------------------------
+
+test('a co-tenant entry maps to a valid target: deployTimer is OMITTED, never null', () => {
+  const t = S.goLiveTargetFor(entry(), { versionUrl: 'http://127.0.0.1:3002/version', pinMode: 'local-commit' });
+  assert.equal(t.ok, true, `co-tenant entry should map; missing: ${JSON.stringify(t.missing)}`);
+  assert.equal('deployTimer' in t.target, false, 'the KEY must be absent — a null reaches go-live as an unsafe token and fails validateTarget');
+  // The wire form is what go-live actually sees.
+  assert.equal(JSON.parse(JSON.stringify(t.target)).deployTimer, undefined);
+  assert.equal(t.target.pinMode, 'local-commit');
+});
+
+test('a classic entry still carries its deployTimer', () => {
+  const t = S.goLiveTargetFor(entry({ deployTimer: 'demo-deploy.timer' }), { versionUrl: 'http://127.0.0.1:3002/version' });
+  assert.equal(t.ok, true);
+  assert.equal(t.target.deployTimer, 'demo-deploy.timer');
+  assert.equal('pinMode' in t.target, false, 'an entry that names no pinMode must not invent one — go-live defaults it to push');
+});
+
+test('a genuinely incomplete entry still reports what is missing', () => {
+  const t = S.goLiveTargetFor(entry({ healthUrl: null }), {});
+  assert.equal(t.ok, false);
+  assert.deepEqual(t.missing, ['healthUrl', 'versionUrl']);
+});
+
+test('rawTopologyFor reads pinMode off disk', () => {
+  const dir = rosterDir([{ slug: 'demo', dir: '/srv/demo', versionUrl: 'http://x/version', pinMode: 'leave-dirty' }]);
+  const raw = S.rawTopologyFor(dir, 'demo');
+  assert.equal(raw.pinMode, 'leave-dirty', 'pinMode is dropped before the target is built — the stale-normalizer trap, one field later');
+  assert.equal(raw.versionUrl, 'http://x/version');
+});
+
+// ---------------------------------------------------------------------------
+// 3. which targets need co-tenant support
+// ---------------------------------------------------------------------------
+
+test('needsCoTenantMode: no deployTimer, or any pinMode', () => {
+  assert.equal(S.needsCoTenantMode({ deployTimer: 'd.timer' }), false);
+  assert.equal(S.needsCoTenantMode({}), true, 'no deployTimer is co-tenant mode');
+  assert.equal(S.needsCoTenantMode({ deployTimer: 'd.timer', pinMode: 'local-commit' }), true, 'pinMode is an unknown field to an older go-live');
+  assert.equal(S.needsCoTenantMode(null), false);
+});
+
+// ---------------------------------------------------------------------------
+// 4. the capability probe — fail-closed, but not over-closed
+// ---------------------------------------------------------------------------
+
+const probe = (source, opts) => S.resolveGoLive('/srv/demo', {
+  resolveFrom: () => '/srv/demo/node_modules/@bongos/core/scripts/gds/go-live.js',
+  readFile: () => source,
+  ...opts,
+});
+
+test('probe: a co-tenant target refuses a go-live.js without pinMode', () => {
+  assert.equal(probe(GO_LIVE_NEW, { needsCoTenant: true }), '/srv/demo/node_modules/@bongos/core/scripts/gds/go-live.js');
+  assert.equal(probe(GO_LIVE_OLD, { needsCoTenant: true }), null, 'that go-live would reject the target on a validation error instead of falling back');
+});
+
+test('probe: an ORDINARY target still runs on a mid-generation core', () => {
+  // The regression to avoid: probing for pinMode unconditionally would strip the
+  // go-live path from every instance sitting between the two releases.
+  assert.equal(probe(GO_LIVE_OLD, { needsCoTenant: false }), '/srv/demo/node_modules/@bongos/core/scripts/gds/go-live.js');
+  assert.equal(probe(GO_LIVE_ANCIENT, { needsCoTenant: false }), null, 'no --target-json: the pre-existing local-mode gate still holds');
+  assert.equal(probe(GO_LIVE_ANCIENT, { needsCoTenant: true }), null);
+});
+
+test('probe: an unreadable or unresolvable go-live falls back rather than throwing', () => {
+  assert.equal(S.resolveGoLive('/srv/demo', { resolveFrom: () => null, readFile: () => GO_LIVE_NEW }), null);
+  assert.equal(S.resolveGoLive('/srv/demo', {
+    resolveFrom: () => '/srv/demo/go-live.js',
+    readFile: () => { throw new Error('EACCES'); },
+  }), null);
+});
+
+// ---------------------------------------------------------------------------
+// 5. end to end: roster entry → engine
+// ---------------------------------------------------------------------------
+
+const engine = (rows, inst, source) => S.goLiveEngineFor(inst, rosterDir(rows), {
+  resolveFrom: () => '/srv/demo/node_modules/@bongos/core/scripts/gds/go-live.js',
+  readFile: () => source,
+});
+
+test('a co-tenant on a current core is driven by go-live, pinMode and all', () => {
+  const row = { slug: 'demo', dir: '/srv/demo', versionUrl: 'http://127.0.0.1:3002/version', pinMode: 'local-commit' };
+  const e = engine([row], entry(), GO_LIVE_NEW);
+  assert.ok(e.script, `should have chosen go-live; why: ${e.why}`);
+  assert.equal(e.coTenant, true);
+  assert.equal(e.mapped.target.pinMode, 'local-commit', 'the pin must not be pushed into the customer\'s own repo');
+  assert.equal('deployTimer' in e.mapped.target, false);
+  assert.equal(e.raw.versionUrl, 'http://127.0.0.1:3002/version', 'the fallback branch reads versionUrl off this');
+});
+
+test('a co-tenant on an older core falls back, and says why', () => {
+  const row = { slug: 'demo', dir: '/srv/demo', versionUrl: 'http://127.0.0.1:3002/version', pinMode: 'local-commit' };
+  const e = engine([row], entry(), GO_LIVE_OLD);
+  assert.equal(e.script, null);
+  assert.equal(e.coTenant, true);
+  assert.match(e.why, /co-tenant support/, `the operator has to be able to tell this apart from a malformed roster entry (got: ${e.why})`);
+});
+
+test('an entry missing topology falls back naming the fields, not the core', () => {
+  const e = engine([{ slug: 'demo', dir: '/srv/demo' }], entry(), GO_LIVE_NEW);
+  assert.equal(e.script, null);
+  assert.equal(e.coTenant, false);
+  assert.match(e.why, /roster entry lacks versionUrl/);
+});
+
+test('a classic entry on a current core is unchanged by all of this', () => {
+  const row = { slug: 'demo', dir: '/srv/demo', versionUrl: 'http://127.0.0.1:3002/version', deployTimer: 'demo-deploy.timer' };
+  const e = engine([row], entry(), GO_LIVE_NEW);
+  assert.ok(e.script);
+  assert.equal(e.coTenant, false);
+  assert.equal(e.mapped.target.deployTimer, 'demo-deploy.timer');
+});
+
+// ---------------------------------------------------------------------------
+// 6. the pin-durability net must not fight the target's own pin policy
+//
+// This is the half that makes co-tenant support real rather than nominal. go-live
+// honours pinMode correctly; the LANE then runs its own commit-and-push net over the
+// same repo afterwards, and that net predates pinMode. Under `leave-dirty` it found the
+// deliberately-dirty pin, committed it and PUSHED it — into the customer's own remote,
+// which is the single thing pinMode exists to prevent.
+// ---------------------------------------------------------------------------
+
+// A fake git that records every invocation and reports one dirty pin file.
+function fakeGit({ dirty = ['package.json'] } = {}) {
+  const calls = [];
+  const run = (_bin, args) => {
+    calls.push(args.slice(2)); // drop the leading -C <dir>
+    const sub = args[2];
+    if (sub === 'status') return { status: 0, stdout: dirty.map((f) => ` M ${f}`).join('\n') };
+    if (sub === 'rev-parse') return { status: 0, stdout: 'main\n' };
+    return { status: 0, stdout: '' };
+  };
+  return { run, calls, ran: (verb) => calls.some((c) => c[0] === verb) };
+}
+
+test('pinModeOf defaults to push, exactly as go-live does', () => {
+  assert.deepEqual(S.pinModeOf({}), { mode: 'push', valid: true });
+  assert.deepEqual(S.pinModeOf(null), { mode: 'push', valid: true });
+  assert.deepEqual(S.pinModeOf({ pinMode: 'local-commit' }), { mode: 'local-commit', valid: true });
+  assert.deepEqual(S.pinModeOf({ pinMode: 'leave-dirty' }), { mode: 'leave-dirty', valid: true });
+});
+
+test('pinModeOf REFUSES an unknown mode instead of defaulting', () => {
+  // Defaulting would send a typo to the push branch, and on a co-tenant that push lands in the
+  // customer's own repo. The safe-looking default is the dangerous one here.
+  assert.deepEqual(S.pinModeOf({ pinMode: 'local_commit' }), { mode: 'local_commit', valid: false });
+  assert.deepEqual(S.pinModeOf({ pinMode: 'leavedirty' }), { mode: 'leavedirty', valid: false });
+  assert.deepEqual(S.PIN_MODES, ['push', 'local-commit', 'leave-dirty']);
+});
+
+test('PIN_MODES mirrors go-live.js PIN_MODES exactly', () => {
+  const src = readFileSync(path.join(ROOT, 'scripts', 'gds', 'go-live.js'), 'utf8');
+  const m = src.match(/const PIN_MODES = \[([^\]]*)\]/);
+  assert.ok(m, 'could not find PIN_MODES in scripts/gds/go-live.js');
+  const theirs = m[1].split(',').map((x) => x.trim().replace(/^'|'$/g, '')).filter(Boolean);
+  assert.deepEqual([...S.PIN_MODES].sort(), [...theirs].sort(),
+    'the lane validates pinMode against its own copy of go-live\'s enum; they have drifted');
+});
+
+test('commitPin pushes by default — the platform instance still needs that', () => {
+  const g = fakeGit();
+  const r = S.commitPin({ dir: '/srv/demo', message: 'pin' }, g.run, () => {});
+  assert.equal(r.ok, true);
+  assert.equal(r.action, 'committed');
+  assert.equal(g.ran('push'), true, 'an unpushed pin on the platform instance is reverted by the next pull-deploy reset');
+});
+
+test('commitPin with push:false commits and STOPS', () => {
+  const g = fakeGit();
+  const r = S.commitPin({ dir: '/srv/demo', message: 'pin', push: false }, g.run, () => {});
+  assert.equal(r.ok, true);
+  assert.equal(r.action, 'committed-local');
+  assert.equal(g.ran('commit'), true, 'the pin must still be made durable locally');
+  assert.equal(g.ran('push'), false, 'the remote is the CUSTOMER\'s repo — pushing there is what pinMode forbids');
+});
+
+test('commitPin still refuses a worktree carrying non-pin changes', () => {
+  const g = fakeGit({ dirty: ['package.json', 'src/thing.js'] });
+  const r = S.commitPin({ dir: '/srv/demo', message: 'pin', push: false }, g.run, () => {});
+  assert.equal(r.ok, false);
+  assert.equal(r.action, 'refused');
+  assert.equal(g.ran('commit'), false, 'a human\'s uncommitted work must stop the lane regardless of pin mode');
+});
+
+// ---------------------------------------------------------------------------
+// 7. the HEAL step — the third place the pin gets written
+//
+// Found by the grader on round 1, and it is the worst of the three because it
+// fires on the HAPPY path. `leave-dirty`'s steady state after a successful
+// upgrade IS a dirty pin, so the next scheduled sweep's heal-first step saw it,
+// called it "a leftover from an earlier sweep", and committed + pushed it into
+// the customer's own repo — reliably, every sweep, not just after a crash.
+//
+// These cases drive commitPin the way main()'s heal branch does, since the heal
+// itself is inline in main() and not separately callable.
+// ---------------------------------------------------------------------------
+
+test('heal under local-commit commits WITHOUT pushing', () => {
+  const g = fakeGit();
+  const r = S.commitPin({ dir: '/srv/demo', message: 'leftover pin', push: false }, g.run, () => {});
+  assert.equal(r.ok, true);
+  assert.equal(r.action, 'committed-local');
+  assert.equal(g.ran('push'), false);
+});
+
+test('heal counts a local commit as healed, not as a no-op', () => {
+  // main() increments `healed` on 'committed' OR 'committed-local'; matching only the former
+  // would under-report every co-tenant heal as if nothing happened.
+  const g = fakeGit();
+  const r = S.commitPin({ dir: '/srv/demo', message: 'leftover pin', push: false }, g.run, () => {});
+  assert.ok(['committed', 'committed-local'].includes(r.action));
+});
+
+test('the heal branch is reachable only when the dirty files ARE the pin', () => {
+  // Unchanged by this work, re-pinned because the heal now has a third path through it.
+  const g = fakeGit({ dirty: ['package.json', 'docs/thing.md'] });
+  const r = S.commitPin({ dir: '/srv/demo', message: 'leftover pin', push: true }, g.run, () => {});
+  assert.equal(r.ok, false);
+  assert.equal(r.action, 'refused');
+  assert.equal(g.ran('commit'), false);
+});
+
+// ---------------------------------------------------------------------------
+// 8. the whole file, read as policy
+//
+// The three pin-writing sites are spread across ~250 lines of main(), and the
+// bug each time was a site that did not ask what mode it was in. A source-level
+// assertion is the only thing that sees all three at once.
+// ---------------------------------------------------------------------------
+
+test('every commitPin call site in the lane decides about push', () => {
+  const src = readFileSync(path.join(ROOT, '.claude', 'scheduled-tasks', 'core-update-subscription', 'subscribe.js'), 'utf8');
+  // Every CALL, excluding the definition (which is `function commitPin({ ... push = true })` —
+  // its default is what these sites must not silently inherit).
+  const calls = [];
+  const re = /commitPin\(\{/g;
+  let m;
+  while ((m = re.exec(src)) !== null) {
+    if (src.slice(Math.max(0, m.index - 9), m.index) === 'function ') continue;
+    // Brace-depth, not indexOf('}') — every message here carries a `${...}` whose own brace
+    // would otherwise end the slice before `push:` is ever reached.
+    let depth = 0, end = m.index;
+    for (let i = src.indexOf('{', m.index); i < src.length; i++) {
+      if (src[i] === '{') depth++;
+      else if (src[i] === '}' && --depth === 0) { end = i + 1; break; }
+    }
+    calls.push(src.slice(m.index, end));
+  }
+  assert.ok(calls.length >= 3, `expected the three known pin-writing call sites, found ${calls.length}`);
+  for (const c of calls) {
+    assert.match(c, /push:/, `a commitPin call site does not decide about push, so it inherits the default and pushes:\n${c}`);
+  }
+});
+
+test('the direct-upgrade fallback withholds --commit-pin unless the mode is push', () => {
+  const src = readFileSync(path.join(ROOT, '.claude', 'scheduled-tasks', 'core-update-subscription', 'subscribe.js'), 'utf8');
+  // --commit-pin makes upgrade.js commit AND push, so the fallback has to gate it too — the
+  // policy must not depend on which engine the instance's core happened to support.
+  assert.match(src, /if \(canCommitPin && pinMode === 'push'\) upArgs\.push\('--commit-pin'\)/,
+    'the fallback path would push a co-tenant pin through upgrade.js instead of the lane');
+});
+
+// ---------------------------------------------------------------------------
+// 9. healDecision — the grader's blocker, now reachable by a test
+//
+// This is the scenario that shipped past a green suite on round 1: under
+// `leave-dirty` the steady state after a successful upgrade IS a dirty pin, so
+// the NEXT sweep's heal step called it a leftover and pushed it to the
+// customer's own remote. On the happy path. Every sweep.
+// ---------------------------------------------------------------------------
+
+const dirtyPin = { repo: true, clean: false, pin: [{ file: 'package.json' }], other: [] };
+const dirtyHuman = { repo: true, clean: false, pin: [], other: [{ file: 'src/thing.js' }] };
+const cleanTree = { repo: true, clean: true, pin: [], other: [] };
+
+test('healDecision: leave-dirty is BY DESIGN, never a leftover', () => {
+  assert.deepEqual(S.healDecision(dirtyPin, 'leave-dirty'), { action: 'by-design' });
+});
+
+test('healDecision: local-commit heals WITHOUT pushing', () => {
+  assert.deepEqual(S.healDecision(dirtyPin, 'local-commit'), { action: 'commit', push: false });
+});
+
+test('healDecision: the platform default still commits and pushes', () => {
+  assert.deepEqual(S.healDecision(dirtyPin, 'push'), { action: 'commit', push: true });
+});
+
+test('healDecision: non-pin changes halt in EVERY mode', () => {
+  // A human's uncommitted work stops the lane whatever the pin policy is — checked in all three
+  // because 'by-design' is an early return and could easily be placed ahead of this.
+  for (const mode of ['push', 'local-commit', 'leave-dirty']) {
+    assert.deepEqual(S.healDecision(dirtyHuman, mode), { action: 'halt' }, `mode ${mode} must still halt`);
+  }
+});
+
+test('healDecision: a clean tree or a non-repo does nothing', () => {
+  assert.deepEqual(S.healDecision(cleanTree, 'push'), { action: 'nothing' });
+  assert.deepEqual(S.healDecision({ repo: false }, 'push'), { action: 'nothing' });
+  assert.deepEqual(S.healDecision(null, 'push'), { action: 'nothing' });
+});
+
+test('both commitPin successes report committed:true', () => {
+  // main() counts a heal off this ONE flag. Matching on action strings instead silently
+  // under-reported every co-tenant heal as if nothing had happened.
+  const a = S.commitPin({ dir: '/srv/demo', message: 'm' }, fakeGit().run, () => {});
+  const b = S.commitPin({ dir: '/srv/demo', message: 'm', push: false }, fakeGit().run, () => {});
+  assert.equal(a.committed, true);
+  assert.equal(b.committed, true);
+  assert.equal(S.commitPin({ dir: '/srv/demo', message: 'm' }, fakeGit({ dirty: [] }).run, () => {}).committed, undefined,
+    'an already-clean tree committed nothing and must not be counted as a heal');
+});

package/tests/upgrade.mjs

@@ -88,11 +88,51 @@ t('vendorTarball: copies the .tgz + side-car manifest under the canonical name',
   writeFileSync(join(src, 'bongos-core-1.15.0.manifest.json'), '{"v":1}');
   const dir = scratchConsumer();
   const rel = u.vendorTarball({ instanceDir: dir, fromTgz: join(src, 'bongos-core-1.15.0.tgz'), targetVersion: '1.15.0' });
-  assert.equal(rel, join('vendor', 'bongos-core-1.15.0.tgz'));
+  // POSIX outright, not join(): this return value is written into package.json as a
+  // `file:` specifier, so the separator is part of the contract, not of the platform
+  assert.equal(rel, 'vendor/bongos-core-1.15.0.tgz');
   assert.equal(readFileSync(join(dir, rel), 'utf8'), 'TGZBYTES');
   assert.ok(existsSync(join(dir, 'vendor', 'bongos-core-1.15.0.manifest.json')), 'manifest copied too');
 });
 
+// The pin is a POSIX specifier on EVERY platform (task 1003839). `bongos init
+// --vendor-core` and `bongos upgrade` both write `file:<vendorRel>` into an
+// instance's package.json, and that package.json is COMMITTED — so a scaffold cut
+// on a Windows laptop was shipping `file:vendor\\bongos-core-x.y.z.tgz` to a Linux
+// provisioner running `npm ci`, which reads the backslash as part of the filename.
+//
+// Two halves, because neither alone can see the bug from CI. The STATIC half reads
+// the sources and so fails on any platform; the BEHAVIOURAL half below it is silent on
+// Linux (path.join already yields a forward slash there) and loud on Windows. The
+// static half runs FIRST for exactly that reason: on Windows a regression trips the
+// behavioural assertions and would abort the case before the platform-independent
+// ones ever ran, hiding whether CI could have caught it.
+t('the vendored core pin is POSIX on every platform, and no call site rebuilds it', () => {
+  // one place decides the separator, and that place spells it posix
+  const upgradeSrc = readFileSync(new URL('../scripts/gds/upgrade.js', import.meta.url), 'utf8');
+  assert.match(upgradeSrc, /function vendorRelFor\([^)]*\)\s*{\s*return path\.posix\.join\(/,
+    'vendorRelFor must build the pin with path.posix.join — it is an npm specifier, not a filesystem path');
+  for (const rel of ['scripts/gds/upgrade.js', 'scripts/gds/init.js']) {
+    const code = readFileSync(new URL('../' + rel, import.meta.url), 'utf8');
+    assert.doesNotMatch(code, /path\.join\(\s*['"]vendor['"]\s*,/,
+      `${rel} must build the pin with vendorRelFor(), not path.join('vendor', …)`);
+  }
+
+  // and the string it produces, end to end
+  assert.equal(u.vendorRelFor('1.17.0'), 'vendor/bongos-core-1.17.0.tgz');
+  assert.doesNotMatch(u.vendorRelFor('1.17.0'), /\\/, 'a package.json file: specifier carries no backslash');
+  // still a usable path: join() normalises a forward-slash relative on Windows too,
+  // so POSIX costs the fs side nothing
+  const dir = scratchConsumer();
+  mkdirSync(join(dir, 'vendor'), { recursive: true });
+  writeFileSync(join(dir, u.vendorRelFor('1.17.0')), 'TGZ');
+  assert.ok(existsSync(join(dir, u.vendorRelFor('1.17.0'))), 'the POSIX rel still resolves on disk');
+  // and the pin that reaches package.json is that string, verbatim
+  u.writePin(dir, u.vendorRelFor('1.17.0'));
+  assert.equal(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).dependencies[u.CORE_PKG],
+    'file:vendor/bongos-core-1.17.0.tgz');
+});
+
 // ---- 3. step shims issue the right argv ------------------------------------
 t('npmInstall / runMigrate / restartService: correct commands', () => {
   const calls = [];