@bongos/core 1.20.24 → 1.20.26

package/modules/government/board.js

@@ -627,7 +627,12 @@ async function closeItem(item, { cause = 'vote' } = {}) {
   });
   if (!closed) return { closed: false, reason: 'already_closed' };
 
-  const authorKarma = outcome === 'passed' ? await awardAuthorRatifyKarma(closed) : null;
+  // A genesis stage ratifies no authored work — closing it is the project's
+  // decision that a stage is done, not a reward for the founder who put it up
+  // (task 1004429). Ideas and amendments pay exactly as before.
+  const authorKarma = outcome === 'passed' && closed.subject_type !== 'genesis_stage'
+    ? await awardAuthorRatifyKarma(closed)
+    : null;
 
   // R14: a PASSED amendment becomes the live constitution — applied AFTER the
   // close commits (the board's decision is the durable record), loudly on
@@ -652,6 +657,7 @@ async function closeItem(item, { cause = 'vote' } = {}) {
     try {
       if (api.emitAsync) await api.emitAsync('board.item.passed', payload);
     } catch (_) { /* emitAsync isolates listener errors; nothing that moves credits subscribes */ }
+    if (closed.subject_type === 'genesis_stage') await emitGenesisStagePassed(closed);
   }
 
   // R22's mirror event: BOTH outcomes, after commit, emitAsync. Separate from
