@bongos/core 1.19.682 → 1.19.684

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.682",
-  "core_contract": "1.19.682",
-  "source_commit": "b499e76b5b34ee8e7e753b7b89a3f6e1e8874224",
+  "core_version": "1.19.684",
+  "core_contract": "1.19.684",
+  "source_commit": "3cf0cdf9f887f9b33631e0bcfb3b7290cd935b06",
   "source_ref": "HEAD",
-  "built_at": "2026-09-12T16:22:24.694Z",
+  "built_at": "2026-09-12T20:55:49.945Z",
   "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": "a8aca2d995556a722b4debefe87ae388610d584d4954da4285b7dbf0a642eef4",
+  "file_count": 2626,
+  "tree_sha256": "dc96d8a5eb830704ee772fe1cee19ce1c4ec39575c4fafbbfe46012f5a2cd4b9",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.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": "1f62636e946a5b5bbf9b546d2e532b704db15ca21c3a9d0e71f5a8b17cde150b"
+      "sha256": "d441eb881efdcff2c6afedfa6d93799fdd64ac323422f12b54bf2c94df2b8d4a"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7777,12 +7782,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "db81ab75a6e749de67b91e13f3605d79a58a90b2e57c83332f535d48273dabcb"
+      "sha256": "130314108dd59672172778afcb5eedb0b8d605a983329a0d0a878ce9c59fa9c9"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "f4d50516d2a3a9ee031a89735502c1c8ec01789eeb4dfa3fd20da07713679279"
+      "sha256": "d5281482b1e0da7cd0cab8f475fc71345776694e8b457b2f96d241a315902ee4"
     },
     {
       "path": "public-docs/index.html",
@@ -8282,7 +8287,7 @@
     {
       "path": "scripts/gds/gen-api-client.js",
       "mode": "0000644",
-      "sha256": "2d8b35709e19b339bc55c57237f2add36fa6bdeb83a9b036faa902b0c4b8e3f9"
+      "sha256": "a023a19001d63b671409efe1afeae400dae96ea50debd6e3a49a7d10dffb55b0"
     },
     {
       "path": "scripts/gds/gen-api-docs.js",
@@ -9542,7 +9547,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "9f875091ba63a70601a61a1d486f5b561026167aa524bd371e457c9a93c2635c"
+      "sha256": "927d43875de79a0923fc0997262fd7a0106c6f56626a89ed5ede0c6c74945eec"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9662,7 +9667,7 @@
     {
       "path": "tests/api_client.mjs",
       "mode": "0000644",
-      "sha256": "fa360a42fa5d11b225afe1b13622f2a27fe43f2b7d0a47c2fef158bc8a11ecb6"
+      "sha256": "c1563c043f34e84aa6c0eec722244b24c51dc1254750fe1a27d3664c327bacd1"
     },
     {
       "path": "tests/api_docs.mjs",
@@ -12984,6 +12989,11 @@
       "mode": "0000644",
       "sha256": "9debf9ecdb02b986c882f3d29bdf4b5fe2154cb4e7639db0fd0a0336cd4bdc3b"
     },
+    {
+      "path": "tests/update_subscription_engine.mjs",
+      "mode": "0000644",
+      "sha256": "a2ba2dca70c6192313c7a64e6dcbb5d7f9dbf2dc457592e643f1d59154b2665f"
+    },
     {
       "path": "tests/upgrade.mjs",
       "mode": "0000644",

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

@@ -1823,5 +1823,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         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)
+  1.19.684 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.683 with no explicit bump. run 34718471740. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

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

@@ -21,6 +21,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { resolveDocsRoot } = require('../../src/instance-config');
+const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
 
 // The client is generated FROM the spec and lives beside it as a per-instance
 // artifact: both resolve to the DOCS root — the instance repo when a consumer
@@ -516,7 +517,15 @@ function main() {
   for (const [name, content] of Object.entries(files)) {
     const dest = path.join(OUT_DIR, name);
     const existing = fs.existsSync(dest) ? fs.readFileSync(dest, 'utf8') : null;
-    if (existing !== content) {
+    // Freshness is a question about CONTENT, so compare content (task 1003844 — the
+    // same defect as 1003619). We render with join('\n') = LF, but a core.autocrlf
+    // checkout hands readFileSync back CRLF, so a byte-wise `!==` called the already
+    // -correct client STALE on every Windows clone, forever: regenerating writes LF,
+    // git restores CRLF, gate red again. Comparing via sameContent cures it for every
+    // file here at once, so a seventh generated file can't reintroduce it by missing
+    // an eol pin. A missing file reads as null, which never matches a non-empty
+    // render — still stale, as before.
+    if (!sameContent(existing, content)) {
       stale = true;
       if (!check) { fs.mkdirSync(OUT_DIR, { recursive: true }); fs.writeFileSync(dest, content); }
     }

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

@@ -11,12 +11,15 @@ import { strict as assert } from 'node:assert';
 import { test } from 'node:test';
 import { createRequire } from 'node:module';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { createClient, ApiError, API_VERSION, DEFAULT_BASE_URL } from '../clients/bongos-client/index.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { sameContent } = require(path.join(ROOT, 'scripts', 'gds', 'gen-freshness.js'));
 
 function fakeFetch(recorder, response = { ok: true, status: 200, body: { ok: true } }) {
   return async (url, init) => {
@@ -149,12 +152,21 @@ test('baseUrl:"" is honored (absolute-path passthrough for the hall fetch wrappe
   assert.deepEqual(res, { status: 200, ok: true, data: { x: 1 } });
 });
 
+// The CI-gate twin of `gen-api-client.js --check`, and it carried the SAME defect
+// (task 1003844): a byte-wise assert.equal against a CRLF working copy failed on
+// every Windows checkout, forever — index.d.ts and README.md have no eol pin, so
+// core.autocrlf hands them back CRLF while the generator renders LF. Compare with
+// sameContent for the same reason gen-freshness.js exists; a real content change
+// still fails, which tests/gen_freshness.mjs pins.
 test('committed client is fresh (regenerate with gen-api-client.js if this fails)', () => {
   const gen = require('../scripts/gds/gen-api-client.js');
   const { files } = gen.build();
   for (const [name, content] of Object.entries(files)) {
     const onDisk = fs.readFileSync(path.join(ROOT, 'clients/bongos-client', name), 'utf8');
-    assert.equal(onDisk, content, `clients/bongos-client/${name} is STALE — run node scripts/gds/gen-api-client.js`);
+    assert.ok(
+      sameContent(onDisk, content),
+      `clients/bongos-client/${name} is STALE — run node scripts/gds/gen-api-client.js`,
+    );
   }
 });
 
@@ -245,3 +257,49 @@ test('browser-global build exposes window.BongosClient and shapes requests ident
   assert.equal(rec.init.headers.Authorization, 'Bearer tok');
   assert.equal(rec.init.body, JSON.stringify({ a: 1 }));
 });
+
+// --- the --check gate itself (task 1003844) ---------------------------------
+//
+// The assertions above compare the client this checkout HAS, so they can only ever
+// see the eol convention this checkout happens to use. The bug lived in the other
+// direction: a Windows clone whose committed client is already correct was told it
+// was STALE, forever. So drive the real CLI against a throwaway docs root where we
+// control the line endings, and pin BOTH halves — the eol-only case must pass, and
+// a genuine edit must still fail, which is what stops an over-broad "fix" (the same
+// pairing tests/gen_freshness.mjs makes for the helper).
+function runGen(root, args = []) {
+  return spawnSync(process.execPath, [path.join(ROOT, 'scripts/gds/gen-api-client.js'), ...args], {
+    encoding: 'utf8',
+    env: { ...process.env, BONGOS_INSTANCE_ROOT: root },
+  });
+}
+
+test('--check reads a CRLF working copy as fresh, and a real edit as stale (task 1003844)', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gen-api-client-'));
+  try {
+    fs.mkdirSync(path.join(root, 'docs', 'api'), { recursive: true });
+    fs.copyFileSync(path.join(ROOT, 'docs/api/openapi.json'), path.join(root, 'docs/api/openapi.json'));
+
+    const wrote = runGen(root);
+    assert.equal(wrote.status, 0, `generator failed: ${wrote.stderr}`);
+
+    // What a core.autocrlf=true checkout hands back for the two files with no eol
+    // pin. Nothing about the CONTENT changed, so --check must stay quiet.
+    for (const name of ['index.d.ts', 'README.md']) {
+      const f = path.join(root, 'clients/bongos-client', name);
+      fs.writeFileSync(f, fs.readFileSync(f, 'utf8').replace(/\n/g, '\r\n'));
+    }
+    const fresh = runGen(root, ['--check']);
+    assert.equal(fresh.status, 0, `CRLF must not read as STALE — this is the bug: ${fresh.stderr}`);
+    assert.match(fresh.stdout, /is fresh/);
+
+    // ...and the gate is still a gate.
+    const target = path.join(root, 'clients/bongos-client/index.mjs');
+    fs.writeFileSync(target, `${fs.readFileSync(target, 'utf8')}\nexport const SMUGGLED = 1;\n`);
+    const stale = runGen(root, ['--check']);
+    assert.equal(stale.status, 2, 'a real content change must still exit 2');
+    assert.match(stale.stderr, /STALE/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

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');
+});