@bongos/core 1.21.92 → 1.21.94

package/modules/autonomy/routes/autonomy.js

@@ -155,6 +155,15 @@ module.exports = function buildAutonomyRouter() {
     }
   });
 
+  // WHO DECIDES AT AUTOMATION (task 1004657; ADR 0363 D5). While the project's
+  // decision-rules row hands Automation to a sitting, these writes refuse one
+  // builder acting alone (409 decided_by_sitting) and point at the matter route;
+  // a passed matter acts through matter-acts.js, never through these routes.
+  // The BRAKE is exempt: switching unattended building off, or pausing one
+  // runner, never waits for a meeting — stopping can only narrow what runs.
+  const isTheBrake = (req) => !!req.body && req.body.enabled === false;
+  const isAPause = (req) => !!req.body && req.body.paused === true;
+
   // ── the Autobongos fence (task 1003908, ADR 0307 §6) ───────────────────────
   //
   // These five routes ARE the fence. Everything the unattended runner is allowed
@@ -195,7 +204,7 @@ module.exports = function buildAutonomyRouter() {
 
   // The kill switch. Archon, system:true — see the catalog entry for why it is the
   // one permission that cannot be delegated to a custom rank.
-  router.post('/autonomy/fence', auth.requireBuilder, auth.requirePermission('autonomy.fence.manage'), async (req, res) => {
+  router.post('/autonomy/fence', auth.requireBuilder, auth.requirePermission('autonomy.fence.manage'), auth.requireActAlone('automation', { unless: isTheBrake }), async (req, res) => {
     if (validateOrRespond(req, res, {
       enabled: { required: true, type: 'boolean' },
       reason: { type: 'string', maxLength: 500 },
@@ -217,7 +226,7 @@ module.exports = function buildAutonomyRouter() {
   });
 
   // Add a goal to the allowlist.
-  router.post('/autonomy/fence/goals', auth.requireBuilder, auth.requirePermission('autonomy.fence.manage'), async (req, res) => {
+  router.post('/autonomy/fence/goals', auth.requireBuilder, auth.requirePermission('autonomy.fence.manage'), auth.requireActAlone('automation'), async (req, res) => {
     if (validateOrRespond(req, res, {
       goal_id: { required: true },   // number or stringified number; coerced below
       note: { type: 'string', maxLength: 500 },
@@ -237,7 +246,7 @@ module.exports = function buildAutonomyRouter() {
 
   // Revoke one. `removed` distinguishes "just revoked" from "already gone" — an
   // owner clicking Remove deserves to know which happened.
-  router.delete('/autonomy/fence/goals/:goalId', auth.requireBuilder, auth.requirePermission('autonomy.fence.manage'), async (req, res) => {
+  router.delete('/autonomy/fence/goals/:goalId', auth.requireBuilder, auth.requirePermission('autonomy.fence.manage'), auth.requireActAlone('automation'), async (req, res) => {
     const goalId = Number(req.params.goalId);
     if (!Number.isSafeInteger(goalId) || goalId <= 0) return res.fail('bad_goal_id', 400);
     try {
@@ -255,7 +264,7 @@ module.exports = function buildAutonomyRouter() {
   // first is part of choosing what it may do. The goal must already be on the
   // allowlist (409 otherwise), so a priority can order the list and never widen
   // it. `goal_id: null` clears it.
-  router.post('/autonomy/fence/priority', auth.requireBuilder, auth.requirePermission('autonomy.fence.manage'), async (req, res) => {
+  router.post('/autonomy/fence/priority', auth.requireBuilder, auth.requirePermission('autonomy.fence.manage'), auth.requireActAlone('automation'), async (req, res) => {
     // Declared with an open rule: the value is a number OR null, which the
     // validator has no type for, so the shape is checked just below.
     if (validateOrRespond(req, res, { goal_id: {} })) return;
@@ -302,7 +311,7 @@ module.exports = function buildAutonomyRouter() {
   // switch. Same atom as the kill switch: stopping a machine is the same act
   // whether it is everyone's or one person's, and the paused builder must not be
   // able to lift it (autonomy.run does not reach this route).
-  router.post('/autonomy/builders/:builderId/pause', auth.requireBuilder, auth.requirePermission('autonomy.fence.manage'), async (req, res) => {
+  router.post('/autonomy/builders/:builderId/pause', auth.requireBuilder, auth.requirePermission('autonomy.fence.manage'), auth.requireActAlone('automation', { unless: isAPause }), async (req, res) => {
     if (validateOrRespond(req, res, {
       paused: { required: true, type: 'boolean' },
       reason: { type: 'string', maxLength: 500 },

package/modules/government/decision-board.js

@@ -286,13 +286,23 @@ async function openMatter({ area, title, detailMd = null, action = null, propose
 }
 
 // May this builder act ALONE at this building — the check a building's own
-// direct route runs before acting (People's rank assignments today). Resolved
+// direct route runs before acting (People's rank assignments here; every other
+// building's routes through the doorway's requireActAlone, task 1004657 — the
+// list is decision-rules AREAS[].acts). Resolved
 // per request against the live row and the builder's live ranks, uncached.
 // Returns { ok: true } or { ok: false, reason: 'decided_by_sitting', … }.
+//
+// HOT PATH since task 1004657: ~30 write routes across the modules mount this
+// through requireActAlone, so it does ONE query and no file I/O. The board block
+// (loadGovernmentConfig — two synchronous file reads, boot-only by config.js's own
+// rule) only ever shapes the CHARTER row's rule and words, and no direct route
+// asks about the charter; every other building's row reads the same without it.
 async function checkActAlone(area, builderId) {
-  const { board } = loadGovernmentConfig();
+  if (!decisionRules.AREA_KEYS.includes(area)) return { ok: false, reason: 'unknown_area' };
   const rows = await db.listDecisionRules();
-  const resolved = decisionRules.resolveAll(rows, { board }).find((r) => r.area === area);
+  const board = area === 'charter' ? loadGovernmentConfig().board : {};
+  const stored = (rows || []).find((r) => r.area === area) || decisionRules.defaultRow(area);
+  const resolved = decisionRules.resolveRow(stored, { board });
   if (!resolved) return { ok: false, reason: 'unknown_area' };
   if (resolved.as_today) return { ok: true, decided: resolved };
   const seated = resolved.sitting

package/modules/government/decision-rules.js

@@ -44,30 +44,77 @@ const { RANK_ORDER } = require('./catalog');
 // The nine buildings, in street order (held equal to docket-vocab BUILDINGS by
 // test). `gate` is the fixed permission that decides the building's matters
 // today — the atom its own pages require, named so a reader can see what a
-// sitting replaces. `acts` lists the direct acts in THIS module that already
-// defer to the row (task 1004529 wired People's rank assignments); every other
-// building's own pages keep their gate until their owning module adopts
-// `mayActAlone` (the ADR's follow-up list).
+// sitting replaces. `acts` is THE RECORD of every direct route that defers to
+// the building's row: while the row names a sitting, each refuses one builder
+// acting alone (409 decided_by_sitting) and points at the matter route. People's
+// rank assignments ask in this module (task 1004529); every other route mounts
+// the doorway's requireActAlone(area) after its permission gate (task 1004657).
+// tests/government_act_alone_buildings.mjs reads this list against the source
+// both ways, so a route cannot defer without being listed, or be listed without
+// deferring. Which routes are a building's: those gated by its `gate` atom,
+// plus the routes its passed matters act through (decision-board MATTER_ACTIONS)
+// and its docket desks reach. A building with no direct route says so in
+// `no_direct_route` — the charter, whose only act is an amendment.
+// NOT a lone act, so never refused: a BRAKE (switching unattended building off,
+// pausing one runner — stopping never waits for a meeting), a dry run, and a
+// tenant project's own owner moving their own pin (that project's decision).
 const AREAS = Object.freeze([
   Object.freeze({ key: 'charter', name: 'Charter', gate: null,
-    today: 'the board, under the constitution in force', acts: Object.freeze([]) }),
+    today: 'the board, under the constitution in force', acts: Object.freeze([]),
+    no_direct_route: 'the charter is changed only by amending the constitution — POST /government/board/items or /government/board/charter' }),
   Object.freeze({ key: 'rules', name: 'Rules', gate: 'project.settings.manage',
-    today: 'whoever may change the project settings', acts: Object.freeze([]) }),
+    today: 'whoever may change the project settings', acts: Object.freeze([
+      'PATCH /project-settings/rot-days',
+      'PATCH /project-settings/ship-mode',
+      'PATCH /work-categories/:id',
+    ]) }),
   Object.freeze({ key: 'disputes', name: 'Disputes', gate: 'security.report.adjudicate',
-    today: 'whoever may judge reports', acts: Object.freeze([]) }),
+    today: 'whoever may judge reports', acts: Object.freeze([
+      'POST /security/reports/:id/confirm',
+      'POST /security/reports/:id/dispute',
+      'POST /security/reports/:id/fix',
+    ]) }),
   Object.freeze({ key: 'people', name: 'People', gate: 'government.manage',
     today: 'whoever may manage ranks',
-    acts: Object.freeze(['POST /government/assignments', 'DELETE /government/assignments/:builderId/:rankKey']) }),
+    acts: Object.freeze([
+      'POST /government/assignments',
+      'DELETE /government/assignments/:builderId/:rankKey',
+      'PATCH /access-requests/:id',
+      'POST /access-requests/invite',
+    ]) }),
   Object.freeze({ key: 'planning', name: 'Planning', gate: 'goal.create',
-    today: 'whoever may create goals', acts: Object.freeze([]) }),
+    today: 'whoever may create goals', acts: Object.freeze([
+      'POST /goals',
+      'POST /goals/reorder',
+      'POST /work-categories',
+      'PUT /versions/focus',
+    ]) }),
   Object.freeze({ key: 'automation', name: 'Automation', gate: 'autonomy.fence.manage',
-    today: 'whoever may switch unattended building on and off', acts: Object.freeze([]) }),
+    today: 'whoever may switch unattended building on and off', acts: Object.freeze([
+      'POST /autonomy/fence',
+      'POST /autonomy/fence/goals',
+      'DELETE /autonomy/fence/goals/:goalId',
+      'POST /autonomy/fence/priority',
+      'POST /autonomy/builders/:builderId/pause',
+    ]) }),
   Object.freeze({ key: 'review', name: 'Review', gate: 'criterion.satisfy',
-    today: 'whoever may mark work as meeting its checks', acts: Object.freeze([]) }),
+    today: 'whoever may mark work as meeting its checks', acts: Object.freeze([
+      'POST /done-when/:criterionId/satisfy',
+      'POST /done-when/:criterionId/unsatisfy',
+    ]) }),
   Object.freeze({ key: 'release', name: 'Release', gate: 'core.pin.move',
-    today: 'whoever may put a release live', acts: Object.freeze([]) }),
+    today: 'whoever may put a release live', acts: Object.freeze([
+      'POST /gate-approvals/:pr/approve',
+      'POST /override-requests/:id/decide',
+      'POST /provisioning/instances/:id/core-upgrade',
+      'POST /provisioning/instances/:id/update-channel',
+      'POST /render-deploy/act',
+      'POST /npm-release/release',
+    ]) }),
   Object.freeze({ key: 'treasury', name: 'Treasury', gate: 'builder.budget.set',
-    today: 'whoever may set spending limits', acts: Object.freeze([]) }),
+    today: 'whoever may set spending limits', acts: Object.freeze([
+      'PATCH /builders/:id/budget',
+    ]) }),
 ]);
 const AREA_KEYS = Object.freeze(AREAS.map((a) => a.key));
 const areaByKey = (key) => AREAS.find((a) => a.key === key) || null;
@@ -245,6 +292,7 @@ function resolveRow(stored, { board = {} } = {}) {
     gate: def.gate,
     today: def.today,
     acts: def.acts,
+    no_direct_route: def.no_direct_route || null,
     set_by_item_id: row.set_by_item_id == null ? null : String(row.set_by_item_id),
     updated_at: row.updated_at || null,
   });

package/modules/lifecycle/routes/done-when.js

@@ -248,7 +248,7 @@ module.exports = function buildDoneWhenRouter() {
   // everywhere — never as a UAT. The escape hatch stays (an all-abandoned
   // criterion that was met another way still needs one); it is just no longer
   // silent.
-  router.post('/done-when/:criterionId/satisfy', auth.requireBuilder, auth.requirePermission('criterion.satisfy'), asyncHandler('POST /done-when/:criterionId/satisfy', async (req, res) => {
+  router.post('/done-when/:criterionId/satisfy', auth.requireBuilder, auth.requirePermission('criterion.satisfy'), auth.requireActAlone('review'), asyncHandler('POST /done-when/:criterionId/satisfy', async (req, res) => {
     if (validateOrRespond(req, res, {
       satisfied_by_task_id: { type: 'integer', min: 1 },
       override_reason: { type: 'string', maxLength: 2000 },
@@ -476,7 +476,7 @@ module.exports = function buildDoneWhenRouter() {
   // rank: archon — un-flip a criterion; same gate as satisfy.
   // An optional `reason` (the Review desk's one-tap chip, task 1004561) is
   // logged beside who undid it; the flip itself is unchanged.
-  router.post('/done-when/:criterionId/unsatisfy', auth.requireBuilder, auth.requirePermission('criterion.unsatisfy'), asyncHandler('POST /done-when/:criterionId/unsatisfy', async (req, res) => {
+  router.post('/done-when/:criterionId/unsatisfy', auth.requireBuilder, auth.requirePermission('criterion.unsatisfy'), auth.requireActAlone('review'), asyncHandler('POST /done-when/:criterionId/unsatisfy', async (req, res) => {
     if (validateOrRespond(req, res, { reason: { type: 'string', maxLength: 200 } })) return;
     const id = parseId(req, res, { param: 'criterionId', code: 'bad_criterion_id' });
     if (id === null) return;

package/modules/lifecycle/routes/gate-approvals.js

@@ -255,7 +255,7 @@ module.exports = function buildGateApprovalsRouter() {
   // POST /gate-approvals/:pr/approve — record owner approval for a stuck gate PR and
   // re-run the gate-review check so it clears. rank: archon (clears the hard floor —
   // pinned in route-rank-check.EXPECTED_RANKS for downgrade protection).
-  router.post('/gate-approvals/:pr/approve', auth.requireBuilder, auth.requirePermission('gate_approval.decide'), async (req, res) => {
+  router.post('/gate-approvals/:pr/approve', auth.requireBuilder, auth.requirePermission('gate_approval.decide'), auth.requireActAlone('release'), async (req, res) => {
     const number = parseId(req, res, { param: 'pr', code: 'bad_pr', positiveInt: true });
     if (number == null) return;
     try {

package/modules/lifecycle/routes/goals.js

@@ -83,7 +83,7 @@ module.exports = function buildGoalsRouter() {
   // POST /goals — create a goal.
   // rank: metic+archon — a Metic or Archon may create a goal; creation of a goal
   // whose scope_modules includes a PROTECTED module is Archon-only (in-handler).
-  router.post('/goals', auth.requireBuilder, auth.requirePermission('goal.create'), async (req, res) => {
+  router.post('/goals', auth.requireBuilder, auth.requirePermission('goal.create'), auth.requireActAlone('planning'), async (req, res) => {
     if (validateOrRespond(req, res, {
       version_id: { required: true, type: 'string', minLength: 1, maxLength: 64 },
       title: { required: true, type: 'string', minLength: 1, maxLength: LIMITS.TITLE },
@@ -239,7 +239,7 @@ module.exports = function buildGoalsRouter() {
   // Mounted BEFORE GET /goals/:id so 'reorder' is never captured as an id.
   // rank: archon — priority is an owner decision, never self-granted by a
   // goal's own member/manager (unlike the goal-authority routes above).
-  router.post('/goals/reorder', auth.requireBuilder, auth.requirePermission('goal.reorder'), async (req, res) => {
+  router.post('/goals/reorder', auth.requireBuilder, auth.requirePermission('goal.reorder'), auth.requireActAlone('planning'), async (req, res) => {
     if (validateOrRespond(req, res, {
       version_id: { required: true, type: 'string', minLength: 1, maxLength: 64 },
       ordered_ids: { required: true, type: 'array', maxItems: 500, itemsType: 'integer' },
@@ -425,7 +425,7 @@ module.exports = function buildGoalsRouter() {
   // prompt writes into. Same permission as authoring a goal: extending the project's
   // vocabulary is a planning act. A duplicate slug returns the existing row (200),
   // so two people prompted at once converge instead of one being stranded.
-  router.post('/work-categories', auth.requireBuilder, auth.requirePermission('goal.create'),
+  router.post('/work-categories', auth.requireBuilder, auth.requirePermission('goal.create'), auth.requireActAlone('planning'),
     goalCategory.categoryCreateHandler({ validateOrRespond, LIMITS, log }));
   // PATCH /work-categories/:id — body { label?, sort_order?, active? }: rename a
   // category, move it in the order, or stop offering it. The set has been list+add
@@ -440,7 +440,7 @@ module.exports = function buildGoalsRouter() {
   // /goal-create prompt refer to. Deactivating never deletes — goals already carrying
   // a retired category keep a resolvable label.
   router.patch('/work-categories/:id', auth.requireBuilder,
-    auth.requirePermission('project.settings.manage'),
+    auth.requirePermission('project.settings.manage'), auth.requireActAlone('rules'),
     goalCategory.categoryUpdateHandler({ validateOrRespond, LIMITS, parseId, log }));
 
   // PATCH /goals/:id/category — body { category_id } (null clears it). Separate from

package/modules/lifecycle/routes/project-settings.js

@@ -313,7 +313,7 @@ module.exports = function buildProjectSettingsRouter() {
   // first and fitness.js caught it; that is why every gated route in the tree spells
   // its atom inline. (Wrapping the middleware list across lines is fine — the sibling
   // PATCH /work-categories/:id does exactly that and still classifies metic+archon.)
-  router.patch('/project-settings/rot-days', api.requireBuilder, api.requirePermission('project.settings.manage'), async (req, res) => {
+  router.patch('/project-settings/rot-days', api.requireBuilder, api.requirePermission('project.settings.manage'), api.requireActAlone('rules'), async (req, res) => {
       // STRICT schema first (ADR 0118): it declares the only field this handler reads,
       // so an unknown key is refused through the ADR 0116 envelope instead of being
       // silently dropped. It settles the TYPE; parseDays below settles the RANGE, using
@@ -364,7 +364,7 @@ module.exports = function buildProjectSettingsRouter() {
   // rank: project.settings.manage (metic+, government_010) — the same atom as the
   // other writes on this page. Validated with the resolver's own parser, so the
   // page, the CLI and the reader can never disagree about what a mode is.
-  router.patch('/project-settings/ship-mode', api.requireBuilder, api.requirePermission('project.settings.manage'), async (req, res) => {
+  router.patch('/project-settings/ship-mode', api.requireBuilder, api.requirePermission('project.settings.manage'), api.requireActAlone('rules'), async (req, res) => {
     if (api.validateOrRespond(req, res, { mode: { required: true, type: 'string' } })) return;
     const parsed = api.projectSettings.parseShipMode(req.body.mode);
     if (!parsed.mode) {

package/modules/lifecycle/routes/tasks.js

@@ -1437,7 +1437,7 @@ module.exports = function buildTasksRouter() {
   // caller; this route only renders its refusal (403 override_owner_only).
   // Approving one confirms nothing and pays nothing — it stops the review holding
   // the DEPLOY and leaves it open on the board.
-  router.post('/override-requests/:id/decide', auth.requireBuilder, auth.requirePermission('override_request.decide'), async (req, res) => {
+  router.post('/override-requests/:id/decide', auth.requireBuilder, auth.requirePermission('override_request.decide'), auth.requireActAlone('release'), async (req, res) => {
     const id = parseId(req, res, { code: 'bad_request_id' });
     if (id === null) return;
     if (validateOrRespond(req, res, {

package/modules/lifecycle/routes/versions.js

@@ -56,7 +56,7 @@ module.exports = function buildVersionsRouter() {
 
   // rank: archon (atom version.focus.set, system) — body { version_id } sets the focus; { version_id: null } clears it.
   // An unknown version id is refused rather than stored.
-  router.put('/versions/focus', auth.requireBuilder, auth.requirePermission('version.focus.set'), asyncHandler('PUT /versions/focus', async (req, res) => {
+  router.put('/versions/focus', auth.requireBuilder, auth.requirePermission('version.focus.set'), auth.requireActAlone('planning'), asyncHandler('PUT /versions/focus', async (req, res) => {
     if (validateOrRespond(req, res, { version_id: { type: 'string', maxLength: 64 } })) return;
     const raw = (req.body || {}).version_id;
     if (raw === undefined || (raw !== null && !raw.trim())) return res.fail('bad_version_id', { status: 400, message: 'Pick a version to star, or send null to clear the focus.' });

package/modules/npm-release/routes/release.js

@@ -36,6 +36,7 @@ module.exports = function buildNpmReleaseReleaseRouter({
     '/npm-release/release',
     api.requireBuilder,
     api.requirePermission('core.pin.move'),
+    api.requireActAlone('release'),
     async (req, res) => {
       if (api.validateOrRespond(req, res, releaseSchema, { strict: true })) return undefined;
       if (!VERSION_RE.test(req.body.version)) {

package/modules/onboarding/routes/access-requests.js

@@ -58,7 +58,7 @@ const express = require('express');
 // core file a module may require, ADR 0083); approval-broadcast travels WITH this
 // admission route (its sole consumer) and is an intra-module require.
 const api = require('../../../src/module-api');
-const auth = { requireBuilder: api.requireBuilder, requirePermission: api.requirePermission };
+const auth = { requireBuilder: api.requireBuilder, requirePermission: api.requirePermission, requireActAlone: api.requireActAlone };
 const { pool } = api;
 const { validateOrRespond, parseId, accountExistenceReadRateLimit } = api;
 // A recruit invite's door closes 30 days after it is sent, computed at read time
@@ -486,7 +486,7 @@ module.exports = function buildAccessRequestsRouter() {
   // the SET value. Postgres infers text from the assignment anyway, but no real
   // engine ever executes this statement — there is no integration test for this
   // route and CI has no Postgres — so the type is stated rather than relied on.
-  router.patch('/access-requests/:id', auth.requireBuilder, auth.requirePermission('access_request.review'), async (req, res) => {
+  router.patch('/access-requests/:id', auth.requireBuilder, auth.requirePermission('access_request.review'), auth.requireActAlone('people'), async (req, res) => {
     const id = parseId(req, res, { code: 'bad_request_id' });
     if (id === null) return;
     if (validateOrRespond(req, res, {
@@ -567,7 +567,7 @@ module.exports = function buildAccessRequestsRouter() {
   // pending request was resolved; 200 already_invited when an invite already
   // stands; 409 already_member when they have an account.
   // rank: archon — the same gate as resolving a request.
-  router.post('/access-requests/invite', auth.requireBuilder, auth.requirePermission('access_request.review'), async (req, res) => {
+  router.post('/access-requests/invite', auth.requireBuilder, auth.requirePermission('access_request.review'), auth.requireActAlone('people'), async (req, res) => {
     if (validateOrRespond(req, res, {
       github_login: { required: true, type: 'string', minLength: 1, maxLength: 60 },
       note: { type: 'string', maxLength: 500 },

package/modules/provisioning/github-setup.js

@@ -0,0 +1,129 @@
+'use strict';
+
+// modules/provisioning/github-setup.js — "Connect GitHub" in one trip, and the checklist
+// that ticks itself (task 1004649; the design of record is docs/design/mocks/day-night-rooms/
+// part 03: Approve the <name> app on GitHub · Install it on your repo · Builders can sign in ·
+// Command-line sign-in is on).
+//
+// WHY. A founder used to make three separate trips to github.com after Create (approve the
+// app, tick "Enable Device Flow", install the app on the repo), and nothing ever checked the
+// last two. Now the manifest carries a setup_url, so GitHub sends the founder from "app
+// created" straight on to "install it on your repo" and then back to the project page — and
+// every tick on the checklist is a fact the SERVER has seen, never a click the page assumed:
+//
+//   approve  — GitHub created the app AND the runner placed its credentials (the runner
+//              records the app's slug only after the placement write, provision.js).
+//   install  — the runner, holding the app's own key, asked GitHub whether the app is
+//              installed on the project's repo and GitHub said yes ('github-app-installed').
+//              The installation_id GitHub appends to the setup_url is NOT trusted: GitHub's
+//              docs warn it can be spoofed, so that redirect only records that the founder
+//              SAYS they installed it ('github-app-install-reported'), which makes the
+//              runner look again.
+//   sign_in  — the runner saw the project report auth_configured (the manifest row 'done').
+//   device   — the runner started a device-flow sign-in with the app's client id and GitHub
+//              did not refuse it with device_flow_disabled ('github-app-device-flow').
+//              GitHub offers no manifest field and no API to switch device flow on (the
+//              spike in this task, written up in docs/design/project-startup-direction.md),
+//              so this step is OPTIONAL: it reads 'later' until the founder ticks the box on
+//              GitHub, and it never holds the project back from being alive.
+//
+// No new columns (ADR 0083 §5 additive rule; this task carries no migration): the verified
+// facts are rows of the existing append-only provisioning_events ledger, read since the
+// latest attempt began. The db is injected.
+
+// The provisioning_events names this leg writes. One table, so the runner (which writes the
+// verified ones), the setup redirect (which writes the reported one) and the reader agree.
+const SETUP_EVENTS = Object.freeze({
+  installReported: 'github-app-install-reported',
+  installed: 'github-app-installed',
+  deviceFlow: 'github-app-device-flow',
+});
+
+// How long after an attempt settles the runner keeps checking for the install and the
+// device-flow tick. Past it the checklist stops promising a self-tick for device flow
+// (the step says "turn it on later"); a fresh install report re-opens the window.
+const VERIFY_WINDOW_MS = 2 * 60 * 60 * 1000;
+
+// The one-trip install page for the app GitHub just created, carrying the attempt's state
+// so GitHub hands it back on the setup_url redirect. null until the app's slug is known.
+// PURE. (The callback page narrows it to the repo with /permissions?suggested_target_id
+// when it can learn the numeric ids — see callback-page.js.)
+function installUrlFor({ appSlug, state } = {}) {
+  if (!appSlug) return null;
+  const q = state ? `?state=${encodeURIComponent(state)}` : '';
+  return `https://github.com/apps/${encodeURIComponent(appSlug)}/installations/new${q}`;
+}
+
+// owner/repo from the instance's target_ref, or null. Strict — this string reaches a
+// public read and the callback page's GitHub lookup.
+const REPO_REF_RE = /^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9._-]{1,100}$/;
+function targetRepo(inst) {
+  const ref = String((inst && inst.target_ref) || '').trim().replace(/\.git$/, '');
+  return REPO_REF_RE.test(ref) ? ref : null;
+}
+
+// The verified facts for one instance since `since` (the attempt's created_at): when each
+// setup event was first seen, or null. One indexed read (idx_provisioning_events_instance).
+async function githubSetupFacts(db, instanceId, since) {
+  const { rows } = await db.query(
+    `SELECT event, min(created_at) AS at FROM provisioning_events
+      WHERE instance_id = $1 AND event = ANY($2) AND created_at >= $3
+      GROUP BY event`,
+    [instanceId, Object.values(SETUP_EVENTS), since || new Date(0).toISOString()]);
+  const at = (name) => {
+    const r = rows.find((x) => x.event === name);
+    return r && r.at ? new Date(r.at).toISOString() : null;
+  };
+  return { installReportedAt: at(SETUP_EVENTS.installReported), installedAt: at(SETUP_EVENTS.installed), deviceFlowAt: at(SETUP_EVENTS.deviceFlow) };
+}
+
+// Each checklist step's state, from the latest attempt's EFFECTIVE status (manifest-truth's
+// vocabulary) + the facts above. A closed vocabulary the page turns into words:
+//   'done' · 'now' (waiting on GitHub, the founder or the platform) · 'todo' (not reached)
+//   · 'stopped' (this attempt failed at this step) · 'later' (device flow only: optional, off).
+// PURE.
+function githubChecklist(status, appSlug, facts = {}) {
+  const s = String(status || '');
+  const inFlight = s === 'pending' || s === 'code_received' || s === 'converting';
+  const failed = s === 'error' || s === 'expired';
+  const approve = appSlug ? 'done' : inFlight ? 'now' : failed ? 'stopped' : 'todo';
+  const install = facts.installedAt ? 'done' : appSlug ? 'now' : 'todo';
+  const signIn = s === 'done' ? 'done' : appSlug && failed ? 'stopped' : appSlug ? 'now' : 'todo';
+  const device = facts.deviceFlowAt ? 'done' : s === 'done' ? 'later' : 'todo';
+  return {
+    approve, install, sign_in: signIn, device_flow: device,
+    // what "is alive" waits for — device flow is optional by design
+    connected: approve === 'done' && install === 'done' && signIn === 'done',
+  };
+}
+
+// Is the runner still checking this attempt? While it is, an install or a 'later'
+// device-flow step can still tick itself, so the page keeps polling. PURE.
+function stillVerifying(row, facts = {}, now = Date.now()) {
+  const settled = row && (row.resolved_at || row.updated_at);
+  const last = Math.max(settled ? new Date(settled).getTime() : 0, facts.installReportedAt ? new Date(facts.installReportedAt).getTime() : 0);
+  return last > 0 && now - last < VERIFY_WINDOW_MS;
+}
+
+// What the public status poll and the owner's instance read add for this leg: the checklist,
+// the install link (until the install is verified), the repo it belongs on, and whether the
+// runner is still checking. `status` is manifest-truth's EFFECTIVE status. Never the raw row.
+// `withState` false (the owner's instance read) leaves the state token off the install
+// link: that read never carries the token (task 1003235), and a stateless install still
+// lands on the setup page, which sends the founder back to their projects.
+// A failed facts read is "nothing verified yet" — the honest 'now' states, never a 500.
+async function githubSetupRead(db, inst, row, status, { now = Date.now(), withState = true } = {}) {
+  if (!row) return { checklist: githubChecklist(null, null), install_url: null, repo: targetRepo(inst), verifying: false };
+  let facts = {};
+  // through module.exports so a route test can stub the one DB read on the cached module
+  try { facts = await module.exports.githubSetupFacts(db, row.instance_id, row.created_at); } catch (_) { facts = {}; }
+  const checklist = githubChecklist(status, row.app_slug, facts);
+  return {
+    checklist,
+    install_url: checklist.install === 'done' ? null : installUrlFor({ appSlug: row.app_slug, state: withState ? row.state : null }),
+    repo: targetRepo(inst),
+    verifying: stillVerifying(row, facts, now),
+  };
+}
+
+module.exports = { SETUP_EVENTS, VERIFY_WINDOW_MS, installUrlFor, targetRepo, githubSetupFacts, githubChecklist, stillVerifying, githubSetupRead };

package/modules/provisioning/module.json

@@ -21,7 +21,8 @@
       "repo-private",
       "render-standup",
       "look",
-      "demo"
+      "demo",
+      "github-setup"
     ],
     "migrations": true,
     "pollers": [

package/modules/provisioning/provisioning.js

@@ -754,6 +754,9 @@ function buildGithubAppManifest({ instanceName, slug, instanceDomain, mothership
     // is never called while inactive; point it at the mothership so it's a real host.
     hook_attributes: { url: `${String(mothershipOrigin || '').replace(/\/+$/, '')}/api/bongos/provisioning/github-app/webhook`, active: false },
     redirect_url: redirectUrl,
+    // One trip (task 1004649): after the install GitHub sends the founder here with the
+    // attempt's state, and the route hands them back to the project page.
+    setup_url: redirectUrl.replace(/\/callback$/, '/setup'), setup_on_update: true,
     callback_urls: [
       `${instOrigin}/api/gds/auth/web/callback`,
       `${instOrigin}/api/bongos/auth/web/callback`,

package/modules/provisioning/routes/callback-page.js

@@ -82,13 +82,65 @@ const HANDBACK_SCRIPT = `
 })();
 `;
 
+// Client script for the ONE-TRIP variant (task 1004649). GitHub just created the app and
+// sent the founder here; the runner now turns GitHub's code into credentials and names the
+// app. This page waits for that name on the state-keyed status poll, then sends the founder
+// straight on to installing the app — narrowed to the project's own repo when GitHub will
+// tell an anonymous caller the repo's numeric ids (a public repo; a private one falls back
+// to the plain install page, where GitHub asks which account). GitHub's setup_url brings
+// them back to the checklist afterwards. Already installed, or the attempt stopped → back
+// to the checklist at once, which says what happened. A wait past five minutes stops and
+// says so; the way back is always on the page. Same no-backtick / no-${...} rule as above.
+const INSTALL_SCRIPT = `
+(function(){
+  var cfg=window.__CB_SETUP__||{};
+  var back=cfg.back||'/projects?view=new';
+  if(cfg.state)back+='#ghstate='+encodeURIComponent(cfg.state);
+  var link=document.getElementById('back');if(link)link.href=back;
+  var note=document.getElementById('note');
+  var say=function(t){if(note)note.textContent=t;};
+  var tries=0,MAX=150;
+  function narrow(base,ownerId,repoId){
+    var parts=String(base).split('?');
+    return parts[0]+'/permissions?'+(parts[1]?parts[1]+'&':'')+'suggested_target_id='+encodeURIComponent(ownerId)+'&repository_ids[]='+encodeURIComponent(repoId);
+  }
+  function go(url){say('Opening the install page on GitHub…');location.replace(url);}
+  function toInstall(d){
+    if(!d.repo){go(d.install_url);return;}
+    fetch('https://api.github.com/repos/'+d.repo,{headers:{Accept:'application/vnd.github+json'}})
+      .then(function(r){return r.ok?r.json():null;})
+      .then(function(j){go(j&&j.id&&j.owner&&j.owner.id?narrow(d.install_url,j.owner.id,j.id):d.install_url);})
+      .catch(function(){go(d.install_url);});
+  }
+  function tick(){
+    tries++;
+    fetch('/api/bongos/provisioning/github-app/status?state='+encodeURIComponent(cfg.state||''))
+      .then(function(r){return r.ok?r.json():null;})
+      .then(function(d){
+        if(d&&d.checklist&&d.checklist.install==='done'){location.replace(back);return;}
+        if(d&&(d.status==='error'||d.status==='expired')){location.replace(back);return;}
+        if(d&&d.install_url){toInstall(d);return;}
+        again();
+      })
+      .catch(again);
+  }
+  function again(){
+    if(tries>=MAX){say('This is taking longer than usual. Go back to your project: the install step waits for you there.');return;}
+    setTimeout(tick,2000);
+  }
+  tick();
+})();
+`;
+
 // The standalone landing page for the public GitHub redirect (the mothership serves it;
 // it is NOT the hall shell). Two variants share the Cloud Bongos brand shell (task 2096):
 //   • hand-back — ok + state + domain: a brief "GitHub app created" that returns the
 //     founder to their setup checklist, where the wait is shown (task 1004548).
+//   • install — the hand-back's inputs + next:'install' (task 1004649): "GitHub app
+//     created", then straight on to installing it on the repo (INSTALL_SCRIPT).
 //   • message — everything else (errors + the no-domain success fallback): a calm badge
 //     + `body` (server-authored, trusted HTML).
-function callbackPage({ ok, title, body, state, domain }) {
+function callbackPage({ ok, title, body, state, domain, next }) {
   const handback = !!(ok && state && domain);
   const cfgJson = JSON.stringify({ state: state || '', domain: domain || '', back: '/projects?view=new' }).replace(/</g, '\\u003c');
   const head = `<!doctype html><html lang="en"><head><meta charset="utf-8">
@@ -98,6 +150,19 @@ function callbackPage({ ok, title, body, state, domain }) {
 <link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=Baloo+2:wght@600;700;800&family=Quicksand:wght@400;500;600;700&family=Fira+Code&display=swap" rel="stylesheet">
 <style>${PAGE_STYLE}</style></head><body>`;
+  if (handback && next === 'install') {
+    return `${head}
+<main class="card">
+  <div class="badge-warn">✓</div>
+  <h1>${esc(title)}</h1>
+  <p class="sub">Next, install it on your repo. Taking you there now.</p>
+  <p class="muted" id="note" role="status" aria-live="polite">Waiting for GitHub to hand over the app…</p>
+  <div class="cta"><a class="btn" id="back" href="/projects?view=new">Back to my project</a></div>
+</main>
+<script>window.__CB_SETUP__=${cfgJson};</script>
+<script>${INSTALL_SCRIPT}</script>
+</body></html>`;
+  }
   if (handback) {
     return `${head}
 <main class="card">

package/modules/provisioning/routes/core-upgrade.js

@@ -62,6 +62,15 @@ function contributeCoreDesk() {
   });
 }
 
+// WHO DECIDES AT RELEASE (task 1004657; ADR 0363 D5). The pin move and the
+// update rule are Release's own acts when the PIN door admitted the caller: while
+// the project's decision-rules row hands Release to a sitting, one builder acting
+// alone is refused (409 decided_by_sitting). Not a lone Release act, so never
+// asked: a tenant project's own owner moving THEIR project (ADR 0339 — that
+// project's decision, not this one's), and a dry run, which only reads.
+const notThisProjectsRelease = (req) => req.coreUpgradeAuthority === 'owner';
+const notADecision = (req) => notThisProjectsRelease(req) || (!!req.body && req.body.dry_run === true);
+
 module.exports = function buildCoreUpgradeRouter() {
   contributeCoreDesk();
   const router = express.Router();
@@ -95,6 +104,7 @@ module.exports = function buildCoreUpgradeRouter() {
     '/provisioning/instances/:id/core-upgrade',
     api.requireBuilder,
     requireOwnProjectOrPin({ pinGate: api.requirePermission('core.pin.move'), provisioning, pool: api.pool, log }),
+    api.requireActAlone('release', { unless: notADecision }),
     makeCoreUpgradeHandler({
       provisioning,
       pool: api.pool,
@@ -130,6 +140,7 @@ module.exports = function buildCoreUpgradeRouter() {
     '/provisioning/instances/:id/update-channel',
     api.requireBuilder,
     requireOwnProjectOrPin({ pinGate: api.requirePermission('core.pin.move'), provisioning, pool: api.pool, log }),
+    api.requireActAlone('release', { unless: notThisProjectsRelease }),
     makeUpdateChannelHandler({
       provisioning,
       pool: api.pool,