@bongos/core 1.19.205 → 1.19.207

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 276 endpoints across 46 route files.
+> **Generated from the live route files** — the route file is authoritative. 278 endpoints across 46 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -369,7 +369,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/projects/featured` | `public` | — | a curated public showcase; no auth by design. |
 | POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | invite a builder into a project (ADR 0141 §5, task #1002115). |
 
-## `provisioning` (15)
+## `provisioning` (17)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -384,6 +384,8 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/provisioning/instances/:id/domain` | `any-builder` | `domain` | POST /provisioning/instances/:id/domain — give the caller's OWN instance its address (task 1002692, gap 5: no path existed to add a domai… |
 | POST | `/api/bongos/provisioning/instances/:id/force-teardown` | `metic+archon` | — | POST /provisioning/instances/:id/force-teardown — Archon tears down ANY instance. |
 | POST | `/api/bongos/provisioning/instances/:id/github-app` | `any-builder` | `account` | POST /provisioning/instances/:id/github-app — mint a GitHub-App-Manifest onboarding link for the caller's OWN instance (task 2080, ADR 01… |
+| GET | `/api/bongos/provisioning/instances/:id/settings` | `any-builder` | — | GET /provisioning/instances/:id/settings — read a project's effective settings + the allowed values (so a form can render its choices). |
+| PATCH | `/api/bongos/provisioning/instances/:id/settings` | `any-builder` | `platform_visibility`, `joinability` | PATCH /provisioning/instances/:id/settings — change a project's settings. |
 | POST | `/api/bongos/provisioning/instances/:id/teardown` | `any-builder` | — | POST /provisioning/instances/:id/teardown — request teardown of the caller's OWN instance. |
 | GET | `/api/bongos/provisioning/onboard-plan` | `public` | — | GET /provisioning/onboard-plan?mode=greenfield\|adopt&domain=<host> — the CANONICAL onboarding step sequence (task 2085; goal 35 / criteri… |
 | GET | `/api/bongos/provisioning/slug-available` | `any-builder` | — | GET /provisioning/slug-available?slug=<handle> — is this handle free to create under? rank: any authenticated builder (same gate as the c… |

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/dev-box/app/src/vendor/bongos-client.cjs

@@ -542,6 +542,10 @@ function createClient(opts = {}) {
       postProvisioningInstancesIdForceTeardown: (args) => request("POST", "/provisioning/instances/{id}/force-teardown", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/github-app — rank: any-builder — POST /provisioning/instances/:id/github-app
       postProvisioningInstancesIdGithubApp: (args) => request("POST", "/provisioning/instances/{id}/github-app", { hasBody: true }, args),
+      // GET /provisioning/instances/{id}/settings — rank: any-builder — GET /provisioning/instances/:id/settings
+      getProvisioningInstancesIdSettings: (args) => request("GET", "/provisioning/instances/{id}/settings", { hasBody: false }, args),
+      // PATCH /provisioning/instances/{id}/settings — rank: any-builder — PATCH /provisioning/instances/:id/settings
+      patchProvisioningInstancesIdSettings: (args) => request("PATCH", "/provisioning/instances/{id}/settings", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/teardown — rank: any-builder — POST /provisioning/instances/:id/teardown
       postProvisioningInstancesIdTeardown: (args) => request("POST", "/provisioning/instances/{id}/teardown", { hasBody: true }, args),
       // GET /provisioning/onboard-plan — rank: public — GET /provisioning/onboard-plan

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

package/modules/lifecycle/routes/tasks.js

@@ -1552,6 +1552,21 @@ module.exports = function buildTasksRouter() {
     }
   });
 
+  // Plain-sentence publish-credential refusals (task 1003049 / gap-list W7). A
+  // bare 'push_unconfigured' left fresh-instance owners with no idea what was
+  // missing while every ship silently piled at 'confirmed' — the refusal must
+  // say what to set up and where.
+  const PUSH_UNCONFIGURED_MSG =
+    'This project has no publish credential, so the server cannot push or merge task branches and shipped work waits at confirmed. ' +
+    "To fix it, install the project's GitHub App on the repo (the onboarding “Install the GitHub App” step) with GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY set in the server env, " +
+    'or set a fine-grained GITHUB_PUSH_TOKEN PAT there instead (ADR 0055).';
+  const appNotInstalledMessage = (e) => {
+    const repo = e && e.owner && e.repo ? `${e.owner}/${e.repo}` : 'the project repository';
+    const where = e && e.install_url ? `at ${e.install_url}` : "from the App's page in GitHub settings (Install App)";
+    return `The project's GitHub App is configured but not installed on ${repo}, so the server cannot push or merge task branches. ` +
+      `Install it ${where}, then retry — no other setup is needed.`;
+  };
+
   // ==========================================================================
   // Server-mediated branch publish (ADR 0055 / task 1025)
   // --------------------------------------------------------------------------
@@ -1584,8 +1599,8 @@ module.exports = function buildTasksRouter() {
     // (or an Archon) may publish this task's branch.
     if (!(await gateTaskOwnership(req, res, id))) return;
     if (!githubPush.isConfigured()) {
-      return res.fail('push_unconfigured', { status: 503, message: 'Server-mediated push is not configured (no GitHub App nor GITHUB_PUSH_TOKEN on the server). ' +
-          'Ask the operator to provision it; meanwhile ship from a machine with its own git push credentials.' });
+      return res.fail('push_unconfigured', { status: 503, message: PUSH_UNCONFIGURED_MSG +
+          ' Meanwhile you can ship from a machine with its own git push credentials.' });
     }
     const { branch, head_sha: headSha, value_summary: valueSummary } = req.body;
     if (!githubPush.isSafeBranch(branch)) return res.fail('bad_branch', 400);
@@ -1647,7 +1662,8 @@ module.exports = function buildTasksRouter() {
       if (e.code === 'BAD_BRANCH') return res.fail('bad_branch', 400);
       if (e.code === 'BAD_SHA') return res.fail('bad_head_sha', 400);
       if (e.code === 'NO_REPO_INFO') return res.fail('no_repo_info', 500);
-      if (e.code === 'PUSH_UNCONFIGURED') return res.fail('push_unconfigured', 503);
+      if (e.code === 'PUSH_UNCONFIGURED') return res.fail('push_unconfigured', { status: 503, message: PUSH_UNCONFIGURED_MSG });
+      if (e.code === 'APP_NOT_INSTALLED') return res.fail('push_unconfigured', { status: 503, message: appNotInstalledMessage(e) });
       if (e.code === 'PR_CREATE_FAILED') return res.fail('pr_create_failed', 502, { detail: e.detail });
       // task 1547: GIT_FAILED now carries WHICH git step failed + the credential-
       // scrubbed stderr (github-push.defaultExec). Log both so the next push outage
@@ -1672,7 +1688,7 @@ module.exports = function buildTasksRouter() {
     const id = parseId(req, res, { code: 'bad_task_id' });
     if (id === null) return;
     if (!(await gateTaskOwnership(req, res, id))) return;
-    if (!githubPush.isConfigured()) return res.fail('push_unconfigured', 503);
+    if (!githubPush.isConfigured()) return res.fail('push_unconfigured', { status: 503, message: PUSH_UNCONFIGURED_MSG });
     const branch = req.query.branch;
     if (!githubPush.isSafeBranch(branch)) return res.fail('bad_branch', 400);
     try {
@@ -1739,6 +1755,7 @@ module.exports = function buildTasksRouter() {
       return res.json({ ok: true, ...status, reconciled, reconcile_blocked, merge_driver });
     } catch (e) {
       if (e.code === 'NO_REPO_INFO') return res.fail('no_repo_info', 500);
+      if (e.code === 'APP_NOT_INSTALLED') return res.fail('push_unconfigured', { status: 503, message: appNotInstalledMessage(e) });
       console.error('[gds] GET /tasks/:id/publish-status', e.code || e.message);
       return res.fail('status_failed', 502);
     }

package/modules/provisioning/migrations/provisioning_009_project_settings.sql

@@ -0,0 +1,19 @@
+-- provisioning_009_project_settings.sql — per-project settings storage (task
+-- 1003040, goal 1000058: the project-management page wave's foundation).
+--
+-- WHY jsonb, not columns: the manage-page wave adds settings one task at a time
+-- (platform visibility, joinability, repo visibility, …) and a new key must not
+-- cost a migration each time. The column is a dumb store; the known keys + their
+-- vocabularies are enforced at the API layer (provisioning.SETTINGS_VOCAB /
+-- the settings routes' validator), and unknown stored values fall back to the
+-- default at read time (effectiveSettings) rather than leaking out.
+--
+-- DEFAULTS = today's behavior: '{}'::jsonb READS as
+-- { platform_visibility: 'public', joinability: 'apply' } — the default lives in
+-- code, applied at read time, so ADD COLUMN backfills every existing row with an
+-- empty object and no instance changes behavior.
+ALTER TABLE provisioning_instances
+  ADD COLUMN IF NOT EXISTS settings jsonb NOT NULL DEFAULT '{}'::jsonb;
+
+INSERT INTO schema_migrations (version) VALUES ('provisioning_009_project_settings')
+ON CONFLICT (version) DO NOTHING;

package/modules/provisioning/onboard-plan.js

@@ -44,6 +44,7 @@ function onboardPlan(mode = 'greenfield', opts = {}) {
     { key: 'seed-version', kind: 'auto', label: 'Seed the first version (V1) so the instance can take tasks immediately (task 2119)' },
     { key: 'oauth-app', kind: 'human', label: 'Wire GitHub sign-in — one-click GitHub App (task 2080), or a manual OAuth app' },
     { key: 'oauth-place', kind: 'auto', shapes: CONTROL_PLANE_SHAPES, label: 'Place the OAuth secret — auto via the Manifest flow, or verified manual (task 1979)' },
+    { key: 'app-install', kind: 'human', label: 'Install the GitHub App on the repo — the publish credential that lets shipped work land itself (task 1003049, ADR 0055)' },
     { key: 'first-sign-in', kind: 'human', label: 'First sign-in (seats the founding Archon)' },
     { key: 'verify', kind: 'auto', label: 'Verify /healthz auth_configured' },
     { key: 'brand', kind: 'auto', label: 'Brand the instance look' },

package/modules/provisioning/provisioning.js

@@ -59,6 +59,17 @@ const PROVISION_ENQUEUE_FROM = new Set(['requested', 'provisioning', 'error', 't
 // itself. Mid-flight or torn-down states refuse truthfully.
 const DOMAIN_ATTACH_FROM = new Set(['requested', 'error', 'active']);
 
+// Per-project settings (task 1003040, goal 1000058): the known keys + their
+// vocabularies, enforced at the API layer — the jsonb `settings` column
+// (migration provisioning_009) is a dumb store with room for future keys.
+// DEFAULT_SETTINGS is TODAY's behavior (public surfaces, apply-to-join),
+// applied at read time so pre-existing rows need no data backfill.
+const SETTINGS_VOCAB = Object.freeze({
+  platform_visibility: ['public', 'gated'],
+  joinability: ['open', 'apply', 'invite_only'],
+});
+const DEFAULT_SETTINGS = Object.freeze({ platform_visibility: 'public', joinability: 'apply' });
+
 // Monthly cost estimate (USD) for a dedicated droplet tier — VISIBILITY only
 // (ADR 0111 §6), never a bill. A small local table so this module needs no
 // sibling-module import; P2 (shared control-plane client extraction) is where a
@@ -210,6 +221,19 @@ function publicInstance(row) {
   };
 }
 
+// The instance's EFFECTIVE settings: the defaults overlaid with the stored,
+// on-vocabulary keys. An off-vocabulary or unknown stored value falls back to
+// its default rather than leaking into the read surface. PURE.
+function effectiveSettings(row) {
+  const stored = row && row.settings && typeof row.settings === 'object' && !Array.isArray(row.settings)
+    ? row.settings : {};
+  const out = { ...DEFAULT_SETTINGS };
+  for (const [key, vocab] of Object.entries(SETTINGS_VOCAB)) {
+    if (vocab.includes(stored[key])) out[key] = stored[key];
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // GitHub App Manifest flow — PURE builders (task 2080, ADR 0133).
 // GitHub has no create-an-OAuth-App API, but the App *Manifest* flow lets the owner
@@ -265,16 +289,21 @@ function githubAppName({ domain, brand, project } = {}) {
 //   • callback_urls — where "Login with GitHub" on the INSTANCE redirects during real
 //     sign-in. Both /api/gds/... (what auth.js actually builds) and the /api/bongos/...
 //     alias are registered so sign-in works regardless of which prefix a build emits.
-// Minimal for sign-in: no repo permissions, no webhook (active:false). PURE.
+// No webhook (active:false). PURE.
 function buildGithubAppManifest({ instanceName, slug, instanceDomain, mothershipOrigin, brand }) {
   const instOrigin = `https://${instanceDomain}`;
   const redirectUrl = `${String(mothershipOrigin || '').replace(/\/+$/, '')}/api/bongos/provisioning/github-app/callback`;
   return {
     name: githubAppName({ domain: instanceDomain, brand, project: instanceName || slug }),
     url: instOrigin,
-    // Sign-in only ever calls GET /user with the user-to-server token — no repo/account
-    // permissions are needed, so request none (least privilege).
-    default_permissions: {},
+    // Sign-in itself needs no permissions (GET /user with a user-to-server token),
+    // but this App DOUBLES as the instance's ADR 0055 publish credential (task
+    // 1003049 / gap-list W7): once installed on the repo, the server mints
+    // installation tokens to push task branches, open/merge PRs, and read deploy
+    // runs — without them every ship strands at 'confirmed' behind manual archon
+    // merges. Exactly the ADR 0055 scopes, nothing more; the App still cannot
+    // push to branch-protected main nor bypass required checks.
+    default_permissions: { contents: 'write', pull_requests: 'write', actions: 'read' },
     default_events: [],
     // No webhook: active:false. A url is still supplied (GitHub validates the shape) but
     // is never called while inactive; point it at the mothership so it's a real host.
@@ -286,10 +315,15 @@ function buildGithubAppManifest({ instanceName, slug, instanceDomain, mothership
     ],
     // public: GitHub answers a PRIVATE App's web authorize URL for any non-owner
     // account with a bare 404 (before the instance is ever involved), so a private
-    // App makes the project structurally single-builder on the web. The App requests
-    // zero permissions, so public costs nothing (gap-list W6, task 1003048). Apps
-    // minted before this fix stay private until flipped by hand — see
-    // docs/recipes/ops-gotchas.md.
+    // App makes the project structurally single-builder on the web (gap-list W6,
+    // task 1003048). TRADE-OFF now that the App carries write scopes: public means
+    // any third party can install it on THEIR 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 W6; mitigated by the publish-reconciler's foreign-install
+    // watch (github-push.foreignInstallations), which warns whenever the App is
+    // installed anywhere beyond the repo owner. Apps minted before the W6 fix stay
+    // private until flipped by hand — see docs/recipes/ops-gotchas.md.
     public: true,
   };
 }
@@ -335,6 +369,20 @@ async function getInstanceByDomain(db, domain) {
   return rows[0] || null;
 }
 
+// Merge a VALIDATED settings patch into the instance's settings column (task
+// 1003040). Narrow like updateInstanceDomain: settings + updated_at only — a
+// settings change is a deliberate owner action, so surfacing it in the
+// updated_at-ordered card list is correct (unlike the liveness overlay).
+async function updateInstanceSettings(db, id, patch) {
+  const { rows } = await db.query(
+    `UPDATE provisioning_instances
+        SET settings = settings || $2::jsonb, updated_at = now()
+      WHERE id = $1 RETURNING *`,
+    [id, JSON.stringify(patch)]
+  );
+  return rows[0] || null;
+}
+
 // Record an instance's domain — the ONLY column this touches (task 1002692). Status
 // changes stay setInstanceStatus's job; keeping this narrow means the domain-attach
 // route can never drift an instance's lifecycle as a side effect.
@@ -725,9 +773,10 @@ module.exports = {
   // constants
   INSTANCE_STATES, HOSTING_SHAPES, ONBOARD_MODES, PROJECT_TYPES, INTENT_ACTIONS, TEARDOWN_FROM,
   PROVISION_ENQUEUE_FROM, DOMAIN_ATTACH_FROM, TIER_MONTHLY_USD, CERT_ELIGIBLE_STATES,
+  SETTINGS_VOCAB, DEFAULT_SETTINGS,
   // pure
   isValidSlug, costEstimateUsd, publicInstance, normalizeHostname,
-  defaultDomainForSlug, isReservedHostname,
+  defaultDomainForSlug, isReservedHostname, effectiveSettings,
   // pure — GitHub App Manifest flow (task 2080)
   githubAppName, buildGithubAppManifest, manifestPostUrl,
   // data access
@@ -735,7 +784,7 @@ module.exports = {
   getInstanceById, getInstanceBySlug, getInstanceByDomain, listInstancesForOwner, listAllInstances,
   // data access — verification overlay (task 1002696)
   listActiveInstancesForLiveness, recordLivenessProbe, recordDnsNote, clearErrorNote,
-  createInstance, setInstanceStatus, updateInstanceDomain,
+  createInstance, setInstanceStatus, updateInstanceDomain, updateInstanceSettings,
   enqueueIntent, enqueueTeardown, getOpenIntent, claimNextIntent, resolveIntent,
   recordEvent, instanceStateForSlug, costLedger,
   // data access — GitHub App Manifest attempts (task 2080)

package/modules/provisioning/routes/provisioning.js

@@ -591,6 +591,69 @@ module.exports = function provisioningRoutes() {
     }
   });
 
+  // ── Per-project settings (task 1003040, goal 1000058) ─────────────────────
+  // The foundation the manage-page wave hangs off: effective settings are the
+  // DEFAULTS (today's behavior — public surfaces, apply-to-join) overlaid with
+  // the instance's stored keys. Own-scoped with an Archon override: the owner
+  // manages their own project; an Archon may act on any (fleet support). 404
+  // for everyone else — no existence leak (the GET-by-id precedent).
+  function settingsAccessDenied(inst, builder) {
+    if (!inst) return true;
+    if (builder.rank === 'archon') return false;
+    return String(inst.owner_builder_id) !== String(builder.id);
+  }
+
+  // GET /provisioning/instances/:id/settings — read a project's effective
+  // settings + the allowed values (so a form can render its choices).
+  // rank: any authenticated builder (own resource; archon may read any).
+  router.get('/provisioning/instances/:id/settings', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
+    if (!id) return;
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (settingsAccessDenied(inst, req.builder)) return res.fail('instance_not_found', 404);
+      res.json({ ok: true, settings: provisioning.effectiveSettings(inst), options: provisioning.SETTINGS_VOCAB });
+    } catch (err) {
+      console.error('[provisioning] GET /provisioning/instances/:id/settings', err);
+      res.fail('settings_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH /provisioning/instances/:id/settings — change a project's settings.
+  // Body: any subset of the known keys; strict validation refuses unknown keys
+  // and off-vocabulary values. rank: any authenticated builder (own resource;
+  // archon may change any — the override is audited via the event's actor).
+  router.patch('/provisioning/instances/:id/settings', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
+    if (!id) return;
+    if (validateOrRespond(req, res, {
+      platform_visibility: { type: 'string', enum: provisioning.SETTINGS_VOCAB.platform_visibility },
+      joinability: { type: 'string', enum: provisioning.SETTINGS_VOCAB.joinability },
+    })) return;
+    const patch = {};
+    for (const key of Object.keys(provisioning.SETTINGS_VOCAB)) {
+      if ((req.body || {})[key] !== undefined) patch[key] = req.body[key];
+    }
+    if (!Object.keys(patch).length) {
+      return res.fail('bad_settings', { status: 400,
+        message: `The body carries no settings to change — send any of: ${Object.keys(provisioning.SETTINGS_VOCAB).join(', ')}.` });
+    }
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (settingsAccessDenied(inst, req.builder)) return res.fail('instance_not_found', 404);
+      const updated = await provisioning.updateInstanceSettings(pool, id, patch);
+      await provisioning.recordEvent(pool, {
+        instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'settings',
+        detail: `settings changed: ${Object.entries(patch).map(([k, v]) => `${k}=${v}`).join(', ')}`,
+        actor: String(inst.owner_builder_id) === String(req.builder.id) ? 'api:self' : 'api:archon',
+      }).catch(() => {});
+      res.json({ ok: true, settings: provisioning.effectiveSettings(updated) });
+    } catch (err) {
+      console.error('[provisioning] PATCH /provisioning/instances/:id/settings', err);
+      res.fail('settings_update_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // POST /provisioning/instances/:id/teardown — request teardown of the caller's
   // OWN instance. rank: any authenticated builder (own resource). Enqueues a
   // 'teardown' intent; the runner executes it (web tier holds no tokens). 404 when
@@ -892,6 +955,10 @@ module.exports = function provisioningRoutes() {
         terminal: status === 'done' || status === 'error' || status === 'expired',
         domain: inst && inst.domain ? inst.domain : null,
         instance_status: inst ? inst.status : null,
+        // The App's public slug (task 1003049): lets the wizard render the one-click
+        // install link (github.com/apps/<slug>/installations/new) for the app-install
+        // step. Public info — the App's page is public by design (task 1003048).
+        app_slug: row.app_slug || null,
       });
     } catch (err) {
       console.error('[provisioning] GET /provisioning/github-app/status', err);