@bongos/core 1.19.204 → 1.19.206

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.204",
-  "core_contract": "1.19.204",
-  "source_commit": "1b831b99695f793cf8d6e7fdf248e20ea2486c77",
+  "core_version": "1.19.206",
+  "core_contract": "1.19.206",
+  "source_commit": "6ef49e744b96d37db9a338979fb85bb56fb6aa6f",
   "source_ref": "HEAD",
-  "built_at": "2026-08-17T19:29:56.265Z",
+  "built_at": "2026-08-17T20:15:14.217Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 310,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 1627,
-  "tree_sha256": "a44dd13817d43a88eb9a226b742a2c039888e0390bf5a5cb428c312e95db4aaf",
+  "tree_sha256": "f7017bc51e10af4dd65ab8df53ce22c7a0e611c7fb948ee6598ce8c4f7831a6a",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -187,7 +187,7 @@
     {
       "path": ".claude/skills/new-project/SKILL.md",
       "mode": "0000644",
-      "sha256": "55b86978a60e33eefe024d7c7d521e4093b82235eeb7e5d4a145fbb0e4db0b06"
+      "sha256": "9b36d441850c335fa634d892088e4c15a2a87acaa9e52808b74a8b2e6e9af39f"
     },
     {
       "path": ".claude/skills/otb-character-review/SKILL.md",
@@ -367,7 +367,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "b37e4a561554ec579b525ff660246d350a70c4acdda9a16d8e6521c38180bae6"
+      "sha256": "38ef88079d260b67161e680ea77fa6ddecb3cc74a1452796cbe28c0e3601c052"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -707,7 +707,7 @@
     {
       "path": "docs/adr/0055-server-mediated-branch-publish.md",
       "mode": "0000644",
-      "sha256": "6f51c67939eacaf510774894625d0a09e6883e4c8e1d8fdea2cf35f8d9f58ea4"
+      "sha256": "11ee013554922e0f9dadb582373c22d4aaa6433ddcb14af28386c4843a39497f"
     },
     {
       "path": "docs/adr/0056-prod-deploy-script-mirror-and-healthcheck-retry.md",
@@ -1137,7 +1137,7 @@
     {
       "path": "docs/adr/0133-github-app-manifest-onboarding-signin.md",
       "mode": "0000644",
-      "sha256": "94e1f79e0a32a53b51e5bbf6d10d37d477d676cad33b267dc3ddc0891ae70704"
+      "sha256": "dbd5b30d75631ba2754f4e7da0d43c03b1ed998b4082e8df23de0d7e7d5c5305"
     },
     {
       "path": "docs/adr/0134-private-first-npm-distribution.md",
@@ -1372,7 +1372,7 @@
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "7892d449572d19f058c6ac364d5b697e28d76bcd922d25d33b5203f5e1b5b7aa"
+      "sha256": "c11ec9dcb0726382e15bb7fc9e74086037ed158256ef16b5efcc81fe2db2d078"
     },
     {
       "path": "docs/architecture.md",
@@ -1672,7 +1672,7 @@
     {
       "path": "docs/recipes/ops-gotchas.md",
       "mode": "0000644",
-      "sha256": "52a209553565405dca461b1c4c0cef9fb0ec6d98b95ed420c82eaf1fa3eb15f6"
+      "sha256": "d9956abefe8496cbbb8bbc94361431d40823c3a9d1fa8f4145e8b48999b54672"
     },
     {
       "path": "docs/recipes/overnight-builder.md",
@@ -3567,7 +3567,7 @@
     {
       "path": "modules/lifecycle/github-push.js",
       "mode": "0000644",
-      "sha256": "aef4e5dca5cbea3c7c2041b877a98204f2cb21c3a9ce017cad57955d2212cf96"
+      "sha256": "127b6666bfbc4b85baebe85b0bf5501ad73b517faf4dafbc1a76a5535ac04ebc"
     },
     {
       "path": "modules/lifecycle/goal-advisory.js",
@@ -3622,7 +3622,7 @@
     {
       "path": "modules/lifecycle/publish-reconciler.js",
       "mode": "0000644",
-      "sha256": "6e41bbab9f8277a13178e4f9fcd278b47b8b34421114522ac113e57aedb631ac"
+      "sha256": "1cca02e8eff2b0a7fdc1fa06ad6be2f633e25a29bdd10dddf6147610fdae087a"
     },
     {
       "path": "modules/lifecycle/routes/analytics.js",
@@ -3662,7 +3662,7 @@
     {
       "path": "modules/lifecycle/routes/tasks.js",
       "mode": "0000644",
-      "sha256": "68b4f47e3a5016645893c60eca2fe11a242012abf6625c99d6a774356d82d1ce"
+      "sha256": "95193b64dcf1121f10fbc871a07cb7997a27a64d3f7b2176957abdae28979729"
     },
     {
       "path": "modules/lifecycle/routes/versions.js",
@@ -3957,7 +3957,7 @@
     {
       "path": "modules/provisioning/onboard-plan.js",
       "mode": "0000644",
-      "sha256": "e06957844e7161ef42e9971cc1a9b952d9ae87a781b2821d882085ca02c6eccf"
+      "sha256": "de7927d2a3c1aac0d40ec5b1ac6c2e98e87cb593c4d3d2bd6ddfe3696371bff6"
     },
     {
       "path": "modules/provisioning/pollers/liveness-sweep.js",
@@ -3967,7 +3967,7 @@
     {
       "path": "modules/provisioning/provisioning.js",
       "mode": "0000644",
-      "sha256": "eebcba4b333030f17c06bc6e1423450ae4af124e4075af52cbd512e80d5ba95e"
+      "sha256": "e43977d0c5458de4fde91e6ccb784b112187545fdf03ceed2c352b605686a57e"
     },
     {
       "path": "modules/provisioning/rate-limit.js",
@@ -3977,7 +3977,7 @@
     {
       "path": "modules/provisioning/routes/provisioning.js",
       "mode": "0000644",
-      "sha256": "17f6adb4edd7dee2ab339f5d302b61ecfbcf45db2ba4d0315eeeffbad87a9dce"
+      "sha256": "f7cf016e10587302437f5d8ab7b01d8b1be6694e05b9e8c47a6ccb2cdfda8ac4"
     },
     {
       "path": "modules/provisioning/tests/liveness.mjs",
@@ -3987,7 +3987,7 @@
     {
       "path": "modules/provisioning/tests/provisioning.mjs",
       "mode": "0000644",
-      "sha256": "98787fad5df787a8ebdbf90fb8bf21b68f1529387b15d65724fdafc8ac0b91d0"
+      "sha256": "4c7bb37582485445e947e233c9fbb9c20c9ab55da9dd159c8062fffa4472a5d7"
     },
     {
       "path": "modules/provisioning/ui/.gitkeep",
@@ -4277,12 +4277,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "45a21ec8d9e8ffae13d85a59beb598f381a10fb85746c42888f0b8c3be098e0f"
+      "sha256": "8cece7080d6a67c93467f86ee1c02cff85f8b2dbd5e8219519e9bc9df034f895"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "07c27a2b49959b9022ad8465bc02abe9fbce3bceb9068385a457d01c32423f0f"
+      "sha256": "05a1768a85ccd224b9caa4e388b83f5a1d933b8b46761ebe7ce6f5a06f3c6d6a"
     },
     {
       "path": "public-docs/index.html",
@@ -4542,7 +4542,7 @@
     {
       "path": "public-landing/projects.html",
       "mode": "0000644",
-      "sha256": "5edfc22fd5d85453df0d83a531fd085b3d5d079b66c7e3f58dcb9a0261c6b4a6"
+      "sha256": "494d1aa1a6ff006a8e8f239c29d90c052f735919937c9dc6fb6b8eeff4902e91"
     },
     {
       "path": "public-landing/world/assets/clouds/cloud-island-large.png",
@@ -5152,7 +5152,7 @@
     {
       "path": "scripts/gds/onboard.js",
       "mode": "0000644",
-      "sha256": "c6fb2c531c6d84dcb16daea50984e1b24021b6379cf992a01482951b119bf9e4"
+      "sha256": "71ee037f1e893a1bcbcaca95e6bdc80c5eb4f5d3e613b59b95e1272d673d3d12"
     },
     {
       "path": "scripts/gds/onboarding-analyze.js",
@@ -5197,7 +5197,7 @@
     {
       "path": "scripts/gds/provision.js",
       "mode": "0000644",
-      "sha256": "1c348e8859004c69e66b8eede56da0bab68ec4d473790f1c1f9bf1769934211f"
+      "sha256": "242f51c3e2ae991dc8a02d7285c829d3cd7b2a4022c516b218d259cac14b855f"
     },
     {
       "path": "scripts/gds/publish-credential-check.js",
@@ -5892,7 +5892,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "acfdae5a37ae7fa878a752cb566ec930dec8a7703cb86ef9d16609f6ec8c1bab"
+      "sha256": "84441072e12b08bf8c5dde09972dc91dd530b586f30f287016d830589476fb5d"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7377,7 +7377,7 @@
     {
       "path": "tests/onboard.mjs",
       "mode": "0000644",
-      "sha256": "72590fd2d6f99db3020cb5488ec4f31cef2ad15718a63d8b147ab5adefe347f7"
+      "sha256": "c6823a6f0f81bcb4f01ccbd2364d6dcf76eb21e3ff10972738f792438939dee0"
     },
     {
       "path": "tests/onboarding_gate.mjs",
@@ -7517,7 +7517,7 @@
     {
       "path": "tests/provision.mjs",
       "mode": "0000644",
-      "sha256": "9e8da984a2a9378809f03cc3f5f1c2cda34f8589ad954db1acd5b12bf424f322"
+      "sha256": "30b55efaa97e695603875ec057901d5333977d41705fc862fc831a424c4e2674"
     },
     {
       "path": "tests/provisioning_default_domain.mjs",
@@ -7572,7 +7572,7 @@
     {
       "path": "tests/publish_branch_route.mjs",
       "mode": "0000644",
-      "sha256": "db309db9b8fe350a64708d2a0c9dd1622ad0e5bfdef7c89775721ff3daa7042d"
+      "sha256": "485b2b965bcf44a515571de43851c42a32f278dcdd02510f0d3cd9f6ac53e61c"
     },
     {
       "path": "tests/publish_manifest.mjs",
@@ -7582,7 +7582,7 @@
     {
       "path": "tests/publish_reconciler.mjs",
       "mode": "0000644",
-      "sha256": "fed6533bd829adc0fc2126c48b28248c90bd32660650f2af91fee112e3f7369a"
+      "sha256": "1dfca44ba378b69041894371c1a3765eba40edbdec18570d7b67cc849bcb9e8a"
     },
     {
       "path": "tests/rank_gate.mjs",
@@ -8077,7 +8077,7 @@
     {
       "path": "tests/tool_scan_engine.mjs",
       "mode": "0000644",
-      "sha256": "c8ae5ea8c8a78d0d2a9a55d7d94b3fd4d40ad36e71510f7d804db5645cc86bec"
+      "sha256": "10a6a41cafcba32406be1aa79e0be1ace1cde2c4163bf0b1a0efd1e5e8f8c403"
     },
     {
       "path": "tests/touches_overlap.mjs",

package/.claude/skills/new-project/SKILL.md

@@ -9,7 +9,7 @@ You are guiding a new owner from **zero to a live, owned Cloud Bongos instance**
 
 A new instance is **standalone** (ADR 0108): it runs from its **own git repo** with `@cloudbongos/core` installed as a **pinned npm dependency**, not a fork of this monorepo. Central updates are a `bongos upgrade` version-pin bump, not a merge. Every step below assumes this shape (`hosting_shape=standalone`).
 
-Four steps are **irreducibly human** and must be rendered as **precise, UI-first, copy-paste-safe prompts** (a non-technical owner does them with browser clicks, no terminal guessing): (1) create the GitHub repo, (2) approve the pre-filled **GitHub App** for sign-in (ONE click — the App Manifest flow, task 2080; no secret to paste), (3) own a domain, (4) the first sign-in. Everything else is automated. Never ask the owner to do in a terminal what they can do with a click.
+Five steps are **irreducibly human** and must be rendered as **precise, UI-first, copy-paste-safe prompts** (a non-technical owner does them with browser clicks, no terminal guessing): (1) create the GitHub repo, (2) approve the pre-filled **GitHub App** for sign-in (ONE click — the App Manifest flow, task 2080; no secret to paste), (3) install that App on the repo (ONE click — the publish credential, task 1003049), (4) own a domain, (5) the first sign-in. Everything else is automated. Never ask the owner to do in a terminal what they can do with a click.
 
 ## The canonical sequence
 
@@ -85,6 +85,8 @@ node scripts/gds/oauth-secret.js place <slug> --client-id <id> --client-secret <
 
 > **Guidance the standup learned:** do **NOT** hand-edit `web.env` with a shell `read -s` — during the Emersonian standup that silently left a 26-char truncated secret that broke sign-in with no obvious cause. `oauth-secret` validates the length/format (catching that truncation), rewrites the env line via Node, restarts the service, then **probes `/healthz` for `auth_configured:true`** before it reports success. If it refuses, the creds are wrong — recheck them; do not proceed.
 
+**Human-only — install the GitHub App on the repo (task 1003049, ADR 0055).** The one-click App doubles as the instance's **publish credential**: the manifest requests Contents rw + PR rw + Actions read, the runner places `GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY` in `web.env`, and the server discovers the installation id on its own — but only an **installed** App can mint push tokens. One click: the wizard's **Install the app on your repo** button (`github.com/apps/<slug>/installations/new`), or GitHub → Settings → Developer settings → GitHub Apps → your app → **Install App** → the project repo. Skip it and every ship strands at `confirmed` behind a manual merge. (Manual OAuth-app path instead? Set a fine-grained `GITHUB_PUSH_TOKEN` in `web.env` — ADR 0055.)
+
 **Human-only — first sign-in.** The owner opens `https://<domain>` and signs in with GitHub **once**. This seats the **founding Archon** — config alone seats no one, so this step is inherent and cannot be automated.
 
 ### 7. Verify

package/clients/bongos-client/index.d.ts

@@ -72,7 +72,7 @@ export interface GetProfilesHandleResponse { account: unknown; cross_project: un
 export interface GetProjectsFeaturedResponse { projects: unknown }
 export interface GetProjectsResponse { projects: unknown }
 export interface GetProvisioningFleetResponse { instances: unknown }
-export interface GetProvisioningGithubAppStatusResponse { ok: boolean; status: unknown; ready: unknown; terminal: unknown; domain: unknown; instance_status: unknown }
+export interface GetProvisioningGithubAppStatusResponse { ok: boolean; status: unknown; ready: unknown; terminal: unknown; domain: unknown; instance_status: unknown; app_slug: unknown }
 export interface GetProvisioningHealthResponse { module: unknown; ok: boolean; coreVersion: unknown }
 export interface GetProvisioningInstancesIdResponse { instance: unknown; open_intent: unknown }
 export interface GetProvisioningInstancesResponse { instances: unknown }

package/docs/adr/0055-server-mediated-branch-publish.md

@@ -42,6 +42,8 @@ A **fine-grained GitHub PAT** scoped to the single repo: `Contents: read/write`
 >
 > Check it with `node scripts/gds/publish-credential-check.js` on the host — it lists the repo's workflows as a control call first, so `blind` and `readable_no_workflow` are distinguishable. Task 1002724 makes a blind probe non-fatal (the reconciler falls back to the git-history land proof), but a blind credential means the deploy gate is **not being enforced**, only bypassed.
 
+> **Update (2026-08-17, task 1003049 — fresh instances get the credential from the manifest App; installation id auto-discovered):** a wizard-born instance had NO publish credential at all — the ADR 0133 manifest requested zero permissions and the conversion's `pem` was discarded — so on every new project the auto-merge + reconciler were dead on arrival and each ship stranded at `confirmed` behind manual archon surgery (gap-list W7, proven live on Spike Harbor). Now: the manifest requests exactly this ADR's scopes (Contents rw + PR rw + Actions read), the control-plane runner places `GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY` into the instance's web.env alongside the OAuth creds, and `github-push.js` **discovers the installation id at runtime** (`GET /repos/{owner}/{repo}/installation` with the App JWT; the env var still wins when set) — so `GITHUB_APP_INSTALLATION_ID` is no longer required. The one human step is installing the App on the repo (the onboarding `app-install` step; the wizard renders the one-click `github.com/apps/<slug>/installations/new` link). <redacted> is a first-class loud state: routes answer a plain-sentence 503 naming the install URL, and the publish-reconciler warns once per streak instead of silently parking ships. **Security trade-off (accepted):** the App is public (the W6 sign-in fix), so third parties can install it on their own repos — those installs sit inside a leaked App key's blast radius even though this server only ever uses its own repo's installation. Mitigation: the reconciler's foreign-install watch (`github-push.foreignInstallations`) warns loudly whenever the App is installed anywhere beyond the repo owner. Pre-existing instances: see the ops-gotchas entry (grant the permissions + generate a key by hand, or use a PAT).
+
 ## Consequences
 
 - A dev-box builder ships end-to-end: `/builder-reauth` → claim → edit → `/builder-stage` ([ADR 0046](<redacted>.md)) → `/builder-ship`, with the GDS doing the push. The box holds no GitHub credential, so the [ADR 0053](0053-scoped-dev-box-session.md) blast-radius argument still holds.

package/docs/adr/0133-github-app-manifest-onboarding-signin.md

@@ -31,9 +31,9 @@ The conversion endpoint is unauthenticated (the code is the auth), so the web ti
 
 ### Manifest shape
 
-`redirect_url` = the **mothership** callback (the instance can't do the exchange). `callback_urls` = the **instance's** own `/api/gds/auth/web/callback` (what `auth.js` actually builds) **and** the `/api/bongos/...` alias, so sign-in works regardless of which prefix a build emits. `default_permissions: {}` (sign-in needs none), `hook_attributes.active:false`, `public:true`. Personal vs org differs only in the POST URL (derived from the repo owner); the App works for sign-in either way.
+`redirect_url` = the **mothership** callback (the instance can't do the exchange). `callback_urls` = the **instance's** own `/api/gds/auth/web/callback` (what `auth.js` actually builds) **and** the `/api/bongos/...` alias, so sign-in works regardless of which prefix a build emits. `default_permissions: { contents: 'write', pull_requests: 'write', actions: 'read' }` — sign-in itself needs none, but the App doubles as the instance's ADR 0055 **publish credential** (task 1003049): the conversion's `pem` + app id land in web.env, and once the owner installs the App on the repo the server mints installation tokens to land shipped work itself. `hook_attributes.active:false`, `public:true`. Personal vs org differs only in the POST URL (derived from the repo owner); the App works for sign-in either way.
 
-> **Amended 2026-08-17 (task 1003048, gap-list W6):** the manifest originally set `public:false`. That made every wizard-born project structurally single-builder on the web — GitHub answers a private App's authorize URL for any non-owner account with a bare 404, before the instance is ever involved (reproduced live on Spike Harbor). The App requests zero permissions, so public costs nothing; the manifest now sets `public:true`. Apps minted before the fix must be flipped by hand (GitHub App settings → Advanced → Make public) — see the ops-gotchas entry.
+> **Amended 2026-08-17 (task 1003048, gap-list W6):** the manifest originally set `public:false`. That made every wizard-born project structurally single-builder on the web — GitHub answers a private App's authorize URL for any non-owner account with a bare 404, before the instance is ever involved (reproduced live on Spike Harbor). The App requested zero permissions at the time, so public cost nothing; the manifest now sets `public:true`. (Task 1003049 later added the ADR 0055 repo scopes, which changes the calculus: a public App with write scopes **can** be installed by third parties on their own repos, and a leaked App private key's blast radius includes those installs — the server itself only ever uses its own repo's installation, but the credential could reach further if compromised. Accepted to keep this fix; mitigated by the publish-reconciler's **foreign-install watch**, which warns loudly whenever the App is installed anywhere beyond the repo owner.) Apps minted before the fix must be flipped by hand (GitHub App settings → Advanced → Make public) — see the ops-gotchas entry.
 
 **App name (tasks 2093 → 2095).** GitHub App names are globally unique across all of GitHub, so a bare project slug (e.g. `demo`) is almost always already taken. The auto name is the **instance domain** (e.g. `demo.cloudbongos.com`): a domain is inherently unique (so it never collides) and it reads perfectly on GitHub's sign-in consent screen, where the name is shown as *"`<name>` by `<owner>` … will redirect to `https://<domain>`"* — the name IS the destination. GitHub keeps the dots in the display name (only the internal slug is transformed) and caps it at 34 chars. **Fallback** (no domain, or a domain over 34 chars): brand-qualify the project — `<mothership brand> - <project>`, e.g. `Cloud Bongos - demo`, from the mothership's own `branding().identity.productName` (portable, not hardcoded) — still far less collision-prone than a bare slug. Either way it is only a default the owner can rename on GitHub's confirmation screen.
 

package/docs/api/openapi.json

@@ -13402,7 +13402,8 @@
           "ready": {},
           "terminal": {},
           "domain": {},
-          "instance_status": {}
+          "instance_status": {},
+          "app_slug": {}
         },
         "required": [
           "ok",
@@ -13410,7 +13411,8 @@
           "ready",
           "terminal",
           "domain",
-          "instance_status"
+          "instance_status",
+          "app_slug"
         ]
       },
       "GetProvisioningHealthResponse": {

package/docs/recipes/ops-gotchas.md

@@ -131,9 +131,16 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 
 - **Symptom:** On a wizard-created instance, any GitHub account other than the App's owner clicks "Sign in with GitHub" and gets a bare GitHub 404 — before the instance is ever involved. The project is effectively single-builder on the web. (Device Flow sign-in for the same non-owner works, which makes the failure look like anything but an App setting.)
 - **Root cause:** the ADR 0133 manifest flow used to mint the GitHub App with `public: false`, and GitHub 404s a private App's authorize URL for every non-owner. Fixed for newly minted Apps (`buildGithubAppManifest` now sets `public: true` — gap-list W6, task 1003048), but a manifest can't be re-applied to an existing App.
-- **Fix for pre-existing instances:** the App owner flips it by hand — github.com → Settings → Developer settings → GitHub Apps → (the instance's App) → **Advanced** → **Make public**. One click, no permission changes (the App requests none).
+- **Fix for pre-existing instances:** the App owner flips it by hand — github.com → Settings → Developer settings → GitHub Apps → (the instance's App) → **Advanced** → **Make public**. One click, no permission changes needed for sign-in.
 - **Live evidence:** reproduced twice against Spike Harbor (instance 18) with a fresh verified-email account, 2026-08-16 — see `docs/audits/project-creation-gap-list.md` W6.
 
+### Manifest-born GitHub Apps created before the task-1003049 fix are NOT a publish credential — every ship strands at `confirmed`
+
+- **Symptom:** on a fresh instance every `/builder-ship` parks at `confirmed`; `GET /tasks/:id/publish-status` answers 503 `push_unconfigured`; the archon has to merge PRs and `POST /tasks/:id/ship` by hand. Silent — work just piles up (gap-list W7, proven live on Spike Harbor task 1).
+- **Root cause:** the ADR 0133 manifest used to request **zero** repo permissions and the conversion's App private key (`pem`) was discarded, so no publish credential (ADR 0055) ever existed on a wizard-born instance. Fixed for newly minted Apps (task 1003049): the manifest now requests `contents: write` + `pull_requests: write` + `actions: read`, `placeManifestCreds` writes `GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY` into web.env, and the server discovers the installation id at runtime — the one human step left is **installing the App on the repo** (the onboarding `app-install` step).
+- **Fix for pre-existing instances:** in the App's GitHub settings — (1) **Permissions & events**: grant Contents read/write, Pull requests read/write, Actions read-only; (2) **General → Private keys**: generate a key; (3) put `GITHUB_APP_ID=<id>` and `GITHUB_APP_PRIVATE_KEY=<pem as one line with literal \n>` in `/etc/<slug>/web.env` and restart the unit; (4) **Install App** → pick the project repo (owners must re-approve the new permissions on an already-installed App). Alternative: a fine-grained `GITHUB_PUSH_TOKEN` PAT with the same three scopes (ADR 0055).
+- **How you know it worked:** `publish-status` stops 503ing, and the publish-reconciler log line `WARN … not installed` (if the App wasn't installed yet) goes quiet after the install.
+
 ---
 
 ## Mac / local dev

package/modules/lifecycle/github-push.js

@@ -20,10 +20,12 @@
 // THE SERVER CREDENTIAL (task 1028 / ADR 0055 hardening). Preferred: a GitHub
 // APP — the server holds ONLY the App private key and mints a SHORT-LIVED,
 // repo-scoped INSTALLATION token (1h) per push window, so there's no standing
-// push secret at rest. Set GITHUB_APP_ID + GITHUB_APP_INSTALLATION_ID +
-// GITHUB_APP_PRIVATE_KEY. Fallback (v1, kept for cutover): a standing fine-grained
-// PAT in GITHUB_PUSH_TOKEN. resolveToken() prefers the App, then the PAT; the App
-// JWT is RS256-signed with node:crypto (no jsonwebtoken / Octokit dependency).
+// push secret at rest. Set GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY (the
+// installation id is discovered from the repo at runtime; GITHUB_APP_INSTALLATION_ID
+// still wins when set — task 1003049). Fallback (v1, kept for cutover): a standing
+// fine-grained PAT in GITHUB_PUSH_TOKEN. resolveToken() prefers the App, then the
+// PAT; the App JWT is RS256-signed with node:crypto (no jsonwebtoken / Octokit
+// dependency).
 //
 // This module is the server seam: push a bundle, open/find the PR, enable auto-
 // merge, report status. All git runs through execFile arg-arrays (shell:false,
@@ -58,12 +60,12 @@ const SAFE_SHA_RE = /^[0-9a-f]{7,64}$/;
 
 // Configured if EITHER credential is present: a GitHub App (preferred) or the
 // v1 PAT fallback. The route 503s when neither is set (task 1028).
+// GITHUB_APP_INSTALLATION_ID is OPTIONAL (task 1003049): a fresh instance's
+// manifest-born App has no known installation id at cred-placement time, so the
+// server discovers it at runtime from GET /repos/{owner}/{repo}/installation —
+// the one human onboarding step left is installing the App on the repo.
 function appConfigured() {
-  return !!(
-    process.env.GITHUB_APP_ID &&
-    process.env.GITHUB_APP_INSTALLATION_ID &&
-    process.env.GITHUB_APP_PRIVATE_KEY
-  );
+  return !!(process.env.GITHUB_APP_ID && process.env.GITHUB_APP_PRIVATE_KEY);
 }
 
 function isConfigured() {
@@ -200,10 +202,76 @@ function mintAppJwt({ appId, privateKeyPem, nowSec }) {
 
 // Module-level cache of the current installation token, reused until ~60s before
 // expiry. Installation tokens are short-lived by construction (1h) and repo-
-// scoped to the single repo this server serves.
+// scoped to the single repo this server serves. The discovered installation id
+// is cached separately — it only changes if the App is uninstalled/reinstalled,
+// and a stale id fails the token exchange loudly (APP_TOKEN_FAILED), never silently.
 let _instCache = { token: null, expEpoch: 0 };
+let _instIdCache = null;
+// Negative cache for APP_NOT_INSTALLED: during an active ship the publish-status
+// poll fires every few seconds, and re-discovering a known-absent installation
+// each time re-mints a JWT + two GitHub calls for the same answer.
+const NOT_INSTALLED_TTL_MS = 60_000;
+let _notInstalled = { untilMs: 0, err: null };
 function _resetAppTokenCacheForTests() {
   _instCache = { token: null, expEpoch: 0 };
+  _instIdCache = null;
+  _notInstalled = { untilMs: 0, err: null };
+}
+
+function appJwtHeaders(jwt) {
+  return {
+    Authorization: `Bearer ${jwt}`,
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+    'User-Agent': userAgent(),
+  };
+}
+
+// Discover the App's installation id on THIS repo (task 1003049). A manifest-born
+// instance (ADR 0133) knows its App id + private key at cred-placement time but not
+// the installation id — the owner installs the App as a separate onboarding step —
+// so the server derives it live instead of requiring a third env var. Throws
+// APP_NOT_INSTALLED (with a best-effort install_url) when the App exists but nobody
+// has installed it on the repo yet: that is the one remaining human step, and the
+// refusal must say so in a sentence, not a bare code.
+async function discoverInstallationId(jwt, deps = {}) {
+  if (_instIdCache) return _instIdCache;
+  const nowMs = deps.now ? deps.now() : Date.now();
+  if (_notInstalled.err && nowMs < _notInstalled.untilMs) throw _notInstalled.err;
+  const info = deps.repoInfo || loadRepoInfo();
+  if (!info || info.error) throw err('NO_REPO_INFO');
+  const { owner, repo } = info;
+  const doFetch = deps.fetchImpl || fetch;
+  const res = await doFetch(`https://api.github.com/repos/${owner}/${repo}/installation`, {
+    headers: appJwtHeaders(jwt),
+  });
+  if (res.status === 404) {
+    // The App is real (the JWT authenticated) but not installed on the repo.
+    // Fetch the App's own page for a clickable install URL (best-effort — the
+    // guidance sentence works without it).
+    let installUrl = null;
+    try {
+      const appRes = await doFetch('https://api.github.com/app', { headers: appJwtHeaders(jwt) });
+      if (appRes.ok) {
+        const app = await appRes.json();
+        if (app && app.html_url) installUrl = `${app.html_url}/installations/new`;
+      }
+    } catch (_) { /* best-effort */ }
+    const e = err('APP_NOT_INSTALLED', { owner, repo, install_url: installUrl });
+    _notInstalled = { untilMs: nowMs + NOT_INSTALLED_TTL_MS, err: e };
+    throw e;
+  }
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '');
+    throw err('APP_TOKEN_FAILED', { status: res.status, detail: detail.slice(0, 200) });
+  }
+  const data = await res.json();
+  if (!data || data.id == null) {
+    throw err('APP_TOKEN_FAILED', { status: res.status, detail: 'installation lookup returned no id' });
+  }
+  _notInstalled = { untilMs: 0, err: null };
+  _instIdCache = String(data.id);
+  return _instIdCache;
 }
 
 // Returns a fresh/cached App installation token, or null if the App isn't
@@ -219,20 +287,22 @@ async function getInstallationToken(deps = {}) {
     privateKeyPem: process.env.GITHUB_APP_PRIVATE_KEY,
     nowSec,
   });
+  // An explicit env id wins (the ADR 0055 v1 shape); otherwise discover it from
+  // the repo (task 1003049 — fresh instances never know it up front).
+  const instId = process.env.GITHUB_APP_INSTALLATION_ID || (await discoverInstallationId(jwt, deps));
   const doFetch = deps.fetchImpl || fetch;
   const res = await doFetch(
-    `https://api.github.com/app/installations/${process.env.GITHUB_APP_INSTALLATION_ID}/access_tokens`,
+    `https://api.github.com/app/installations/${instId}/access_tokens`,
     {
       method: 'POST',
-      headers: {
-        Authorization: `Bearer ${jwt}`,
-        Accept: 'application/vnd.github+json',
-        'X-GitHub-Api-Version': '2022-11-28',
-        'User-Agent': userAgent(),
-      },
+      headers: appJwtHeaders(jwt),
     }
   );
   if (!res.ok) {
+    // A DISCOVERED id can go stale (App uninstalled + reinstalled gets a new
+    // installation id). Drop it so the next attempt re-discovers instead of
+    // failing until a server restart. An env-pinned id is the operator's to fix.
+    if (!process.env.GITHUB_APP_INSTALLATION_ID) _instIdCache = null;
     const detail = await res.text().catch(() => '');
     throw err('APP_TOKEN_FAILED', { status: res.status, detail: detail.slice(0, 200) });
   }
@@ -244,6 +314,42 @@ async function getInstallationToken(deps = {}) {
   return data.token;
 }
 
+// Installations of this App on accounts OTHER than this repo's owner (task
+// 1003049 grade, hacker finding). The App is public (W6) and now carries the
+// ADR 0055 write scopes, so any third party CAN install it on their own repos —
+// this server never uses those grants, but a leaked App private key could, so an
+// unexpected install must be visible, never silent. The publish-reconciler calls
+// this once per sweep and WARNs on a non-empty answer. Best-effort by design:
+// returns null when it cannot tell (App unconfigured, repo info missing, API
+// miss) — a watch must never break the sweep it rides on.
+async function foreignInstallations(deps = {}) {
+  if (!appConfigured()) return null;
+  const info = deps.repoInfo || loadRepoInfo();
+  if (!info || info.error) return null;
+  const nowSec = Math.floor((deps.now ? deps.now() : Date.now()) / 1000);
+  const jwt = mintAppJwt({
+    appId: process.env.GITHUB_APP_ID,
+    privateKeyPem: process.env.GITHUB_APP_PRIVATE_KEY,
+    nowSec,
+  });
+  const doFetch = deps.fetchImpl || fetch;
+  let data;
+  try {
+    const res = await doFetch('https://api.github.com/app/installations?per_page=100', {
+      headers: appJwtHeaders(jwt),
+    });
+    if (!res.ok) return null;
+    data = await res.json();
+  } catch (_) {
+    return null;
+  }
+  if (!Array.isArray(data)) return null;
+  const owner = String(info.owner || '').toLowerCase();
+  return data
+    .map((i) => ({ id: i && i.id, account: (i && i.account && i.account.login) || null }))
+    .filter((i) => String(i.account || '').toLowerCase() !== owner);
+}
+
 // Resolve the credential for git push + GitHub API: an explicitly-injected token
 // (tests) first, then a GitHub App installation token, then the v1 PAT, else null.
 async function resolveToken(deps = {}) {
@@ -863,7 +969,11 @@ async function updateBranchIfBehind({ branch }, deps = {}) {
 // returns false on any failure, in which case the gate-review check sees no attestation
 // and escalates — the SAFE direction (no rank bypass without a real server signal).
 async function setCommitStatus({ sha, state, context, description, targetUrl }, deps = {}) {
-  const token = await resolveToken(deps);
+  // resolveToken can THROW (APP_TOKEN_FAILED / APP_NOT_INSTALLED); this helper's
+  // contract is "false on any failure" — the gate-review check then escalates,
+  // which is the safe direction.
+  let token;
+  try { token = await resolveToken(deps); } catch (_) { return false; }
   if (!token) return false;
   if (!SAFE_SHA_RE.test(String(sha || ''))) return false;
   const repoInfo = deps.repoInfo || loadRepoInfo();
@@ -1253,6 +1363,8 @@ module.exports = {
   isAncestorOfDefaultBranch,
   resolveToken,
   getInstallationToken,
+  discoverInstallationId,
+  foreignInstallations,
   // exported for unit tests
   buildAuthUrl,
   mintAppJwt,

package/modules/lifecycle/publish-reconciler.js

@@ -191,13 +191,56 @@ async function runSweep(deps = {}) {
     if (!warn.unconfigured) {
       warn.unconfigured = true;
       errFn(
-        `[publish-reconciler] WARN ${describeTarget({ configured: false, repo: resolveTarget(deps) })} — confirmed→shipped can NEVER land until a credential is set (GITHUB_APP_ID + GITHUB_APP_INSTALLATION_ID + GITHUB_APP_PRIVATE_KEY, or GITHUB_PUSH_TOKEN). Subsequent sweeps stay quiet until this changes.`
+        `[publish-reconciler] WARN ${describeTarget({ configured: false, repo: resolveTarget(deps) })} — confirmed→shipped can NEVER land until a credential is set (GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY — installation id is auto-discovered — or GITHUB_PUSH_TOKEN). Subsequent sweeps stay quiet until this changes.`
       );
     }
     return { skipped: 'unconfigured', checked: 0, reconciled: 0, merged: 0, resolvedConflicts: 0, errors: 0, strandsFlagged: 0 };
   }
   warn.unconfigured = false; // re-arm: a later credential LOSS must warn again
 
+  // task 1003049 — an App that is configured but NOT INSTALLED on the repo would
+  // pass the gate above and then throw APP_NOT_INSTALLED inside every per-branch
+  // call, where the best-effort catches swallow it — silently re-creating the
+  // stranding this sweep exists to prevent. Probe the token once (cached, so a
+  // healthy steady state costs nothing) and WARN once per streak instead.
+  if (typeof push.getInstallationToken === 'function' && typeof push.appConfigured === 'function' && push.appConfigured()) {
+    try {
+      await push.getInstallationToken();
+      warn.appNotInstalled = false; // re-arm: a later uninstall must warn again
+      // Foreign-install watch (task 1003049 grade): the App is public (W6) and
+      // carries write scopes, so a stranger CAN install it on their own repo.
+      // This server never uses that grant, but a leaked App key could — an
+      // unexpected install is surfaced loudly, once per streak, never silently.
+      if (typeof push.foreignInstallations === 'function') {
+        try {
+          const foreign = await push.foreignInstallations();
+          if (foreign && foreign.length) {
+            if (!warn.foreignInstalls) {
+              warn.foreignInstalls = true;
+              errFn(
+                `[publish-reconciler] WARN this project's GitHub App is installed on ${foreign.length} account(s) beyond the repo owner (${foreign.map((f) => f.account).filter(Boolean).join(', ')}). The server never uses those grants, but the App key's blast radius includes them — uninstall the App there (or rotate the key) if this is unexpected.`
+              );
+            }
+          } else if (foreign) {
+            warn.foreignInstalls = false; // re-arm once the roster is clean again
+          }
+        } catch (_) { /* best-effort watch — never breaks the sweep */ }
+      }
+    } catch (e) {
+      if (e && e.code === 'APP_NOT_INSTALLED') {
+        if (!warn.appNotInstalled) {
+          warn.appNotInstalled = true;
+          errFn(
+            `[publish-reconciler] WARN the project's GitHub App is not installed on ${e.owner}/${e.repo} — confirmed→shipped can NEVER land until someone installs it${e.install_url ? ` (${e.install_url})` : ''}. Subsequent sweeps stay quiet until this changes.`
+          );
+        }
+        return { skipped: 'app_not_installed', checked: 0, reconciled: 0, merged: 0, resolvedConflicts: 0, errors: 0, strandsFlagged: 0 };
+      }
+      // Any other failure (APP_TOKEN_FAILED, network) is transient territory — let
+      // the sweep run; the per-branch calls handle their own misses.
+    }
+  }
+
   let rows;
   try {
     rows = await db.listConfirmedTasksForReconcile({ limit: deps.limit || SWEEP_LIMIT });