@bongos/core 1.19.204 → 1.19.206

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/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

@@ -265,16 +265,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 +291,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,
   };
 }

package/modules/provisioning/routes/provisioning.js

@@ -892,6 +892,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);

package/modules/provisioning/tests/provisioning.mjs

@@ -165,7 +165,7 @@ t('githubAppName falls back to brand-qualified project when there is no usable d
   assert.ok(long.length <= 34 && long.startsWith('Cloud Bongos - '), `capped + brand kept: ${long}`);
 });
 
-t('buildGithubAppManifest points redirect at the MOTHERSHIP, callbacks at the INSTANCE, minimal perms, public, domain-named', () => {
+t('buildGithubAppManifest points redirect at the MOTHERSHIP, callbacks at the INSTANCE, ADR 0055 publish scopes, public, domain-named', () => {
   const m = P.buildGithubAppManifest({
     instanceName: 'mercury', slug: 'mercury', brand: 'Cloud Bongos',
     instanceDomain: 'mercury.example.com', mothershipOrigin: 'https://cloudbongos.com',
@@ -179,8 +179,10 @@ t('buildGithubAppManifest points redirect at the MOTHERSHIP, callbacks at the IN
     'https://mercury.example.com/api/gds/auth/web/callback',
     'https://mercury.example.com/api/bongos/auth/web/callback',
   ]);
-  // sign-in needs no repo/account permissions; no active webhook
-  assert.deepEqual(m.default_permissions, {});
+  // The App doubles as the ADR 0055 publish credential (task 1003049): exactly the
+  // three publish scopes — Contents rw (push branches), PR rw (open/merge), Actions
+  // read (deploy probe) — and nothing more. No active webhook.
+  assert.deepEqual(m.default_permissions, { contents: 'write', pull_requests: 'write', actions: 'read' });
   assert.equal(m.hook_attributes.active, false);
   // public: a PRIVATE App answers the web authorize URL for any non-owner with a bare
   // GitHub 404, making the project single-builder on the web (gap-list W6, task 1003048)

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.204",
+  "version": "1.19.206",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/public-landing/projects.html

@@ -2768,7 +2768,7 @@ h1[tabindex="-1"]:focus{outline:none;}
     var GH_ICON = '<svg class="gh" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27s1.36.09 2 .27c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8z"/></svg>';
 
     var instanceId = null;             /* set when a create lands / a resumed watch starts */
-    var live = { instStatus: null, manifest: null, manifestMsg: '' };
+    var live = { instStatus: null, manifest: null, manifestMsg: '', appSlug: null };
     var planPromises = {};             /* mode|domain → Promise<steps[]> */
     var lastStepsHtml = '';
     var FALLBACK_HUMAN_KEYS = ['github-repo', 'oauth-app', 'first-sign-in', 'enter-hall'];
@@ -2861,6 +2861,21 @@ h1[tabindex="-1"]:focus{outline:none;}
         '<button type="button" class="ghbtn" data-action="manifest-start">' + GH_ICON + 'Set up GitHub sign-in</button>' + manualOauthDetails() + '</li>';
     }
 
+    /* app-install — the ADR 0055 publish credential (task 1003049): the sign-in App
+       doubles as it, but only an INSTALLED App can mint push tokens; without this
+       one click every finished task waits at confirmed for a manual merge. */
+    function renderStepAppInstall() {
+      if (live.manifest !== 'done') {
+        return '<li class="slocked" data-onboard-step="app-install"><b>Install the GitHub App on your repo</b><p>Unlocks once GitHub sign-in above is wired — the same app, installed on your repo, is what lets finished work merge and ship itself.</p></li>';
+      }
+      var installUrl = live.appSlug ? 'https://github.com/apps/' + esc(live.appSlug) + '/installations/new' : null;
+      return '<li data-onboard-step="app-install"><b>Install the GitHub App on your repo</b><p>One click: install the app you just approved on this project’s repo. Without it, finished work waits for a manual merge instead of shipping itself.</p>' +
+        (installUrl
+          ? '<a class="ghbtn" href="' + installUrl + '" target="_blank" rel="noopener">' + GH_ICON + 'Install the app on your repo</a>'
+          : '<p>GitHub → Settings → Developer settings → GitHub Apps → your app → <strong>Install App</strong> → pick this project’s repo.</p>') +
+        '</li>';
+    }
+
     function renderStepFirstSignIn() {
       var domain = resolvedDomain();
       if (!domain) {
@@ -2879,6 +2894,7 @@ h1[tabindex="-1"]:focus{outline:none;}
     var STEP_RENDERERS = {
       'github-repo': renderStepGithubRepo,
       'oauth-app': renderStepOauthApp,
+      'app-install': renderStepAppInstall,
       'first-sign-in': renderStepFirstSignIn,
       'enter-hall': renderStepEnterHall
     };
@@ -3007,6 +3023,7 @@ h1[tabindex="-1"]:focus{outline:none;}
           .then(function (res) { if (!res.ok) throw new Error('soft'); return res.json(); })
           .then(function (d) {
             if (myGen !== manifestGen) return;
+            if (d.app_slug && d.app_slug !== live.appSlug) { live.appSlug = d.app_slug; renderSteps(); }
             var next = d.ready ? 'done' : (d.status || 'pending');
             if (next !== live.manifest) { live.manifest = next; renderSteps(); }
             if (!d.terminal) manifestPollTimer = setTimeout(tick, 4000);
@@ -3187,7 +3204,7 @@ h1[tabindex="-1"]:focus{outline:none;}
         stopManifestPoll();
         instanceId = null;
         watchPending = false; manifestPending = false; manifestState = null;
-        live = { instStatus: null, manifest: null, manifestMsg: '' };
+        live = { instStatus: null, manifest: null, manifestMsg: '', appSlug: null };
         lastStepsHtml = '';
         try { sessionStorage.removeItem(CREATED_KEY); sessionStorage.removeItem(DRAFT_KEY); } catch (e) {}
         state = { step: 1, name: '', projType: null, mode: 'greenfield', owner: '', ownerTouched: false, repo: '', repoTouched: false, slug: '', slugTouched: false, domain: '', noAddress: false };

package/scripts/gds/onboard.js

@@ -9,9 +9,9 @@
 // provision → OAuth → verify → brand legs. Standalone model only (ADR 0108).
 //
 // It automates what it can (DNS token preflight, OAuth-cred validation, /healthz
-// verify) and renders the four irreducibly-human steps (create the GitHub repo, the
-// OAuth app + secret, own the domain, first sign-in) as precise, copy-paste-safe
-// prompts. It does NOT hold cloud tokens: the actual provision runs on the control
+// verify) and renders the irreducibly-human steps (create the GitHub repo, the
+// OAuth app + secret, install the App on the repo, own the domain, first sign-in)
+// as precise, copy-paste-safe prompts. It does NOT hold cloud tokens: the actual provision runs on the control
 // plane (it prints the exact `provision.js` command), preserving the trust boundary.
 
 const readline = require('node:readline');
@@ -189,6 +189,14 @@ async function run() {
       log('   (validates + rewrites web.env via Node + restarts + probes /healthz auth_configured — never hand-edit web.env.)');
       await ask(rl, 'Press Enter once oauth-secret reports auth_configured=true…');
 
+      // The publish credential (task 1003049, ADR 0055): the one-click App carries the
+      // repo scopes, but only an INSTALLED App can mint push tokens — skip this click
+      // and every ship strands at 'confirmed' behind a manual merge.
+      log('\n   Install the GitHub App on the repo — the publish credential that lets shipped work land itself:');
+      log('   github.com → Settings → Developer settings → GitHub Apps → your app → Install App → pick this project’s repo.');
+      log('   (On the manual OAuth-app path instead? Set a fine-grained GITHUB_PUSH_TOKEN in web.env — ADR 0055.)');
+      await ask(rl, 'Press Enter once the App is installed on the repo…');
+
       // Step 8/9 — first sign-in + verify
       log('\n⑦ First sign-in (seats the founding Archon):');
       log(`   Open ${oauthAppInstructions(a.domain).homepageUrl} and sign in with GitHub once.`);

package/scripts/gds/provision.js

@@ -1021,7 +1021,7 @@ function provisionedEnvPrefix() {
 // the hall on this host + OAuth uses the real callback origin — without them the pack
 // stays at neutral localhost and the hall never loads (task 1972). No domain yet
 // (bring-your-own deferred, ADR 0111 §4) ⇒ origins stay neutral until one is set.
-function webEnvBody(inst, { clientId = '', clientSecret = '', federation = null } = {}) {
+function webEnvBody(inst, { clientId = '', clientSecret = '', appId = null, appPem = null, federation = null } = {}) {
   const prefix = provisionedEnvPrefix();
   const origin = inst.domain ? `https://${inst.domain}` : '';
   const originLines = origin
@@ -1077,6 +1077,19 @@ ${prefix}_HUB_ORIGIN=${federation.hubOrigin}
 ${prefix}_HUB_CLIENT_ID=${federation.clientId}
 ${prefix}_HUB_CLIENT_SECRET=${federation.clientSecret}
 ${prefix}_HUB_PUBLIC_KEY=${federation.hubPublicKey}
+`
+    : '';
+  // The publish credential (task 1003049, ADR 0055): the manifest-born App's id +
+  // private key, read BARE (no prefix) by modules/lifecycle/github-push.js. The
+  // pem is env-file-flattened to a single line with literal \n (the ADR 0055
+  // rotation convention; normalizePem restores it). The installation id is NOT
+  // written — the server discovers it from the repo once the owner installs the
+  // App (the onboarding app-install step).
+  const appLines = appId && appPem
+    ? `# Publish credential (ADR 0055): the sign-in GitHub App doubles as it. The server
+# mints short-lived installation tokens once the App is INSTALLED on the repo.
+GITHUB_APP_ID=${appId}
+GITHUB_APP_PRIVATE_KEY=${String(appPem).replace(/\r?\n/g, '\\n')}
 `
     : '';
   return `# /etc/${inst.slug}/web.env — per-instance secrets (chmod 600, OUTSIDE the repo).
@@ -1084,7 +1097,7 @@ ${credComment}
 ${prefix}_GITHUB_CLIENT_ID=${clientId || ''}
 ${prefix}_GITHUB_CLIENT_SECRET=${clientSecret || ''}
 ${firstAdminLine}GDS_BRANDING_FILE=${PROVISIONED_BRANDING_FILE}
-${originLines}PORT=${inst.port}
+${originLines}${appLines}PORT=${inst.port}
 PGDATABASE=${dbName(inst)}
 ${fedLines}`;
 }
@@ -1948,6 +1961,10 @@ async function convertManifestCode(code, { fetchImpl = globalThis.fetch, userAge
     clientSecret: String(data.client_secret),
     appId: data.id != null ? Number(data.id) : null,
     appSlug: data.slug || null,
+    // The App private key (task 1003049): with the manifest now requesting the
+    // ADR 0055 repo scopes, this pem + the app id ARE the instance's publish
+    // credential — placed into web.env alongside the OAuth creds, never logged.
+    appPem: data.pem ? String(data.pem) : null,
   };
 }
 
@@ -1973,7 +1990,7 @@ async function placeManifestCreds(inst, mrow, deps) {
     creds = await (deps.convertManifestCode || convertManifestCode)(mrow.github_code, {});
   } else {
     log(`  [oauth-manifest] would POST api.github.com/app-manifests/<code>/conversions for ${inst.slug}`);
-    creds = { clientId: '0'.repeat(20), clientSecret: '0'.repeat(40), appId: null, appSlug: null };
+    creds = { clientId: '0'.repeat(20), clientSecret: '0'.repeat(40), appId: null, appSlug: null, appPem: null };
   }
 
   // 2) validate the returned creds BEFORE writing (catch a malformed GitHub response —
@@ -1991,7 +2008,13 @@ async function placeManifestCreds(inst, mrow, deps) {
   // 3) rewrite web.env with the creds + restart the unit (never logs the secret — the
   //    writeFile logs only a byte count; the value is base64/temp-file placed).
   log(`  [oauth-manifest] place creds in ${webEnvPath(inst)} + restart ${inst.slug}`);
-  boxWriteFile(webEnvPath(inst), webEnvBody(inst, { clientId: creds.clientId, clientSecret: creds.clientSecret }), { mode: 0o600, sudo: true });
+  boxWriteFile(webEnvPath(inst), webEnvBody(inst, {
+    clientId: creds.clientId, clientSecret: creds.clientSecret,
+    // The App id + private key double as the ADR 0055 publish credential (task
+    // 1003049); older Apps (pre-permission manifests) return a pem too — placing
+    // it is harmless and heals once the owner grants the permissions + installs.
+    appId: creds.appId, appPem: creds.appPem,
+  }), { mode: 0o600, sudo: true });
   boxExec(`${sudoP}systemctl restart ${inst.slug}`);
 
   // 4) verify /healthz reports auth_configured=true (only meaningful under --apply).

package/src/module-api.js

@@ -835,8 +835,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.202 with no explicit bump. run 32059705946. (task 1002620)
 //   1.19.204 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.203 with no explicit bump. run 32060607072. (task 1002620)
+//   1.19.205 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.204 with no explicit bump. run 32061149280. (task 1002620)
+//   1.19.206 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.205 with no explicit bump. run 32064728346. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.204'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.206'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/onboard.mjs

@@ -15,12 +15,16 @@ test('onboardPlan is the canonical sequence: name+address first, the builders ha
   assert.equal(keys[keys.length - 2], 'brand');
   // the irreducibly-human steps (must be UI-first prompts)
   const human = plan.filter((s) => s.kind === 'human').map((s) => s.key);
-  assert.deepEqual(human, ['github-repo', 'oauth-app', 'first-sign-in', 'enter-hall']);
+  assert.deepEqual(human, ['github-repo', 'oauth-app', 'app-install', 'first-sign-in', 'enter-hall']);
   // the DNS preflight comes BEFORE provision (task 1980: before the address step)
   assert.ok(keys.indexOf('dns-preflight') < keys.indexOf('provision'), 'dns preflight precedes provision');
   // OAuth secret placement comes after the OAuth app + before first sign-in
   assert.ok(keys.indexOf('oauth-app') < keys.indexOf('oauth-place'), 'app before place');
   assert.ok(keys.indexOf('oauth-place') < keys.indexOf('first-sign-in'), 'place before sign-in');
+  // The publish-credential install (task 1003049) needs the App to exist first and
+  // must be prompted before the owner walks away into the hall.
+  assert.ok(keys.indexOf('oauth-place') < keys.indexOf('app-install'), 'the App exists before it can be installed');
+  assert.ok(keys.indexOf('app-install') < keys.indexOf('first-sign-in'), 'install prompted before sign-in');
 });
 
 test('onboardPlan(adopt): same sequence + human steps, but the scaffold-leg labels branch (task 2046)', () => {

package/tests/provision.mjs

@@ -1044,11 +1044,27 @@ t('webEnvBody fills the OAuth cred lines when creds are given; blank placeholder
   const inst = { ...coTenant, domain: 'mercury.example.com' };
   const blank = P.webEnvBody(inst);
   assert.match(blank, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_GITHUB_CLIENT_ID=\\n`), 'blank id line by default');
+  assert.doesNotMatch(blank, /GITHUB_APP_ID=/, 'no App credential lines without an App');
   const filled = P.webEnvBody(inst, { clientId: 'Iv1.abc123def456ghi7', clientSecret: 's'.repeat(40) });
   assert.match(filled, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_GITHUB_CLIENT_ID=Iv1\\.abc123def456ghi7`));
   assert.match(filled, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_GITHUB_CLIENT_SECRET=s{40}`));
 });
 
+t('webEnvBody writes the BARE publish-credential vars, pem flattened to one env line (task 1003049)', () => {
+  const inst = { ...coTenant, domain: 'mercury.example.com' };
+  const body = P.webEnvBody(inst, {
+    clientId: 'Iv1.abc123def456ghi7', clientSecret: 's'.repeat(40),
+    appId: 42, appPem: '-----BEGIN KEY-----\nAAA\nBBB\n-----END KEY-----\n',
+  });
+  // BARE names (github-push.js reads process.env.GITHUB_APP_ID, no instance prefix)
+  assert.match(body, /^GITHUB_APP_ID=42$/m);
+  assert.match(body, /^GITHUB_APP_PRIVATE_KEY=-----BEGIN KEY-----\\nAAA\\nBBB\\n-----END KEY-----\\n$/m);
+  assert.doesNotMatch(body, /GITHUB_APP_INSTALLATION_ID/, 'installation id is discovered at runtime, never placed');
+  // pem missing (older Apps) → no half-written credential
+  const noPem = P.webEnvBody(inst, { clientId: 'Iv1.abc123def456ghi7', clientSecret: 's'.repeat(40), appId: 42, appPem: null });
+  assert.doesNotMatch(noPem, /GITHUB_APP_ID=/);
+});
+
 await ta('convertManifestCode POSTs the unauthenticated conversion endpoint + maps the response', async () => {
   let calledUrl = '', calledInit = null;
   const fetchImpl = async (url, init) => {
@@ -1060,7 +1076,16 @@ await ta('convertManifestCode POSTs the unauthenticated conversion endpoint + ma
   assert.equal(calledInit.method, 'POST');
   assert.ok(calledInit.headers['User-Agent'], 'stamps a User-Agent (GitHub requires one)');
   assert.ok(!('Authorization' in calledInit.headers), 'unauthenticated — the code IS the auth');
-  assert.deepEqual(creds, { clientId: 'Iv1.abcdef0123456789', clientSecret: 'x'.repeat(40), appId: 42, appSlug: 'mercury-signin' });
+  assert.deepEqual(creds, { clientId: 'Iv1.abcdef0123456789', clientSecret: 'x'.repeat(40), appId: 42, appSlug: 'mercury-signin', appPem: null });
+});
+
+await ta('convertManifestCode maps the App private key (pem) — the ADR 0055 publish credential (task 1003049)', async () => {
+  const pem = '-----BEGIN RSA PRIVATE KEY-----\nMIIkey\n-----END RSA PRIVATE KEY-----\n';
+  const fetchImpl = async () => ({ ok: true, text: async () => JSON.stringify({
+    id: 7, slug: 's', client_id: 'Iv1.abcdef0123456789', client_secret: 'x'.repeat(40), pem,
+  }) });
+  const creds = await P.convertManifestCode('C', { fetchImpl });
+  assert.equal(creds.appPem, pem, 'the pem rides the creds to web.env placement');
 });
 
 await ta('convertManifestCode throws on a non-2xx or a creds-less response', async () => {
@@ -1075,7 +1100,7 @@ await ta('placeManifestCreds (--apply): converts, rewrites web.env with the cred
   const writes = []; const cmds = [];
   const deps = {
     apply: true, privileged: false, log: () => {},
-    convertManifestCode: async () => ({ clientId: 'Iv1.abcdef0123456789', clientSecret: 'z'.repeat(40), appId: 9, appSlug: 'm-signin' }),
+    convertManifestCode: async () => ({ clientId: 'Iv1.abcdef0123456789', clientSecret: 'z'.repeat(40), appId: 9, appSlug: 'm-signin', appPem: '-----BEGIN KEY-----\nAAA\n-----END KEY-----\n' }),
     exec: (cmd) => { cmds.push(cmd); return { ok: true, stdout: '{"ok":true,"auth_configured":true}' }; },
     writeFile: (p, body) => { writes.push({ p, body }); return { ok: true }; },
   };
@@ -1086,6 +1111,9 @@ await ta('placeManifestCreds (--apply): converts, rewrites web.env with the cred
   const env = writes.find((w) => /web\.env$/.test(w.p));
   assert.ok(env, 'web.env was written');
   assert.match(env.body, /_GITHUB_CLIENT_SECRET=z{40}/);
+  // …and the publish credential (task 1003049): App id + one-line pem, bare names
+  assert.match(env.body, /^GITHUB_APP_ID=9$/m, 'the App id is placed as the publish credential');
+  assert.match(env.body, /^GITHUB_APP_PRIVATE_KEY=-----BEGIN KEY-----\\nAAA\\n-----END KEY-----\\n$/m, 'the pem is placed env-flattened');
   // the unit was restarted, and /healthz was probed
   assert.ok(cmds.some((c) => /systemctl restart mercury/.test(c)), 'restarts the unit');
   assert.ok(cmds.some((c) => /\/healthz/.test(c)), 'probes healthz');

package/tests/publish_branch_route.mjs

@@ -476,7 +476,7 @@ async function withEnv(vars, fn) {
 const APP_ENV = { GITHUB_APP_ID: '123', GITHUB_APP_INSTALLATION_ID: '456', GITHUB_APP_PRIVATE_KEY: APP_PRIVKEY };
 const NO_APP = { GITHUB_APP_ID: undefined, GITHUB_APP_INSTALLATION_ID: undefined, GITHUB_APP_PRIVATE_KEY: undefined };
 
-await t('appConfigured / isConfigured: true only with App (all 3 vars) or PAT', async () => {
+await t('appConfigured / isConfigured: true with App (id + key; installation id optional) or PAT', async () => {
   await withEnv({ ...NO_APP, GITHUB_PUSH_TOKEN: undefined }, async () => {
     assert.equal(gp.appConfigured(), false);
     assert.equal(gp.isConfigured(), false);
@@ -490,7 +490,11 @@ await t('appConfigured / isConfigured: true only with App (all 3 vars) or PAT',
     assert.equal(gp.isConfigured(), true, 'App alone configures it');
   });
   await withEnv({ GITHUB_APP_ID: '123', GITHUB_APP_INSTALLATION_ID: undefined, GITHUB_APP_PRIVATE_KEY: APP_PRIVKEY, GITHUB_PUSH_TOKEN: undefined }, async () => {
-    assert.equal(gp.appConfigured(), false, 'partial App config (no installation id) is NOT configured');
+    assert.equal(gp.appConfigured(), true, 'id + key ARE enough — the installation id is discovered from the repo (task 1003049)');
+    assert.equal(gp.isConfigured(), true);
+  });
+  await withEnv({ GITHUB_APP_ID: '123', GITHUB_APP_INSTALLATION_ID: '456', GITHUB_APP_PRIVATE_KEY: undefined, GITHUB_PUSH_TOKEN: undefined }, async () => {
+    assert.equal(gp.appConfigured(), false, 'no private key → not configured');
     assert.equal(gp.isConfigured(), false);
   });
 });
@@ -548,6 +552,153 @@ await t('getInstallationToken: App configured but the exchange fails → APP_TOK
   });
 });
 
+// task 1003049 — a manifest-born instance knows its App id + key at cred-placement
+// time but never the installation id: that only exists after the owner's one-click
+// install. The server derives it live instead of demanding a third env var.
+const APP_ENV_NO_INST = { GITHUB_APP_ID: '123', GITHUB_APP_INSTALLATION_ID: undefined, GITHUB_APP_PRIVATE_KEY: APP_PRIVKEY };
+
+await t('getInstallationToken: no installation id in env → discovers it from the repo, then mints (task 1003049)', async () => {
+  await withEnv({ ...APP_ENV_NO_INST, GITHUB_PUSH_TOKEN: undefined }, async () => {
+    const urls = [];
+    const fetchImpl = async (url, opts = {}) => {
+      urls.push(url);
+      if (url.endsWith('/repos/someowner/somerepo/installation')) {
+        const authz = opts.headers.Authorization;
+        assert.ok(/^Bearer /.test(authz) && jwtSignatureVerifies(authz.slice(7), APP_PUBKEY), 'discovery authenticates with a valid App JWT');
+        return jsonRes(200, { id: 789 });
+      }
+      if (url.includes('/app/installations/789/access_tokens')) {
+        return jsonRes(201, { token: 'ghs_discovered', expires_at: '2999-01-01T00:00:00Z' });
+      }
+      throw new Error('unexpected ' + url);
+    };
+    const now = () => 1_700_000_000 * 1000;
+    const tok = await gp.getInstallationToken({ fetchImpl, now, repoInfo: REPO });
+    assert.equal(tok, 'ghs_discovered');
+    assert.ok(urls.some((u) => u.endsWith('/repos/someowner/somerepo/installation')), 'looked the installation up on the repo');
+  });
+});
+
+await t('getInstallationToken: env GITHUB_APP_INSTALLATION_ID still wins — no discovery call (the ADR 0055 v1 shape)', async () => {
+  await withEnv({ ...APP_ENV, GITHUB_PUSH_TOKEN: undefined }, async () => {
+    const fetchImpl = async (url) => {
+      if (url.endsWith('/installation')) throw new Error('must not discover when the env id is set');
+      return jsonRes(201, { token: 'ghs_env', expires_at: '2999-01-01T00:00:00Z' });
+    };
+    assert.equal(await gp.getInstallationToken({ fetchImpl, now: () => 1_700_000_000 * 1000, repoInfo: REPO }), 'ghs_env');
+  });
+});
+
+await t('getInstallationToken: App not installed on the repo → APP_NOT_INSTALLED carrying the install URL (task 1003049)', async () => {
+  await withEnv({ ...APP_ENV_NO_INST, GITHUB_PUSH_TOKEN: undefined }, async () => {
+    const fetchImpl = async (url) => {
+      if (url.endsWith('/repos/someowner/somerepo/installation')) return jsonRes(404, { message: 'Not Found' });
+      if (url.endsWith('api.github.com/app')) return jsonRes(200, { html_url: 'https://github.com/apps/mercury-signin' });
+      throw new Error('unexpected ' + url);
+    };
+    await assert.rejects(
+      () => gp.getInstallationToken({ fetchImpl, now: () => 1_700_000_000 * 1000, repoInfo: REPO }),
+      (e) => e.code === 'APP_NOT_INSTALLED'
+        && e.owner === 'someowner' && e.repo === 'somerepo'
+        && e.install_url === 'https://github.com/apps/mercury-signin/installations/new',
+      'names the repo + the one-click install URL so the refusal is self-serve'
+    );
+  });
+});
+
+await t('discoverInstallationId: APP_NOT_INSTALLED is negative-cached for a short TTL (no per-poll re-probe)', async () => {
+  await withEnv({ ...APP_ENV_NO_INST, GITHUB_PUSH_TOKEN: undefined }, async () => {
+    let probes = 0;
+    const fetchImpl = async (url) => {
+      if (url.endsWith('/repos/someowner/somerepo/installation')) { probes++; return jsonRes(404, {}); }
+      if (url.endsWith('api.github.com/app')) return jsonRes(200, { html_url: 'https://github.com/apps/x' });
+      throw new Error('unexpected ' + url);
+    };
+    let nowMs = 1_700_000_000 * 1000;
+    const now = () => nowMs;
+    const call = () => gp.getInstallationToken({ fetchImpl, now, repoInfo: REPO });
+    await assert.rejects(call, (e) => e.code === 'APP_NOT_INSTALLED');
+    await assert.rejects(call, (e) => e.code === 'APP_NOT_INSTALLED');
+    assert.equal(probes, 1, 'the second poll inside the TTL reuses the cached refusal');
+    nowMs += 61_000;
+    await assert.rejects(call, (e) => e.code === 'APP_NOT_INSTALLED');
+    assert.equal(probes, 2, 'after the TTL the state is re-probed (an install must be noticed)');
+  });
+});
+
+await t('getInstallationToken: a stale DISCOVERED id is dropped on exchange failure — next call re-discovers (no restart needed)', async () => {
+  await withEnv({ ...APP_ENV_NO_INST, GITHUB_PUSH_TOKEN: undefined }, async () => {
+    let discoveries = 0, exchanges = 0;
+    const fetchImpl = async (url) => {
+      if (url.endsWith('/repos/someowner/somerepo/installation')) {
+        discoveries++;
+        return jsonRes(200, { id: discoveries === 1 ? 111 : 222 });
+      }
+      if (url.includes('/access_tokens')) {
+        exchanges++;
+        // the first (stale) id fails the exchange; the re-discovered one works
+        if (url.includes('/111/')) return jsonRes(404, { message: 'gone (uninstalled+reinstalled)' });
+        return jsonRes(201, { token: 'ghs_fresh', expires_at: '2999-01-01T00:00:00Z' });
+      }
+      throw new Error('unexpected ' + url);
+    };
+    const now = () => 1_700_000_000 * 1000;
+    await assert.rejects(
+      () => gp.getInstallationToken({ fetchImpl, now, repoInfo: REPO }),
+      (e) => e.code === 'APP_TOKEN_FAILED'
+    );
+    assert.equal(await gp.getInstallationToken({ fetchImpl, now, repoInfo: REPO }), 'ghs_fresh',
+      'the stale id was dropped and re-discovery healed the exchange');
+    assert.equal(discoveries, 2);
+    assert.equal(exchanges, 2);
+  });
+});
+
+await t('foreignInstallations: installs beyond the repo owner are surfaced; own install is not; API miss → null (task 1003049 grade)', async () => {
+  await withEnv({ ...APP_ENV_NO_INST, GITHUB_PUSH_TOKEN: undefined }, async () => {
+    const roster = [
+      { id: 1, account: { login: 'SomeOwner' } },   // own (case-insensitive)
+      { id: 2, account: { login: 'stranger' } },
+      { id: 3, account: { login: 'another-org' } },
+    ];
+    const fetchImpl = async (url) => {
+      if (url.includes('/app/installations?')) return jsonRes(200, roster);
+      throw new Error('unexpected ' + url);
+    };
+    const foreign = await gp.foreignInstallations({ fetchImpl, now: () => 1_700_000_000 * 1000, repoInfo: REPO });
+    assert.deepEqual(foreign.map((f) => f.account).sort(), ['another-org', 'stranger']);
+    const miss = await gp.foreignInstallations({ fetchImpl: async () => jsonRes(500, {}), now: () => 1_700_000_000 * 1000, repoInfo: REPO });
+    assert.equal(miss, null, 'a watch that cannot tell says null, never a fake all-clear');
+  });
+  await withEnv({ ...NO_APP, GITHUB_PUSH_TOKEN: undefined }, async () => {
+    assert.equal(await gp.foreignInstallations({ fetchImpl: async () => { throw new Error('no'); } }), null,
+      'unconfigured App → null');
+  });
+});
+
+await t('GET /tasks/:id/publish-status with no credential → a plain-sentence 503, not a bare code (task 1003049)', async () => {
+  await withEnv({ ...NO_APP, GITHUB_PUSH_TOKEN: undefined }, async () => {
+    const router = buildTasksRouter();
+    const layer = findRouteLayer(router, '/tasks/:id/publish-status', 'get');
+    const handler = layer.route.stack[layer.route.stack.length - 1].handle;
+    const out = { failCode: null, failOpts: null };
+    const res = {
+      status() { return this; },
+      json() { return this; },
+      fail(code, opts) { out.failCode = code; out.failOpts = opts; return this; },
+    };
+    // rank archon → gateTaskOwnership passes with no DB lookup, keeping the test hermetic.
+    const req = { params: { id: '77' }, query: { branch: 'claude/x' }, builder: { id: 95, rank: 'archon' } };
+    await handler(req, res);
+    assert.equal(out.failCode, 'push_unconfigured');
+    assert.equal(out.failOpts && out.failOpts.status, 503);
+    const msg = String((out.failOpts && out.failOpts.message) || '');
+    assert.match(msg, /publish credential/i, 'says WHAT is missing in a sentence');
+    assert.match(msg, /GitHub App/, 'says what to set up');
+    assert.match(msg, /GITHUB_PUSH_TOKEN/, 'names the PAT alternative');
+  });
+});
+
 await t('resolveToken precedence: deps.token > App installation token > PAT > null', async () => {
   await withEnv({ ...APP_ENV, GITHUB_PUSH_TOKEN: 'pat' }, async () => {
     assert.equal(