@@ -806,6 +812,188 @@ async function proposeAmendment({
   return { ok: true, amendment, item };
 }
 
+// ── the board's third subject: closing a genesis stage (task 1004429) ───────
+//
+// Spec decision D7 (docs/specs/bongos-v2-project-startup.md): a new project is
+// founded through five stages, and when a stage's tasks are all finished its
+// close is put to the constitution IN FORCE. It is an ordinary board item, and
+// that is the whole design — the stage borrows every rule the board already
+// has rather than bringing one of its own:
+//
+//   • THE CONSTITUTION IS SNAPSHOTTED, like every item, so a charter adopted
+//     mid-sitting does not change how an already-open stage closes.
+//   • NO NEW PASS RULE, NO GENESIS BYPASS. Under the monarchy default
+//     (first_ratifier) the founder's single confirm closes the stage because
+//     the founder is the first ratifier — not because anything special-cases
+//     genesis. Under consent, majority or unanimous it is a real sitting, with
+//     the clock and turnout rules unchanged.
+//   • THE AUTHOR RULE IS UNCHANGED — which means it does not reach a stage. It
+//     is full_idea-scoped (authorRuleApplies, ADR 0191): it guards an author
+//     who GAINS from ratification, and closing a stage pays nobody. A stage is
+//     in the amendment's position, where §7 already says the one member of a
+//     monarchy must be able to decide their own item.
+//   • IT PAYS NOTHING. No credit (the reward port is only reached for a
+//     full_idea) and no ratify karma (closeItem skips it for a stage).
+//
+// The subject_id is the stage NUMBER. An instance is one project, so the
+// number names a stage uniquely, and government_003's one-open-per-subject
+// index then keeps at most one sitting per stage STRUCTURALLY — the same
+// idempotency a Full Idea gets. A passed stage may be sat again later (the
+// design's "second pass once your builders join"); the index is partial on
+// open items only. government_020 widens the subject CHECK and bounds the range.
+const GENESIS_STAGES = Object.freeze([
+  Object.freeze({ key: 'scope', number: 1, label: 'Scope' }),
+  Object.freeze({ key: 'strategize', number: 2, label: 'Strategize' }),
+  Object.freeze({ key: 'charter', number: 3, label: 'Charter' }),
+  Object.freeze({ key: 'legalize', number: 4, label: 'Legalize' }),
+  Object.freeze({ key: 'legislation', number: 5, label: 'Legislation' }),
+]);
+
+// "Finished" is the task's terminal states: shipped, or dropped — which the
+// tasks table spells `abandoned` (migration 012; a merged-away task lands
+// there too). `confirmed` is NOT finished: the work is graded but not landed.
+const STAGE_TASK_FINISHED_STATUSES = Object.freeze(['shipped', 'abandoned']);
+
+const stageByKey = (key) => GENESIS_STAGES.find((s) => s.key === key) || null;
+const stageByNumber = (n) => GENESIS_STAGES.find((s) => s.number === Number(n)) || null;
+
+// The pass rules, said in words for the founding band. Keyed by exactly
+// config.js PASS_RULES (held equal by tests/government_board_genesis_stage.mjs,
+// so a fifth rule cannot land without its words); an unknown rule in an old
+// snapshot says so rather than guessing.
+const PASS_RULE_WORDS = Object.freeze({
+  first_ratifier: 'One yes from any member decides it.',
+  consent: 'It passes unless a member objects, once everyone has voted or the clock runs out.',
+  majority: 'More than half of all members must say yes.',
+  unanimous: 'Everyone who votes must agree, and at least one member must say yes.',
+});
+
+// Put a finished stage to the board. Returns, never throws for a refusal:
+//   { opened: true,  item, stage }
+//   { opened: false, reason: 'unknown_stage' | 'no_stage_tasks' }
+//   { opened: false, reason: 'stage_tasks_unfinished', unfinished: [{ task_id, status }] }
+//   { opened: false, reason: 'already_open', item, stage }
+//
+// THE FINISHED-TASKS GATE LIVES HERE, not in the caller — the same posture as
+// the Full Idea bar: the genesis home says which tasks make up the stage, and
+// this module checks them against the tasks table before anything is written.
+// An empty list is refused rather than read as "nothing left to do", because a
+// stage close with no tasks behind it would be exactly the bypass D7 rules out.
+// `openedBy` is the founder (or whoever put it up); it may be null for an
+// automatic open, the same as a grade-opened idea.
+//
+// WHO MAY CALL THIS is the caller's gate, by design, exactly as for
+// openWindowForFullIdea: this is a port method with no HTTP route, and opening
+// a sitting decides nothing — it only asks the board. Whoever exposes it to a
+// person (the genesis home) must gate that route itself. The deciding wall is
+// unchanged either way: only a member under the snapshot can vote it closed.
+async function openGenesisStageClose({ stageKey, taskIds, openedBy = null } = {}) {
+  const stage = stageByKey(stageKey);
+  if (!stage) return { opened: false, reason: 'unknown_stage' };
+  const ids = Array.isArray(taskIds) ? taskIds.map(Number) : [];
+  if (!ids.length || !ids.every((n) => Number.isInteger(n) && n > 0)) {
+    return { opened: false, reason: 'no_stage_tasks' };
+  }
+  const unique = [...new Set(ids)];
+  const rows = await db.getTaskStatuses(unique);
+  const statusById = new Map(rows.map((r) => [String(r.id), r.status]));
+  const unfinished = unique
+    .filter((id) => !STAGE_TASK_FINISHED_STATUSES.includes(statusById.get(String(id))))
+    .map((id) => ({ task_id: String(id), status: statusById.get(String(id)) ?? null }));
+  if (unfinished.length) return { opened: false, reason: 'stage_tasks_unfinished', unfinished };
+
+  const { board } = loadGovernmentConfig();
+  const item = await db.openBoardItem({
+    subjectType: 'genesis_stage',
+    subjectId: stage.number,
+    openedBy: openedBy == null || openedBy === '' ? null : openedBy,
+    constitution: board,
+    windowMinutes: board.window_minutes,
+  });
+  if (!item) {
+    return { opened: false, reason: 'already_open', item: await db.getOpenBoardItem('genesis_stage', stage.number), stage };
+  }
+  await emitWindowOpened(item);
+  return { opened: true, item, stage };
+}
+
+// The genesis home's cue (spec D7 / task 1004423): a stage's sitting PASSED,
+// so mark it done and wake its room. Emitted after the close commits, beside
+// the general `board.item.passed`, carrying what that contract deliberately
+// does not — which stage. Best-effort by construction, like every board event:
+// the durable fact is the `outcome = 'passed'` row, which genesisStageStatus
+// reads, so a listener that missed the nudge can always recover the state.
+async function emitGenesisStagePassed(closed) {
+  const stage = stageByNumber(closed.subject_id);
+  if (!stage) return;
+  try {
+    if (api.emitAsync) {
+      await api.emitAsync('board.genesis_stage.passed', {
+        item_id: String(closed.id),
+        stage_key: stage.key,
+        stage_number: stage.number,
+        passed_at: closed.closed_at || null,
+      });
+    }
+  } catch (_) { /* a nudge that fails is recoverable from the passed row */ }
+}
+
+// "Who is this stage waiting on" — for the founding band. One entry per stage,
+// from the LATEST sitting on it:
+//   state: 'not_put' (never put to the board) | 'sitting' | 'passed' | 'returned'
+// and for a sitting, the members under the item's OWN snapshot (not the live
+// config), split into who has voted and who is still to — per request,
+// uncached, the ADR 0016 posture of every membership read here. Under monarchy
+// `one_vote_decides` is true and `waiting_on` names everyone who could give
+// that vote. The countdown is the database's (`remaining_seconds`); the client
+// never does clock math. Membership is resolved once per distinct predicate.
+async function genesisStageStatus() {
+  const items = await db.listLatestGenesisStageItems();
+  const open = items.filter((i) => !i.closed_at);
+  const votes = open.length ? await db.getVotesForItems(open.map((i) => i.id)) : [];
+  const membersByPredicate = new Map();
+  const stages = [];
+  for (const stage of GENESIS_STAGES) {
+    const item = items.find((i) => Number(i.subject_id) === stage.number);
+    const base = { key: stage.key, number: stage.number, label: stage.label };
+    if (!item) {
+      stages.push({ ...base, state: 'not_put', item_id: null, voted: [], waiting_on: [] });
+      continue;
+    }
+    const constitution = item.constitution || {};
+    const common = {
+      ...base,
+      item_id: String(item.id),
+      opened_at: item.opened_at || null,
+      pass_rule: constitution.pass_rule || null,
+      needs: PASS_RULE_WORDS[constitution.pass_rule] || 'The rule this sitting runs under is not one this version knows; only its clock can close it.',
+      one_vote_decides: constitution.pass_rule === 'first_ratifier',
+    };
+    if (item.closed_at) {
+      stages.push({ ...common, state: item.outcome, closed_at: item.closed_at, voted: [], waiting_on: [] });
+      continue;
+    }
+    const key = String(constitution.membership || '');
+    if (!membersByPredicate.has(key)) membersByPredicate.set(key, await resolveBoardMembers(constitution));
+    const members = membersByPredicate.get(key);
+    const cast = votes.filter((v) => String(v.item_id) === String(item.id));
+    const castBy = new Map(cast.map((v) => [String(v.voter_id), v]));
+    stages.push({
+      ...common,
+      state: 'sitting',
+      closes_at: item.closes_at || null,
+      remaining_seconds: item.remaining_seconds ?? null,
+      voted: cast.map((v) => ({
+        builder_id: String(v.voter_id), github_login: v.github_login, display_name: v.display_name, direction: v.direction,
+      })),
+      waiting_on: members.filter((m) => !castBy.has(String(m.builder_id))).map((m) => ({
+        builder_id: m.builder_id, github_login: m.github_login, display_name: m.display_name,
+      })),
+    });
+  }
+  return { stages };
+}
+
 // ── the Board Room view (BV1.R16 of goal 1000069, ADR 0175 §9) ──────────────
 //
 // One assembled read for the room: open items with their clock, the OPEN
@@ -851,7 +1039,17 @@ async function boardRoomView({ closedLimit = 20 } = {}) {
     });
   }
   const project = (item) => {
-    const subject = item.subject_type === 'full_idea'
+    // A genesis stage's subject is the stage itself — named from the one list,
+    // so the room never mistakes it for an amendment (task 1004429).
+    const subject = item.subject_type === 'genesis_stage'
+      ? (() => {
+          const s = stageByNumber(item.subject_id);
+          return s ? {
+            stage_key: s.key, stage_number: s.number, label: s.label,
+            author_id: item.opened_by == null ? null : String(item.opened_by),
+          } : null;
+        })()
+      : item.subject_type === 'full_idea'
       ? (() => {
           const r = ideaById.get(String(item.subject_id));
           return r ? {
@@ -1138,6 +1336,10 @@ async function pendingVotesFor(builderId) {
 }
 
 module.exports = {
+  GENESIS_STAGES,
+  PASS_RULE_WORDS,
+  openGenesisStageClose,
+  genesisStageStatus,
   pendingVotesFor,
   hasMajority,
   majorityDecided,

package/modules/government/db.js

@@ -688,7 +688,12 @@ async function getExpiredOpenBoardItems(limit = 100) {
 async function openBoardItemsAwaitingVoter(voterId) {
   const { rows } = await pool.query(
     `SELECT i.id, i.subject_type, i.subject_id, i.constitution, i.opened_at, i.closes_at,
-            CASE WHEN i.subject_type = 'full_idea' THEN idea.captured_by ELSE i.opened_by END AS author_id,
+            -- A genesis stage has no author to hold back (task 1004429): the
+            -- founder who put it up IS the confirm monarchy waits on, so they
+            -- must be summoned, not skipped.
+            CASE WHEN i.subject_type = 'full_idea' THEN idea.captured_by
+                 WHEN i.subject_type = 'genesis_stage' THEN NULL
+                 ELSE i.opened_by END AS author_id,
             (v.id IS NOT NULL) AS already_voted
        FROM government_board_items i
        LEFT JOIN idea_inbox idea
@@ -703,6 +708,40 @@ async function openBoardItemsAwaitingVoter(voterId) {
   return rows;
 }
 
+// --- genesis stages (task 1004429 / BV2.PS04) --------------------------------
+
+// The status of each task a stage names, for the "are this stage's tasks all
+// finished" gate. `tasks` is a core table; READING it is the sanctioned pattern
+// (the boundary is code imports, not table access). An id with no row comes
+// back absent, and the caller counts that as unfinished — a stage cannot close
+// on a task nobody can find.
+async function getTaskStatuses(taskIds) {
+  if (!taskIds || !taskIds.length) return [];
+  const { rows } = await pool.query(
+    `SELECT id, status FROM tasks WHERE id = ANY($1::bigint[])`,
+    [taskIds],
+  );
+  return rows;
+}
+
+// The latest sitting for each genesis stage (one row per stage number, newest
+// first within it), with the same database-clock fields the room reads. Served
+// by government_020's partial index, keyed to exactly this ORDER BY — the table
+// holds every idea and amendment sitting forever, and without it this read
+// would scan all of that history to find a handful of stage rows.
+async function listLatestGenesisStageItems() {
+  const { rows } = await pool.query(
+    `SELECT DISTINCT ON (subject_id) *,
+            (closes_at IS NOT NULL AND closes_at < now()) AS expired,
+            CASE WHEN closes_at IS NULL THEN NULL
+                 ELSE GREATEST(0, EXTRACT(EPOCH FROM (closes_at - now()))::int) END AS remaining_seconds
+       FROM government_board_items
+      WHERE subject_type = 'genesis_stage'
+      ORDER BY subject_id, opened_at DESC, id DESC`,
+  );
+  return rows;
+}
+
 // Author-ratification karma (+3, board.js AUTHOR_RATIFY_KARMA_DELTA) — fired by
 // the R10 close on a passed item. IDEMPOTENT: the reason key is unique per item
 // and the INSERT is one atomic WHERE-NOT-EXISTS statement (the economy
@@ -731,6 +770,8 @@ async function insertVoteKarma({ voterId, itemId, delta }) {
 
 module.exports = {
   openBoardItemsAwaitingVoter,
+  getTaskStatuses,
+  listLatestGenesisStageItems,
   getPermissionKeysForBuilder,
   getRankKeysForBuilder,
   getSeededRanks,

package/modules/government/migrations/government_020_genesis_stage_subject.sql

@@ -0,0 +1,55 @@
+-- government_020_genesis_stage_subject.sql — the board's third subject: closing
+-- a genesis stage (task 1004429 / BV2.PS04, spec docs/specs/bongos-v2-project-
+-- startup.md decision D7).
+--
+-- government_003 built `subject_type` so that a third subject would be "a row,
+-- not a migration". That held for the ROWS — no new table, no new column — but
+-- the column carries a CHECK naming the two subjects it knew about, so the
+-- vocabulary itself still has to widen here. That is the whole of this file.
+--
+-- A genesis stage's subject_id is its STAGE NUMBER (1 scope · 2 strategize ·
+-- 3 charter · 4 legalize · 5 legislation — board.js GENESIS_STAGES is the one
+-- list). An instance is one project, so the number names the stage uniquely,
+-- and that is what lets government_003's partial unique index keep AT MOST ONE
+-- OPEN SITTING PER STAGE structurally, the same way it keeps one per idea: a
+-- double-fired "the stage's tasks are done" opens exactly one item. A stage
+-- that passed can be sat again later (the "second pass once your builders
+-- join" in the design of record) — the index is partial on open items only.
+--
+-- Nothing about deciding changes. The item snapshots the constitution in force
+-- like every other item, the pass rules are the same four, and the author and
+-- clock rules are the ones every item runs under.
+--
+-- Additive, idempotent: dropping and re-adding a CHECK that only WIDENS admits
+-- every row already in the table.
+
+BEGIN;
+
+ALTER TABLE government_board_items
+  DROP CONSTRAINT IF EXISTS government_board_items_subject_type_check;
+
+ALTER TABLE government_board_items
+  ADD CONSTRAINT government_board_items_subject_type_check
+  CHECK (subject_type IN ('full_idea', 'constitutional_amendment', 'genesis_stage'));
+
+-- The stage number is a small closed range; a stray id would be a sitting on a
+-- stage that does not exist. Scoped to genesis_stage so the other subjects'
+-- ids (idea and amendment row ids) are untouched.
+ALTER TABLE government_board_items
+  DROP CONSTRAINT IF EXISTS government_board_items_genesis_stage_number;
+
+ALTER TABLE government_board_items
+  ADD CONSTRAINT government_board_items_genesis_stage_number
+  CHECK (subject_type <> 'genesis_stage' OR subject_id BETWEEN 1 AND 5);
+
+-- Serves the founding band's read (db.js listLatestGenesisStageItems: the latest
+-- sitting per stage, DISTINCT ON subject_id ORDER BY subject_id, opened_at DESC,
+-- id DESC). The table only grows — every Full Idea and amendment sitting stays
+-- forever — so a read that filters by subject_type alone would scan that whole
+-- history to find at most a handful of stage rows. Partial on the one subject it
+-- asks for and keyed to its ORDER BY exactly, the government_006/018 shape.
+CREATE INDEX IF NOT EXISTS government_board_items_genesis_stage_latest
+  ON government_board_items (subject_id, opened_at DESC, id DESC)
+  WHERE subject_type = 'genesis_stage';
+
+COMMIT;

package/modules/government/routes/government.js

@@ -108,6 +108,13 @@ const governmentPort = {
   // is no counterpart that records an outcome, and there must never be one: an
   // outcome is written by a close, never by the module reading it.
   boardPassForIdea: board.boardPassForIdea,
+  // task 1004429 (BV2.PS04): a finished genesis stage is put to the board — the
+  // genesis home (task 1004423) calls this when a stage's tasks are done. The
+  // finished-tasks gate lives inside board.js; the item is an ordinary one under
+  // the constitution in force. And the founding band's read: per stage, what it
+  // is waiting on. A pass is announced as `board.genesis_stage.passed`.
+  openGenesisStageClose: board.openGenesisStageClose,
+  genesisStageStatus: board.genesisStageStatus,
 };
 
 function registerSeams() {
@@ -460,6 +467,19 @@ module.exports = function buildGovernmentRouter() {
     }
   });
 
+  // rank: perm board.vote.cast — the founding band's read (task 1004429): each
+  // genesis stage's latest sitting, and who it is still waiting on under the
+  // item's own snapshot. Same atom as the room — seeing who is still to vote is
+  // part of the open ballot (§9). A read; nothing here opens or decides.
+  router.get('/government/board/genesis-stages', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    try {
+      res.json(await board.genesisStageStatus());
+    } catch (err) {
+      log.error('[gds] GET /government/board/genesis-stages', err);
+      res.fail('genesis_stage_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // rank: perm board.item.open — put an AMENDMENT to the board (R14 of goal
   // 1000069, ADR 0175 §7). The board's other subject never comes through here:
   // a Full Idea's window opens AUTOMATICALLY on grade pass (R07), so requesting

package/modules/hall-ui/public/board-room.js

@@ -132,6 +132,11 @@
       const title = item.subject ? item.subject.title : `idea ${item.subject_id}`;
       return `<a href="/#/idea/${escapeHtml(String(item.subject_id))}">${escapeHtml(title)}</a> ${pill('quiet', 'Full Idea')}`;
     }
+    // task 1004429: the third subject — closing a founding stage.
+    if (item.subject_type === 'genesis_stage') {
+      const label = item.subject ? item.subject.label : `stage ${item.subject_id}`;
+      return `Close the ${escapeHtml(label)} stage ${pill('quiet', 'genesis stage')}`;
+    }
     return `Constitutional amendment ${pill('quiet', 'amendment')}`;
   }
 

package/modules/provisioning/free-place-lock.js

@@ -0,0 +1,52 @@
+// modules/provisioning/free-place-lock.js — one first-free hosted-project request per
+// builder at a time, across every web process (task 1004412, ADR 0354 D2).
+//
+// The shape gate counts a builder's live hosted projects and the route inserts the new
+// one a few awaits later. Two requests sent together would both count zero and both take
+// the free place. A process-local mark only closes that inside one process, so the guard
+// is a Postgres advisory lock keyed on the builder: whichever request holds it answers,
+// and any other request from that builder, from any process, is refused until it is let
+// go. It is taken with TRY, so nothing ever queues behind it.
+//
+// Session-level, on a client held from the gate's count to the route's insert, because the
+// count and the insert are not one transaction. Releasing unlocks and returns the client; if the
+// unlock itself fails the client is destroyed, which ends the session and frees the lock.
+//
+// Its own file so a test can re-point `holdFreePlace` through the module object, and
+// because provisioning.js and routes/provisioning.js sit at their size ratchets.
+'use strict';
+
+// The lock's first key: one namespace for this guard, so it can never collide with an
+// advisory lock another part of the platform takes on a builder id.
+const NAMESPACE_SQL = "hashtext('provisioning.one-free-hosted-project')";
+
+// holdFreePlace — try to hold the builder's free-place lock. Resolves to a release
+// function when it is held, or null when another request already holds it. Throws when
+// the database cannot be asked; the caller refuses then (it never admits on a guess).
+async function holdFreePlace(db, builderId) {
+  const key = Number(builderId);
+  if (!Number.isInteger(key)) throw new TypeError(`free-place lock: builder id ${builderId} is not an integer`);
+  const client = await db.connect();
+  let held;
+  try {
+    const { rows } = await client.query(`SELECT pg_try_advisory_lock(${NAMESPACE_SQL}, $1::int) AS held`, [key]);
+    held = !!(rows[0] && rows[0].held);
+  } catch (err) {
+    client.release(true);
+    throw err;
+  }
+  if (!held) { client.release(); return null; }
+  let released = false;
+  return async function release() {
+    if (released) return;
+    released = true;
+    try {
+      await client.query(`SELECT pg_advisory_unlock(${NAMESPACE_SQL}, $1::int)`, [key]);
+      client.release();
+    } catch {
+      client.release(true);
+    }
+  };
+}
+
+module.exports = { holdFreePlace };

package/modules/provisioning/paid-shape-gate.js

@@ -1,5 +1,6 @@
-// modules/provisioning/paid-shape-gate.js — who may ask for which hosting SHAPE
-// (task 1003682, widened by task 1003370 / audit B4).
+// modules/provisioning/paid-shape-gate.js — who may ask for which hosting SHAPE, and how
+// many hosted projects a builder may hold without the fleet permission
+// (task 1003682, widened by task 1003370 / audit B4, one free hosted project by task 1004412).
 //
 // THE FILENAME IS NARROWER THAN THE FILE, DELIBERATELY. This started as the gate over
 // METERED shapes alone. Task 1003370 widened it to every shape that is not the free
@@ -9,9 +10,9 @@
 // clarity for free.
 //
 // The create route is open to any authenticated builder, and it must stay that way:
-// standing up a project is the platform's front door, not a privilege. But only ONE of
-// the shapes it accepts is actually that front door. The others each hand the caller
-// something the platform pays for or trusts:
+// standing up a project is the platform's front door, not a privilege. But only two of
+// the shapes it accepts are that front door, and only one of them without limit. The
+// others each hand the caller something the platform pays for or trusts:
 //
 //   byo-host      — the front door since ADR 0323. The OWNER supplies the host, so the
 //                   platform pays nothing and runs none of the caller's code. No
@@ -22,23 +23,23 @@
 //   co-tenant     — RETIRED (ADR 0323). Was the free front door; ran on the platform's
 //                   own box, which is why the name could not be carried over to
 //                   bring-your-own-host. Now UNREQUESTABLE — see below.
-//   cloud-host    — runs the caller's OWN repo on a host the platform stands up. TODAY
-//                   that host is still the platform's own box, and that is what this
-//                   entry gates: the unit's WorkingDirectory is that checkout
+//   cloud-host    — the project's hall, hosted by us (ADR 0345), and the only shape the
+//                   create wizard sends. It runs the caller's OWN repo on the platform's
+//                   own box: the unit's WorkingDirectory is that checkout
 //                   (`scripts/gds/provision-units.js`) and the module loader discovers
 //                   modules from `resolveInstanceRoot()`, which is process.cwd()
 //                   (`src/module-loader/loader.js`). So the caller names a repo and the
-//                   platform require()s its `modules/` — arbitrary code execution on the
-//                   control plane's own machine. Task 1003369 gave each instance its own
-//                   uid, which bounds the blast radius to that account; it does not make
-//                   "any Xenos may run code here" an acceptable default.
+//                   platform require()s its `modules/` — code execution on the control
+//                   plane's own machine. Task 1003369 gave each instance its own uid,
+//                   which bounds the blast radius to that account.
 //
-//                   Once ADR 0327 lands, a cloud-host stands up on the OWNER's platform
-//                   account instead and that specific argument dissolves — but the gate
-//                   does NOT automatically follow, because the platform is still doing
-//                   the standing-up and still spending its own runner on it. Re-decide
-//                   this entry when the move happens (task 1004184); do not assume the
-//                   shape becomes open just because the box stops being ours.
+//                   Task 1003370 gated it outright, and that also refused every new user
+//                   at the wizard's last button (task 1004412): ADR 0345 decision 1 says
+//                   creating a project needs no account, key or bill. The owner's ruling
+//                   (2026-09-30, ADR 0354): a builder's FIRST live hosted project needs no
+//                   authority, and a further one needs the fleet permission. The limit is
+//                   what stops one person taking every place on the box (ADR 0285). See
+//                   ONE_FREE_SHAPES below.
 //
 //                   Stored as 'standalone' until task 1004182 renamed it to match the
 //                   owner-facing name (migration provisioning_027). The old 'dedicated'
@@ -54,7 +55,8 @@
 // reason this is a middleware over one field rather than a floor on the endpoint.
 //
 // AN ALLOW-LIST, NOT A DENY-LIST — the control-plane-guard.js rule, for the same reason.
-// The set named below is the set that needs NO authority. Every other shape, including
+// The sets named below are the ones that need no authority (OPEN_SHAPES), or none for a
+// builder's first project (ONE_FREE_SHAPES). Every other shape, including
 // one added after this file was last read, requires the permission by omission. The
 // previous shape of this gate listed the one shape that was gated and admitted the rest,
 // and that is exactly how `cloud-host` and `control-plane` stayed open: `cloud-host`
@@ -79,14 +81,30 @@
 'use strict';
 
 const provisioning = require('./provisioning.js');
+const { failFrom } = require('./public-refusal');
 
-// The shapes any authenticated builder may request with no permission at all. This is
-// the whole allow-list, and it is deliberately one entry long: byo-host is the front
-// door, and the front door is the only thing that should be free. `tests/
-// provisioning_paid_shape_gate.mjs` pins HOSTING_SHAPES against this set so a new shape
+// The shapes any authenticated builder may request with no permission at all, as many
+// times as they like. Deliberately one entry long: byo-host runs on the owner's own
+// host, so it costs the platform nothing and runs none of the caller's code. `tests/
+// provisioning_paid_shape_gate.mjs` pins HOSTING_SHAPES against these sets so a new shape
 // cannot be added without someone deciding, in writing, which side of the line it is on.
 const OPEN_SHAPES = Object.freeze(new Set(['byo-host']));
 
+// The shapes a builder may hold ONE live project of with no permission (task 1004412,
+// ADR 0354). A second one needs provisioning.fleet.manage, like any shape outside every
+// set here. cloud-host is the only member: it is the wizard's front door under ADR 0345,
+// and it spends a place on the shared box, of which there are about fifteen (ADR 0285).
+// "Live" is any status but torn_down: a failed or queued project still holds its place,
+// and its owner can retry it (the same slug) or take it offline to free the place.
+const ONE_FREE_SHAPES = Object.freeze(new Set(['cloud-host']));
+
+// One first-free request per builder at a time. The count and the insert are two steps
+// with awaits between them, so two requests sent at once would both count zero and both
+// take the free place. The builder's advisory lock is held from before the count until
+// the response closes, so a second request sent meanwhile — from any web process — is
+// refused (the wizard never sends two). ./free-place-lock.js says how it is held.
+const freePlace = require('./free-place-lock');
+
 // Shapes that are not requestable through this route AT ALL — no permission admits them,
 // because there is no rank at which "ask the API for a second control plane" is a
 // coherent request. The control-plane row is the platform describing ITSELF; a builder
@@ -105,6 +123,8 @@ const UNREQUESTABLE_SHAPES = Object.freeze(new Set(['control-plane', 'co-tenant'
 
 // shapeAuthority — what does this wire value demand? PURE. Returns one of:
 //   'open'          → admit with no permission
+//   'one-free'      → admit the caller's first live project of the shape; after that,
+//                     require provisioning.fleet.manage
 //   'unrequestable' → refuse outright, whatever the caller holds
 //   'permission'    → require provisioning.fleet.manage
 //   'defer'         → not a shape this gate recognises; let the route's own validator
@@ -128,18 +148,58 @@ function shapeAuthority(rawShape) {
   if (!provisioning.HOSTING_SHAPES.includes(shape)) return 'defer';
   if (UNREQUESTABLE_SHAPES.has(shape)) return 'unrequestable';
   if (OPEN_SHAPES.has(shape)) return 'open';
+  if (ONE_FREE_SHAPES.has(shape)) return 'one-free';
   return 'permission';
 }
 
+// otherLiveProjects — the caller's own projects of this shape that still hold their place,
+// leaving out the slug being asked for: a retry or revive of your own project is that
+// project again, not a second one. The slug is normalised exactly as the route does.
+// Reads provisioning through its module object at request time so a test can re-point it.
+async function otherLiveProjects(db, builderId, shape, rawSlug) {
+  const slug = String(rawSlug || '').trim().toLowerCase();
+  const rows = await provisioning.listInstancesForOwner(db, builderId);
+  return rows.filter((r) => r.hosting_shape === shape && r.status !== 'torn_down' && r.slug !== slug);
+}
+
 // requireAuthorityForShape — the create route's shape gate. Mount it AFTER requireBuilder
 // and BEFORE the handler, so a refusal leaves no row behind for the runner to drain later.
 // `requirePermission` is injected (rather than required here) so the gate is exercisable
-// without standing up the auth stack.
-function requireAuthorityForShape(requirePermission) {
+// without standing up the auth stack; `db` and `log` serve the one-free count.
+function requireAuthorityForShape(requirePermission, db, log) {
   const gate = requirePermission('provisioning.fleet.manage');
-  return function shapeGate(req, res, next) {
+  return async function shapeGate(req, res, next) {
     const verdict = shapeAuthority(req.body && req.body.hosting_shape);
     if (verdict === 'open' || verdict === 'defer') return next();
+    if (verdict === 'one-free') {
+      let others;
+      try {
+        // Read through the module object at request time so a test can re-point it.
+        const release = await freePlace.holdFreePlace(db, req.builder.id);
+        if (!release) {
+          return res.fail('create_in_progress', {
+            status: 409,
+            message: 'Another project request from this account is still being answered. Try again once it finishes.',
+          });
+        }
+        // Held until the row exists: the handler calls req.releaseFreePlace right after its
+        // insert, so the lock's connection is not kept through the rest of the request.
+        // Every earlier exit (a refusal, a validation 400, a thrown error, a client that
+        // hangs up) releases on 'close' instead — 'close', not 'finish', because 'finish'
+        // never fires for a response the client abandoned. Release is idempotent.
+        req.releaseFreePlace = release;
+        res.once('close', () => { release().catch(() => {}); });
+        others = await otherLiveProjects(db, req.builder.id, req.body.hosting_shape, req.body.slug);
+      } catch (err) {
+        // Fail CLOSED (ADR 0016): a lock or count that could not be read is not a free place.
+        log.error('[provisioning] shape gate could not lock or count the caller\'s projects; refusing', err);
+        return failFrom(res, err, 'request_failed');
+      }
+      if (others.length === 0) return next();
+      // A further live project: the same permission as any gated shape, and the kernel
+      // gate's own refusal (permission_forbidden, naming the atom) is the answer.
+      return gate(req, res, next);
+    }
     if (verdict === 'unrequestable') {
       // Two shapes land here for different reasons, so the message names which.
       //
@@ -167,8 +227,8 @@ function requireAuthorityForShape(requirePermission) {
   };
 }
 
-// Only the gate is exported. OPEN_SHAPES, UNREQUESTABLE_SHAPES and shapeAuthority are
-// deliberately private: nothing outside this file needs to ask "what does this shape
-// demand" separately from being gated on it, and an export nobody consumes is one more
-// thing to keep true.
+// Only the gate is exported. OPEN_SHAPES, ONE_FREE_SHAPES, UNREQUESTABLE_SHAPES and
+// shapeAuthority are deliberately private: nothing outside this file needs to ask "what
+// does this shape demand" separately from being gated on it, and an export nobody
+// consumes is one more thing to keep true.
 module.exports = { requireAuthorityForShape };