@bongos/core 1.17.0

package/docs/recipes/ship-and-regrade.md

@@ -0,0 +1,72 @@
+# Recipe: shipping, the grade gate, and re-grading a stuck task
+
+> When a `/builder-ship` fails the subagent quality grader, the task lands at
+> `completed` and the claim is gone. This recipe is how you recover — **fix the
+> findings and re-grade**, which is the cheap default. Reaching for the Archon
+> `/confirm` override is the last resort (see the memory rule
+> `feedback_prefer_regrade_over_override`).
+
+## The ship lifecycle (where the grade gate sits)
+
+`/builder-ship` runs three transitions ([Phase 5](../session-logs/<redacted>.md)):
+
+1. **`completed`** — the claim resolves once local verification (smoke) passes. **The claim is consumed here.**
+2. **`confirmed`** — the v2 subagent quality grader (the 4-worker panel: Narc · Quality · Hacker · Efficiency Monger) passes. **Credits land here.**
+3. **`shipped`** — branch auto-merged to `main` + deployed; the Discord `#ship-news` broadcast fires.
+
+The grader reads **committed history** (`merge-base origin/main HEAD`…`HEAD`), independent of touches[] — so the diff it judges is whatever you've committed on the branch, not your working tree.
+
+## The regrade-gap (why this recipe exists)
+
+If the grade at step 2 **fails**, the task stays at `completed` but the claim is already gone (resolved at step 1). Historically there was no clean way back in — this was the **task-595-regrade-gap**, re-hit on [#600](https://example.com/builders#/task/600) and [#671](https://example.com/builders#/task/671)/[#673](https://example.com/builders#/task/673):
+
+- `node scripts/gds/claim.js <id>` → refuses, "not ready (current status: completed)".
+- `PATCH /tasks/:id {status:ready}` → refuses, `status_not_patchable`.
+- `POST /tasks/:id/promote` → refuses, `cannot_promote` (only works from backlog).
+- Re-running `ship.js` → "You don't have an active claim".
+
+The only escapes were the Archon `/confirm` override (which *bypasses* the grader — wrong, per `feedback_prefer_regrade_over_override`) or hand-building a grader harness.
+
+## The fix: `--regrade` ([#678](https://example.com/builders#/task/678))
+
+```bash
+node scripts/gds/ship.js <task-id> --regrade
+```
+
+This re-runs **ONLY the grade step** against the committed diff, with **no claim required**:
+
+1. **Eligibility** — the task must be at `completed`, and you must either have *last held the claim* or be an **Archon**. (The ownership data comes from the `last_claim` field on `GET /api/gds/tasks/:id`; the gate is `evaluateRegradeEligibility` in `ship.js`.)
+2. **Preflight** — your work must be committed (the grader reads committed history, not your working tree) and your local ship/grade tooling must be current with `main` (a stale `grader.js`/`ship.js` silently fails the same way — the [#662](https://example.com/builders#/task/662) lesson). `--force` overrides the freshness checks.
+3. **Empty-diff guard** — the grader reads committed history, so an empty committed diff aborts cleanly.
+4. **Grade** — runs the subagent grader and POSTs to the rank-open `/tasks/:id/grade` endpoint. `applyGrade` promotes `completed → confirmed` and awards credits on pass (idempotent — re-grading after the credit already landed is a no-op).
+5. **On pass** — the normal `confirmed → shipped` auto-merge + deploy + memory/session sync tail runs, exactly as a first-try pass would have. (A grade-failed ship never reached merge, so a passing re-grade is the *first* time the task actually ships and broadcasts.)
+
+Flags: `--summary "…"` (defaults to the task's stored value_summary), `--no-merge` (stop at confirmed; land later with `/merge-mode`), `--force` (override preflight freshness).
+
+### Typical recovery loop
+
+```bash
+node scripts/gds/ship.js 600            # grade FAILS → task at completed, claim gone
+# … read the issues, fix them, commit on the same branch …
+node scripts/gds/ship.js 600 --regrade  # re-grades the committed diff; on pass → confirmed → shipped
+```
+
+## Why `/grade` is rank-open (and the ownership check is a UX guard)
+
+`POST /tasks/:id/grade` is `requireBuilder` (any rank) by design — the *subagent grade* is the trust authority, not builder identity. `--regrade`'s "owner or Archon" check is therefore a client-side UX guardrail (don't accidentally re-grade someone else's task), not a security boundary. The real protection against a dishonest grade is the same as on the normal ship path: the builder runs the grader honestly against their committed diff.
+
+## Last resort: the Archon override
+
+Only if the grade was genuinely *wrong* (not "I don't want to fix it"):
+
+```bash
+curl -X POST -H "Authorization: Bearer <token>" https://example.com/api/gds/tasks/<id>/confirm
+```
+
+This writes a `task_grades` row with `grader_kind='lars'` so the audit trail shows it was a manual override. Prefer `--regrade`.
+
+## Related
+
+- Learning `#43` — "Recover a task stuck at 'completed': re-grade standalone, then /merge-mode" (the manual procedure this recipe automates).
+- [`/merge-mode`](../../.claude/skills/merge-mode/SKILL.md) — lands `confirmed → shipped` when auto-merge bailed.
+- [ADR 0024](../adr/<redacted>.md) — the MAS grader panel.

package/docs/recipes/staging-data.md

@@ -0,0 +1,50 @@
+# Staging data — what's real, what's faked
+
+> **Seeded by** [`scripts/gds/seed-staging.sh`](../../scripts/gds/seed-staging.sh) (V3.R41 / [#262](https://example.com/builders#/task/262)).
+> Staging DB: `example_staging` on the droplet. Staging is the controlled mirror used for red-team ([#272](https://example.com/builders#/task/272) parallel-load, future C9 work) — **never** a place to trust as a record of truth.
+
+## How seeding works
+
+`seed-staging.sh` runs **on the droplet** (both databases are local, peer auth as `lars`). It takes a **full `pg_dump` of production (schema + data)**, drops and recreates the staging `public` schema, restores the dump, then anonymizes.
+
+Why a full dump (not data-only): prod has a circular / self-referential FK (`tasks.parent_task_id`). A full dump adds all FK constraints **after** loading the rows, so that restores cleanly — and staging inherits prod's **exact schema**, so **no separate `migrate.sh` step is needed**. (A fresh `migrate.sh` from an empty DB would also fail: migration 021 is a *data* migration that assumes prod state.)
+
+```bash
+# On the droplet:
+bash scripts/gds/seed-staging.sh
+
+# Or from a laptop in one shot:
+ssh lars@<droplet> 'bash -s' < scripts/gds/seed-staging.sh
+```
+
+Re-runnable any time; each run replaces staging's data wholesale.
+
+## What's REAL (copied verbatim from prod)
+
+The structure and content of the work-tracking graph, so staging behaves like the real system:
+
+- **tasks, claims, versions, dependencies, done_when_criteria, task_criteria** — real titles, descriptions, statuses, ranks, links.
+- **cost_log, credit_log, learnings, idea_inbox, grades, achievements** — real rows.
+- **builder_memory** — real per-builder memory content (builder-authored project notes; internal, not personal data).
+
+These are *project* data (what the team built), not end-user data. Staging lives on the same access-controlled droplet as prod.
+
+## What's FAKED / removed (the anonymization step)
+
+- **Builder identity is anonymized.** Every `builders` row gets `github_login = builder-<id>`, `display_name = Builder <id>`, `github_id = 900000<id>`, `avatar_url = NULL`. No real GitHub handle survives on staging.
+- **All sessions are purged.** After the restore, the script nulls every column that references `builder_sessions` and then `DELETE`s every session row, so the seeded DB ends with **zero** sessions and **no real bearer token**. Mint a staging-only token directly (insert a row into `example_staging.builder_sessions`) when a test needs to authenticate — note the auth regex only accepts `[A-Za-z0-9]+`, so the token must be alphanumeric (no hyphens).
+
+### Honest note on the restore window (not a zero-trust guarantee)
+
+Because it's a *full* dump, real session rows **are** loaded during the restore and only deleted a moment later in the anonymize step — so for the brief restore→purge window (~1s) real bearer tokens transiently exist in the staging DB, and the temporary dump file under `/tmp` (mode `0600`, shredded on normal exit) holds real `github_login` values until cleanup. This is acceptable because staging is the **same trust domain** as prod (one access-controlled droplet, peer auth) — but it is **not** a "real tokens never touch staging" guarantee. If you need that guarantee (e.g. seeding onto a less-trusted host), revoke prod sessions first or seed during a maintenance window. The end state after a successful run is always zero sessions.
+
+## Reseeding cadence
+
+Re-run on demand (before a red-team / load-test session) or on a weekly cron. To install the weekly cron on the droplet:
+
+```bash
+# 03:30 every Monday — refresh staging from prod.
+( crontab -l 2>/dev/null; echo "30 3 * * 1 bash /home/lars/example-staging/scripts/gds/seed-staging.sh >> /home/lars/seed-staging.log 2>&1" ) | crontab -
+```
+
+(On-demand is the common case; the cron is optional convenience. The staging checkout must be on current `main` so it has the latest schema — `git pull` it before a manual seed if prod's schema has moved. Until the cron is installed, treat staging data as a point-in-time snapshot from the last manual seed.)

package/docs/recipes/staging-environment.md

@@ -0,0 +1,215 @@
+---
+track: internal
+scope: shared-infra (droplet, Caddy, Postgres, Cloudflare DNS + cert)
+---
+
+# Staging environment — provision and operate
+
+> ⚠️ **Currently FROZEN as of 2026-05-29.** Staging was provisioned + verified end-to-end (see `https://staging.example.com` history in audit_log) and then immediately frozen pending real use. The systemd unit is **stopped + disabled** — incoming requests get a 502 from Caddy because the Node process isn't listening. All other scaffolding (DB, .env with OAuth creds, Caddy block, DNS record, cert SAN, separate GitHub OAuth app) is intact.
+>
+> **Revive with two commands**:
+> ```bash
+> ssh lars@REDACTED_IP "sudo systemctl enable example-staging && \
+>                            sudo systemctl start example-staging"
+> # Then verify:
+> curl -sS https://staging.example.com/healthz   # → "ok"
+> ```
+> No re-provisioning needed unless you've rebuilt the droplet or wiped `/home/lars/example-staging`. The full first-time setup (DNS, cert, OAuth app, env file) is below for reference + for the next staging spin-up.
+>
+> **Why frozen instead of torn down?** Provisioning costs an hour the first time (DNS propagation, OAuth app, cert SAN check, debugging migration data gaps). A frozen environment is `~30MB RAM idle on the droplet` for free, vs. paying the setup cost again later. See the decision discussion at end-of-session 2026-05-29 — defer-not-delete was the call.
+
+> The staging environment lives at `https://staging.example.com`. It runs on the SAME droplet as prod but as a separate Node process on port 3001, against a separate Postgres database (`example_staging`), with separate GitHub OAuth credentials, and pointing at a separate Discord channel for broadcasts.
+
+V3.R39 ([#260](https://example.com/builders#/task/260)) shipped the scaffolding; this recipe is how to bring it live for the first time and how to operate it once it's up. Follow-up tasks V3.R40 ([#261](https://example.com/builders#/task/261)) and V3.R41 ([#262](https://example.com/builders#/task/262)) will land deploy automation and data seeding on top.
+
+## First-time provisioning (Lars — one-time)
+
+Four pre-conditions Lars must satisfy before the provisioning script can run end-to-end. Each is a manual step in a Cloudflare or GitHub UI; none can be automated from a laptop.
+
+### 1. DNS A record
+
+In Cloudflare → DNS → Records, add:
+
+| Type | Name | Content | Proxy | TTL |
+|---|---|---|---|---|
+| A | `staging` | `REDACTED_IP` | ☑ Proxied (orange cloud) | Auto |
+
+Verify from a laptop:
+
+```bash
+dig +short staging.example.com
+# Should return a Cloudflare-edge IP (proxied), not REDACTED_IP directly.
+```
+
+### 2. Origin Cert SAN
+
+Caddy is using `/etc/caddy/origin.crt` issued by Cloudflare's Origin CA. Confirm the cert covers `*.example.com`:
+
+```bash
+ssh lars@REDACTED_IP \
+  "openssl x509 -in /etc/caddy/origin.crt -noout -text" \
+  | awk '/Subject Alternative Name/{getline; print}'
+```
+
+If `*.example.com` is **not** in the output:
+
+1. Cloudflare → SSL/TLS → Origin Server → Create Certificate.
+2. Hostnames: `example.com, *.example.com` (cover apex + all subdomains).
+3. Validity: 15 years (Cloudflare's max).
+4. Save the certificate + private key.
+5. On the droplet: replace `/etc/caddy/origin.crt` + `/etc/caddy/origin.key` (chmod 600 on the key).
+6. `sudo systemctl reload caddy`.
+
+### 3. Separate GitHub OAuth app
+
+The prod OAuth app points its callback at `example.com/api/gds/auth/web/callback`. Staging needs its own:
+
+1. github.com → Settings → Developer settings → OAuth Apps → New OAuth App.
+2. Application name: `Off the Boats — staging`.
+3. Homepage URL: `https://staging.example.com`.
+4. Authorization callback URL: `https://staging.example.com/api/gds/auth/web/callback`.
+5. Note the **Client ID** and **Client Secret** — they go into `/home/lars/example-staging/.env` (see step 4 of the provisioning script).
+
+### 4. Separate Discord channel + webhook
+
+Staging ships should NOT announce to the real team channel. Either:
+
+- (recommended) Create a parallel Discord channel "Example Staging Builds." Add an incoming webhook on it + paste the URL into `.env` as `DISCORD_SHIP_NEWS_WEBHOOK` (see `scripts/discord/README.md`).
+- (acceptable) Leave `DISCORD_SHIP_NEWS_WEBHOOK` blank in staging `.env` — the build broadcast will skip silently.
+
+## Running the provisioning script
+
+```bash
+# scp the script to the droplet (or run it inline over ssh)
+scp scripts/deploy/provision-staging.sh lars@REDACTED_IP:/tmp/
+ssh lars@REDACTED_IP "bash /tmp/provision-staging.sh"
+
+# OR — inline:
+ssh lars@REDACTED_IP "bash -s" < scripts/deploy/provision-staging.sh
+```
+
+The script is **idempotent** — re-running it is the recovery path on partial failure. It walks 8 steps:
+
+1. Verify DNS + cert SAN.
+2. Create the staging Postgres DB if missing.
+3. Clone the repo to `/home/lars/example-staging` (or git-pull if it already exists).
+4. Drop a `.env` **template** with the staging-specific fields; **exit early** if the OAuth secrets are still blank, so Lars can fill them in and re-run.
+5. Install + enable + start the systemd unit `example-staging.service`.
+6. Apply pending migrations against the staging DB.
+7. Verify localhost:3001/healthz.
+8. Verify https://staging.example.com/healthz.
+
+If any step fails, the script bails with a clear diagnostic. Fix the underlying issue, re-run.
+
+## Day-to-day operation
+
+### Restarting
+
+```bash
+ssh lars@REDACTED_IP "sudo systemctl restart example-staging"
+```
+
+The systemd unit will revive automatically on droplet reboot (it's `WantedBy=multi-user.target`).
+
+### Logs
+
+```bash
+ssh lars@REDACTED_IP "sudo journalctl -u example-staging -f"
+```
+
+### Deploying to staging
+
+**Automated (V3.R40 / [#261](https://example.com/builders#/task/261)) — the normal path.** Push to the `staging` branch and GitHub Actions deploys it:
+
+```bash
+# From any checkout — ship a feature branch (or main) to staging:
+git push origin <your-branch>:staging --force
+```
+
+`.github/workflows/deploy-staging.yml` fires on the push: it scp's the latest `scripts/deploy/deploy-staging.sh` to `~/deploy-staging.sh` on the droplet, then runs it (reset to `origin/staging` → conditional `npm ci` → migrate `example_staging` → restart the service → smoke). A green run means `https://staging.example.com` reflects the push within ~2 minutes. Force-push is expected — `staging` is a disposable pointer at whatever release candidate you want to test, and the deploy script does a `git reset --hard origin/staging` to match.
+
+> **One-time setup required before auto-deploy works — BOTH secrets (no insecure fallback):**
+> 1. `STAGING_SSH_KEY` — a dedicated deploy keypair whose public half is in the droplet's `~/.ssh/authorized_keys`.
+> 2. `DROPLET_KNOWN_HOSTS` — the droplet's SSH host key in `known_hosts` format, captured once from a trusted machine with `ssh-keyscan -t ed25519 REDACTED_IP`. The workflow connects with `StrictHostKeyChecking=yes` against this pin, so a MITM can't substitute its own host key. Pinning is **mandatory** — there is deliberately no trust-on-first-use fallback.
+>
+> Until **both** are set the workflow **skips cleanly** (no red X) and you fall back to the manual path below. Tracked in `blockers/`.
+
+**Manual fallback** (no secret set yet, or deploying by hand):
+
+```bash
+# Push the ref you want, then run the deploy script on the droplet:
+git push origin <your-branch>:staging --force
+ssh lars@REDACTED_IP "bash ~/deploy-staging.sh"
+
+# Or, if ~/deploy-staging.sh isn't installed yet, install it first:
+scp scripts/deploy/deploy-staging.sh lars@REDACTED_IP:~/deploy-staging.sh
+ssh lars@REDACTED_IP "chmod +x ~/deploy-staging.sh && bash ~/deploy-staging.sh"
+```
+
+`~/deploy-staging.sh` always operates on the `staging` branch and the `example_staging` DB — never `main`, never the prod DB.
+
+### Wiping staging data
+
+Safe — staging is a sandbox.
+
+```bash
+ssh lars@REDACTED_IP \
+  "sudo -u postgres dropdb example_staging && \
+   sudo -u postgres createdb -O lars example_staging && \
+   cd /home/lars/example-staging && \
+   PGDATABASE=example_staging bash scripts/migrate.sh && \
+   sudo systemctl restart example-staging"
+```
+
+### Rotating staging secrets
+
+Same model as prod (see [ADR 0022](../adr/0022-secrets-policy.md)) but the rotation only touches the staging GitHub OAuth app + the staging webhook. Production credentials are unaffected.
+
+## What's intentionally NOT separated
+
+These resources are shared between prod and staging by design — separating them would multiply cost without buying meaningful isolation for a $5K-budget project:
+
+- **The droplet itself** — `REDACTED_IP`. Both processes co-exist on this one host. If we ever hit memory pressure or noisy-neighbor effects, splitting is a future architecture decision.
+- **The Postgres server** — same `postgresql` daemon, separate databases. Postgres's per-database isolation is enough for the use case.
+- **Caddy** — same Caddy instance routes both via the Host header.
+- **The Cloudflare zone** — same `example.com` zone, different DNS records.
+- **The Origin Cert** — the wildcard `*.example.com` SAN covers both, so one cert is enough.
+
+The things that ARE separated (process, port, DB, OAuth app, env, chat webhook) are exactly the things that would cause a confused-with-prod incident if shared.
+
+## Smoke-test recipe (for /merge-mode or manual checks)
+
+```bash
+# Full staging smoke from a laptop
+HOST=https://staging.example.com
+for path in /healthz /api/gds/healthz /api/gds/public/versions; do
+  status=$(curl -o /dev/null -sS -w '%{http_code}' "${HOST}${path}")
+  printf "  %-40s %s\n" "${HOST}${path}" "${status}"
+done
+# Expect three 200s.
+```
+
+The same shape as `scripts/gds/smoke-gds.js` but pointed at staging. A future task could parameterize `smoke-gds.js` to accept a host arg — filed as a follow-up.
+
+## Freezing staging again (when you stop using it actively)
+
+The mirror of the revival commands at the top of this doc:
+
+```bash
+ssh lars@REDACTED_IP "sudo systemctl stop example-staging && \
+                           sudo systemctl disable example-staging"
+# Verify it stays down:
+curl -sS -o /dev/null -w '%{http_code}\n' https://staging.example.com/healthz   # → 502
+```
+
+The freeze preserves:
+
+- The systemd unit file at `/etc/systemd/system/example-staging.service`
+- The repo checkout at `/home/lars/example-staging`
+- The `.env` file at chmod 600 with the staging OAuth credentials
+- The `example_staging` Postgres database
+- The Caddy block, DNS record, Origin Cert SAN, separate GitHub OAuth app
+
+Idle resource cost on the droplet: ~0. The freeze is what you reach for instead of teardown when you might want staging back within months — re-provisioning the full chain (especially the DNS + cert + OAuth app dance) is more friction than leaving the scaffolding in place.
+
+If you want a HARD teardown (e.g. droplet is going away, project pivoting), the sequence is in [§"The 'tear it down' option" in CLAUDE.md handoff for this work](../session-logs/) — drop the DB, remove the unit file, remove the checkout, revert the Caddy block. The GitHub OAuth app + the Cloudflare DNS record are free to leave around even after teardown.

package/docs/recipes/upgrading-the-core.md

@@ -0,0 +1,58 @@
+# Recipe — upgrading a consumer instance's Cloud Bongos core (`bongos upgrade`)
+
+> The R86 update-consumption channel ([ADR 0100](../adr/<redacted>.md) §2, [ADR 0103](../adr/<redacted>.md) §4, task [#1690](https://example.com/builders#/task/1690)). How a **two-repo consumer instance** — one that installs `@cloudbongos/core` as a vendored-tarball dependency — pulls the core from version N → N+1. Tooling: [`scripts/gds/upgrade.js`](../../scripts/gds/upgrade.js) (`bongos upgrade`). First proven live on emersonian-circles 1.15.0 → 1.16.0 (task [#1976](https://example.com/builders#/task/1976)).
+
+## What the channel does
+
+`bongos upgrade --to <version> --from <tgz>` runs, from a consumer instance root:
+
+1. **pre-flight** — module-compat vs the target core + a clean git tree (skip with `--force`).
+2. **bump the pin** — vendor the new `cloudbongos-core-<version>.tgz` and rewrite the `"@cloudbongos/core": "file:vendor/…"` dependency.
+3. **`npm install`** — `node_modules/@cloudbongos/core` becomes the new version.
+4. **`npm run migrate`** — the core's `migrate.sh` applies additive `core_*` migrations (merged three-root: core + instance + modules).
+5. **materialize `.claude/`** — refresh skills/settings/hooks from the new core (`materializeClaude`), rewriting invocations to the `bongos` bin.
+6. **restart** — `--service <unit>` or `--restart-cmd "<cmd>"`.
+7. **verify** — installed version == target (+ optional `--health-url`).
+
+Run bare (`bongos upgrade`, no `--to`) it stays the module-compat **pre-check** only.
+
+## The bootstrap (first bump)
+
+The channel ships *in* the core. On the FIRST bump, the consumer's installed core is the OLD version (whose `bongos upgrade` may be the pre-check stub or lack a fix). So drive the first bump with the **new version's** `upgrade.js`, run out of its extracted package against `--instance <consumer>`:
+
+```bash
+cd /tmp && rm -rf pkg && mkdir pkg && tar xzf cloudbongos-core-<version>.tgz -C pkg
+node /tmp/pkg/package/scripts/gds/upgrade.js --to <version> --from /tmp/cloudbongos-core-<version>.tgz --instance <consumer-root> …
+```
+
+Once a consumer is on a core that carries the channel, its own `bongos upgrade` drives later bumps.
+
+## Live procedure (as run for emersonian-circles 1.15.0 → 1.16.0)
+
+The instance runs on the droplet (co-tenant): systemd `emersonian-circles.service`, `WorkingDirectory=/home/lars/emersonian-circles`, port `:3004`, DB `emersonian_circles`. The consumer repo also has a laptop clone (`~/dev/emersonian-circles`) + origin (`example-owner/emersonian-circles`).
+
+1. **Cut the canonical tarball from `main`** (after the core change has merged, so the pin is a real release):
+   ```bash
+   node scripts/gds/package-core.js --version <version>   # → dist/cloudbongos-core-<version>.tgz (+ manifest)
+   ```
+   `package-core` archives committed `HEAD`, **not the working tree** — commit + merge first, then verify the artifact (`ls dist/cloudbongos-core-<version>/…`).
+2. **Back up the instance DB** — `pg_dump emersonian_circles | gzip > /tmp/…sql.gz`.
+3. **`scp` the tarball to the droplet**, verify `sha256sum` matches.
+4. **`--dry-run` first**, then the real run — extracted-package bootstrap, with the instance DB pinned:
+   ```bash
+   PGDATABASE=emersonian_circles CLOUDBONGOS_INSTANCE_ROOT=/home/lars/emersonian-circles \
+     node /tmp/pkg/package/scripts/gds/upgrade.js --to <version> --from /tmp/cloudbongos-core-<version>.tgz \
+       --instance /home/lars/emersonian-circles \
+       --restart-cmd "sudo systemctl restart emersonian-circles.service" \
+       --health-url http://127.0.0.1:3004/healthz
+   ```
+5. **Verify** — `systemctl is-active`, local + public `/healthz` 200, `/version`, `installed core == <version>`, the `core_upgrades` row.
+6. **Update the repo of record** — run the channel on the laptop clone (`--skip-migrate`, no DB there), commit the pin bump (drop the superseded tarball), `git push origin`.
+7. **Align the droplet checkout** — the droplet has no deploy key (`git pull` fails; idea 509), so `git bundle` the new commit on the laptop, `scp`, `git fetch <bundle> && git reset --hard FETCH_HEAD`. `node_modules` is already the new version, so no re-`npm ci`; a final restart makes `/version` report the new commit.
+
+## Gotchas
+
+- **`PGDATABASE` is load-bearing on a co-tenant droplet.** `migrate.sh` defaults `PGDATABASE` to `example` — **production**. Always set `PGDATABASE=<instance-db>` explicitly, or you migrate the wrong database.
+- **The health check polls the restart** (fixed in task [#1984](https://example.com/builders#/task/1984)). The service binds its port ~1s after `systemctl restart`, so `--health-url` now polls up to ~30s for a 2xx before reporting a warning — an immediate `fetch failed` no longer means a failed upgrade. (Pre-1984 cores fetched once and spuriously reported `fetch failed`; there, confirm with `is-active` + a manual `curl`.)
+- **The ledger auto-inserts via `PGDATABASE` too** (fixed in task [#1984](https://example.com/builders#/task/1984)). A consumer on `PGDATABASE` + peer auth now gets its `core_upgrades` row written automatically — the channel delegates the insert to `psql -d "$PGDATABASE"`, exactly like `migrate.sh`, so no manual `psql INSERT` is needed. (`DATABASE_URL` still works, via the `pg` driver.) Pre-1984 cores only auto-wrote with `DATABASE_URL`; on those, record the row manually.
+- **No deploy key on the droplet** → deploys/upgrades ride a `git bundle`, not `git pull` (idea 509).