@bongos/core 1.19.676 → 1.19.678

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.676",
-  "core_contract": "1.19.676",
-  "source_commit": "9aad4d0005991e8ba38f4443b4e5611a13aa3af8",
+  "core_version": "1.19.678",
+  "core_contract": "1.19.678",
+  "source_commit": "f16c9e626ff2c55f717a95aee3d34d77b8d1d7cc",
   "source_ref": "HEAD",
-  "built_at": "2026-09-11T20:44:28.469Z",
+  "built_at": "2026-09-11T22:19:41.718Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 474,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2123,
+    "functional_verbatim": 2124,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2621,
-  "tree_sha256": "b556a6e9644d99b65ffdf9ac64384eee16b20ecfb7e31ed60c875d76297310f3",
+  "file_count": 2622,
+  "tree_sha256": "f74a39b4cffb6701304f05814582718e8b1580ab01d97d6c6be2be8e2ff4e18f",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -387,7 +387,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "22523f2527d8849445122c5a03332d777a63d849a5806e33d387cbd83c54fb2f"
+      "sha256": "ba2f6ea9be911785f06761110363357fc1257fb53dadcb51def6194d1f60c9e7"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -1912,12 +1912,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "6b681ad5de20a67efa1d6d024d5cb5dbe5313add4ec51d94a30a0025fa567ba2"
+      "sha256": "f4f639df647605d86971b62b81921c77c465ded0782eb29d7fc5254ba2f16d0d"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "301cf1db00b9f18b84cb765bbaa359329a665b1ef754dff4c21c1550ec60cae5"
+      "sha256": "dbe27d28100bdbf007baefc90bfc93692b04fc8772019976292260617af175ac"
     },
     {
       "path": "docs/architecture.md",
@@ -2792,7 +2792,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "b8786c58575f93eb93661ee1d7e0745f0993f5666e5237ca073177df2d3ee9f4"
+      "sha256": "ec91ef553908baf5180767c401d6b91afc48d938740258e63a48fb88106f7177"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5662,7 +5662,7 @@
     {
       "path": "modules/lifecycle/db-goals.js",
       "mode": "0000644",
-      "sha256": "dde23a909ea56f7102d42af9bd5a832449940b00b4bfac7ed779e7938d95885c"
+      "sha256": "23df3da3437c14aa3dd1d276d501a9fd42c9937ffdfcec8d7b893d5edfd69469"
     },
     {
       "path": "modules/lifecycle/db-grade.js",
@@ -5697,7 +5697,7 @@
     {
       "path": "modules/lifecycle/db-versions.js",
       "mode": "0000644",
-      "sha256": "8d8f8a16443e9f193829d8ac127b522e92984bcafc9a48a27c7deea5da2900b7"
+      "sha256": "7eaaafc9414bf77c12c57eefde02ddf1c67601f4b6b15ded3692bc3765ac036b"
     },
     {
       "path": "modules/lifecycle/db.js",
@@ -5947,7 +5947,7 @@
     {
       "path": "modules/lifecycle/routes/versions.js",
       "mode": "0000644",
-      "sha256": "a8cdb97b220c2de738396986e8cd326218f688a0277b4c75784420cfbdd0d369"
+      "sha256": "d69b98e63306141aa01d064b82a249a05b96aa010404cebd00edbc887107e52d"
     },
     {
       "path": "modules/lifecycle/routes/visuals.js",
@@ -6482,7 +6482,7 @@
     {
       "path": "modules/provisioning/provisioning.js",
       "mode": "0000644",
-      "sha256": "32083b07e4c676f9a68e0b78df3e5f5a0cea45fe0cb168a32fe1180165c99fbe"
+      "sha256": "0f82fbdf4838a7e72d4128c76b4da7f05ed4578b8a20c167c7fb2e95cb1e9237"
     },
     {
       "path": "modules/provisioning/rate-limit.js",
@@ -6507,7 +6507,7 @@
     {
       "path": "modules/provisioning/routes/provisioning.js",
       "mode": "0000644",
-      "sha256": "202dcfb416317eda72696455ace487d36021377d87a6c122df9561bc087939a8"
+      "sha256": "c83cec200215e9cb04446592e1aed32daf8e083142416bdc1f25d261f460d1cf"
     },
     {
       "path": "modules/provisioning/starter-bundles.js",
@@ -7767,12 +7767,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "3b0ebf2f1fb870085a40531295fb3c5989be5ab399e2493e43a1e3e844b0633c"
+      "sha256": "0edc0468c32498fd329ba23692832935f7524f2b4d24065d9a53cf583728af49"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "b4c1e3c5189ac7220af056624bdc0476a0d751c00aa76aba2e84416128280bc7"
+      "sha256": "32048e9ab629a14af9beee43dba2b8620a0e29db73a806dc66f21d08061a3c8b"
     },
     {
       "path": "public-docs/index.html",
@@ -8362,7 +8362,7 @@
     {
       "path": "scripts/gds/init.js",
       "mode": "0000644",
-      "sha256": "390df0043001a825bbd4709df767e8ef21089743b799fc9c638a5509e8222ae8"
+      "sha256": "1d63c1485820ad2e81e97979402eabd3829e86503f4c06318a251dc3a6874047"
     },
     {
       "path": "scripts/gds/install-git-hooks.js",
@@ -9532,7 +9532,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "406c218b56b011b4560887f2ae4e13f20e227fa4404e6763649e2eac2b0f5292"
+      "sha256": "538fc4afaf5a3f0da5eb4bcc3d99533cdf03cc5898163e6b8bcf8ca1584d14ec"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11382,7 +11382,7 @@
     {
       "path": "tests/init.mjs",
       "mode": "0000644",
-      "sha256": "21e5093a3b151e378a69249dab9b82845cec4d6c172d1a729cdc28512615a00b"
+      "sha256": "4a79313db6d6393415ace3e24f985be397156c10845b6543fdfbda3944ddeec0"
     },
     {
       "path": "tests/instance_config.mjs",
@@ -12132,7 +12132,7 @@
     {
       "path": "tests/provisioning_settings_apply.mjs",
       "mode": "0000644",
-      "sha256": "7fc80fc5576aba1dd10c0416899ade5fa2c9380ea8c1a995aaa99745aa56c29c"
+      "sha256": "a55a1c88958710a8b84048b88ba5d68b05e4489242a777852af8a2c9991462fb"
     },
     {
       "path": "tests/provisioning_settings_env.mjs",
@@ -13014,6 +13014,11 @@
       "mode": "0000644",
       "sha256": "f972971a1f668a085c5f5b4c5ccba616e4b77a3f3308f9a48af33e43ecd62a8c"
     },
+    {
+      "path": "tests/version_first_goal.mjs",
+      "mode": "0000644",
+      "sha256": "52e6115ac6af363db16358c1264b01d3295d013db1a986a9c21fdb8ba58f4119"
+    },
     {
       "path": "tests/version_literals.mjs",
       "mode": "0000644",
@@ -13037,7 +13042,7 @@
     {
       "path": "tests/versions_route.mjs",
       "mode": "0000644",
-      "sha256": "2a381bab380342e4fc556211d4821c85fdde1f676a6c5c6aa2421a89a573cd27"
+      "sha256": "1e439ad083cb9a345fafc952d9527979c59d9ef9ca875e4aa1eb602b5227dc22"
     },
     {
       "path": "tests/visibility_pull.mjs",

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

@@ -397,8 +397,8 @@ export interface PostVersionsIdCloseRequest { reason?: string; dispositions?: Re
 export interface PostVersionsIdCloseResponse { ok: boolean; version: unknown; applied: unknown; promoted: unknown; carried: unknown }
 export interface PostVersionsIdDoneWhenRequest { criterion_id: string; criterion_md: string; goal_id?: number; sort_order?: number }
 export interface PostVersionsIdDoneWhenResponse { ok: boolean; criterion: unknown }
-export interface PostVersionsRequest { id: string; name: string; status?: string; track?: string; done_when?: string; scope_doc_path?: string; criteria?: unknown[] }
-export interface PostVersionsResponse { version: unknown; criteria: unknown }
+export interface PostVersionsRequest { id: string; name: string; status?: string; track?: string; done_when?: string; scope_doc_path?: string; criteria?: unknown[]; first_goal?: Record<string, unknown> }
+export interface PostVersionsResponse { version: unknown; goal: unknown; criteria: unknown }
 export interface PutGovernmentRanksRankKeyPermissionsPermissionKeyResponse { ok: boolean; rank_key: unknown; permission_key: unknown; granted: unknown }
 export interface PutMingleOptInRequest { opted_in: boolean }
 export interface PutMingleOptInResponse { opted_in: unknown; updated_at: unknown }

package/docs/api/openapi.json

@@ -12149,7 +12149,7 @@
           "provisioning"
         ],
         "summary": "PATCH /provisioning/instances/:id/settings",
-        "description": "PATCH /provisioning/instances/:id/settings — change a project's settings. Body: any subset of the known keys; strict validation refuses unknown keys and off-vocabulary values. rank: any authenticated builder (own resource; archon may change any — the override is audited via the event's actor). The platform's row is updated first; then, for an ACTIVE instance on a shape the runner can reach, a 'settings-apply' intent is enqueued (task 1003140): the control-plane runner patches the instance's web.env in place and RESTARTS it, because the branding pack is memoized for the process lifetime. A save that changes nothing neither writes nor restarts. The response is a request receipt — `saved` is what the platform now stores, and `push` { queued, restart, reachable, message } says whether a restart was queued and when the value takes effect — never a claim the instance already runs it; a client reads that back from the instance's own public GET /instance manifest (brand.project). 409 intent_conflict (details.recorded: true) when the open slot is held by other work — the change IS saved.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "description": "PATCH /provisioning/instances/:id/settings — change a project's settings. Body: any subset of the known keys; strict validation refuses unknown keys and off-vocabulary values. rank: any authenticated builder (own resource; archon may change any — the override is audited via the event's actor). The platform's row is updated first; then, for an ACTIVE instance on a shape the runner can reach, a 'settings-apply' intent is enqueued (task 1003140): the control-plane runner patches the instance's web.env in place and RESTARTS it, because the branding pack is memoized for the process lifetime. A save that changes nothing neither writes nor restarts. The response is a request receipt — `saved` is what the platform now stores, and `push` { queued, restart, reachable, message } says whether a restart was queued and when the value takes effect — never a claim the instance already runs it; a client reads that back from the instance's own public GET /instance manifest (brand.project). 409 intent_conflict (details.recorded: true) when the open slot is held by other work — the change IS saved. A save whose push did not get carried (that 409, or an enqueue that threw) marks the push OWED, which is what makes the \"send it again\" both of those name actually re-queue instead of hitting the no-op \"No change\" branch (task 1003524).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
         "x-rank": "any-builder",
         "x-source": "modules/provisioning/routes/provisioning.js",
         "parameters": [
@@ -22791,6 +22791,9 @@
           "criteria": {
             "type": "array",
             "maxItems": 100
+          },
+          "first_goal": {
+            "type": "object"
           }
         },
         "required": [
@@ -22803,10 +22806,12 @@
         "type": "object",
         "properties": {
           "version": {},
+          "goal": {},
           "criteria": {}
         },
         "required": [
           "version",
+          "goal",
           "criteria"
         ]
       },

package/docs/api-reference.md

@@ -629,7 +629,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/versions` | `public` | — | read-only version list; mirrors /public/versions. |
-| POST | `/api/bongos/versions` | `archon` | `id`, `name`, `status`, `track`, `done_when`, `scope_doc_path`, `criteria` | POST /versions — create a version + its done-when criteria in one call. |
+| POST | `/api/bongos/versions` | `archon` | `id`, `name`, `status`, `track`, `done_when`, `scope_doc_path`, `criteria`, `first_goal` | POST /versions — create a version + its done-when criteria in one call. |
 | POST | `/api/bongos/versions/:id/close` | `archon` | `reason`, `dispositions` | POST /versions/:id/close — the move a version has never had (BV1.R12, task 1003599, goal 1000086, ADR 0250 D5, ADR 0263 §5). |
 | GET | `/api/bongos/versions/:id/done-when` | `public` | — | Public: the status dashboard (status.<apex>) fetches this every 60s alongside other public/* surfaces. |
 | POST | `/api/bongos/versions/:id/done-when` | `metic+archon` | `criterion_id`, `criterion_md`, `goal_id`, `sort_order` | Auth (Metic+, then the goal's own authority): create a done-when criterion at RUNTIME. |

package/docs/module-api-changelog.md

@@ -1811,5 +1811,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.674 with no explicit bump. run 34639371461. (task 1002620)
   1.19.676 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.675 with no explicit bump. run 34645751352. (task 1002620)
+  1.19.677 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.676 with no explicit bump. run 34650610723. (task 1002620)
+  1.19.678 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.677 with no explicit bump. run 34653458123. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/db-goals.js

@@ -65,11 +65,17 @@ const MEMBERSHIP_REQUEST_COLS =
 // state R03 exists to prevent, and a second round-trip can fail after the goal
 // lands. Pass null (the normal path) and no admission row is written at all, so
 // the presence of a row always means the gate was actually overridden.
+//
+// IT CAN RUN INSIDE THE CALLER'S TRANSACTION (deps.client), the same seam
+// ensureMaintenanceGoal below already takes and for the same reason: a version's
+// FIRST goal is created by db.createVersion in the transaction that creates the
+// version (task 1003701), and a goal committed on its own connection would
+// survive a rolled-back version create as a goal pointing at nothing.
 async function createGoal(
   { versionId, title, subtitle = null, description = null, scopeModules = [], status = 'open', createdBy = null, categoryId = null, admission = null },
   deps = {}
 ) {
-  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const activePool = deps.client || ((deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool);
   const { rows } = await activePool.query(
     `WITH next_order AS (
        SELECT COALESCE(MAX(sort_order) + 1, 0) AS n FROM goals WHERE version_id = $1

package/modules/lifecycle/db-versions.js

@@ -15,6 +15,10 @@ const { pool, withTx } = api;
 const doneWhen = require('./done-when.js');
 const { nonTerminalSql } = require('./task-status');
 const { SMOKE_NOT_LIKE } = require('./db-shared.js');
+// db-goals.js does NOT require this file, so this direction adds no require cycle
+// (fitness pins the count). createVersion needs it to seed a version's FIRST goal
+// in the same transaction — task 1003701.
+const { createGoal } = require('./db-goals.js');
 
 async function listVersions() {
   const { rows } = await pool.query(
@@ -130,10 +134,35 @@ async function versionsWithStatus(status, deps = {}) {
   return rows;
 }
 
-async function createVersion({ id, name, status = 'planning', track = 'product', scopeDocPath = null, doneWhen = null, criteria = [] }) {
+// createVersion — a version, its FIRST GOAL, and its done-when criteria, in one
+// transaction (task 1003701).
+//
+// THE GOAL IS NOT OPTIONAL DECORATION; it closes a chicken-and-egg that made a
+// fresh instance unseedable. `bongos init` creates its version at 'building', and
+// two rules then met in the middle: BV1.R11 refuses a task with no goal_id, and
+// R03 refuses a new goal on a version that is no longer 'planning'. So init could
+// file no task, and could create no goal to file them under — proved against live
+// on 2026-09-07. Creating the version's own first goal WITH the version is the
+// way out that spends no escape hatch: this is not scope GROWTH on a closed
+// version (what R03 guards), it is the version's initial scope, and it exists
+// before the version is visible to anyone.
+//
+// It also fixes the quieter defect underneath. Since ADR 0086 criteria live under
+// goals, and since migration 160 the catch-all goals were created by a one-shot
+// backfill with no trigger behind it — so every version created afterwards got
+// goal-less criteria, and ADR 0183 criteria satisfy themselves off LINKED tasks.
+// Criteria nobody can link a task to can never close. Stamping goal_id here is
+// what gives them something to hang from.
+async function createVersion({ id, name, status = 'planning', track = 'product', scopeDocPath = null, doneWhen = null, criteria = [], firstGoal = null, createdBy = null }, deps = {}) {
   // versions.track is NOT NULL with no DB default (migration 003) — omitting it
   // here made every create 500. An instance's first version is its product
   // track, so that's the default; 'internal' is the platform's own track.
+  //
+  // deps.pool is the module's existing test seam (listVersions, versionProgress):
+  // honoured ONLY under NODE_ENV=test, so production can never be pointed at an
+  // injected pool. It is threaded into withTx so the whole transaction — version,
+  // goal and criteria — runs on it.
+  const txPool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
   return withTx(async (client) => {
     const { rows } = await client.query(
       `INSERT INTO versions (id, name, status, track, scope_doc_path, done_when)
@@ -142,21 +171,32 @@ async function createVersion({ id, name, status = 'planning', track = 'product',
       [id, name, status, track, scopeDocPath, doneWhen]
     );
     const version = rows[0];
+    // The first goal. Titled for the version it opens unless the caller names one —
+    // a version's opening scope is the version, until someone splits it. Rides the
+    // SAME client, so a failure anywhere below rolls the goal back with everything
+    // else and never leaves a goal pointing at a version that does not exist.
+    const goal = await createGoal({
+      versionId: id,
+      title: (firstGoal && String(firstGoal.title || '').trim()) || name || id,
+      description: (firstGoal && firstGoal.description) || doneWhen || null,
+      createdBy,
+    }, { client });
     const createdCriteria = [];
     let i = 0;
     for (const c of (criteria || [])) {
       const { rows: cr } = await client.query(
-        `INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, sort_order)
-              VALUES ($1, $2, $3, $4)
+        `INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, sort_order, goal_id)
+              VALUES ($1, $2, $3, $4, $5)
          ON CONFLICT (version_id, criterion_id) DO NOTHING
-         RETURNING id, version_id, criterion_id, criterion_md, sort_order, satisfied`,
-        [id, c.criterion_id, c.criterion_md, Number.isFinite(c.sort_order) ? c.sort_order : (i + 1) * 10]
+         RETURNING id, version_id, criterion_id, criterion_md, sort_order, satisfied, goal_id`,
+        [id, c.criterion_id, c.criterion_md, Number.isFinite(c.sort_order) ? c.sort_order : (i + 1) * 10,
+         goal ? goal.id : null]
       );
       if (cr[0]) createdCriteria.push(cr[0]);
       i++;
     }
-    return { version, criteria: createdCriteria };
-  });
+    return { version, goal: goal || null, criteria: createdCriteria };
+  }, { pool: txPool });
 }
 
 // currentBuildingVersionId — the version new work defaults into, or null when

package/modules/lifecycle/routes/versions.js

@@ -103,6 +103,8 @@ module.exports = function buildVersionsRouter() {
       done_when: { type: 'string', maxLength: 8000 },
       scope_doc_path: { type: 'string', maxLength: 256 },
       criteria: { type: 'array', maxItems: 100 },
+      // The version's first goal (task 1003701) — { title?, description? }, both optional.
+      first_goal: { type: 'object' },
     })) return;
     const body = req.body || {};
     const id = String(body.id).trim();
@@ -177,13 +179,23 @@ module.exports = function buildVersionsRouter() {
       });
     }
 
-    let version, created;
+    // The version's FIRST GOAL (task 1003701). Optional and free-form: name it and
+    // the version opens with that goal, omit it and the goal carries the version's
+    // own name. It is created in createVersion's transaction, not here, because a
+    // goal that outlived a rolled-back version create would point at nothing.
+    const fg = body.first_goal && typeof body.first_goal === 'object' ? body.first_goal : null;
+    let version, goal, created;
     try {
-      ({ version, criteria: created } = await db.createVersion({
+      ({ version, goal, criteria: created } = await db.createVersion({
         id, name, status, track,
         doneWhen: body.done_when ?? null,
         scopeDocPath: body.scope_doc_path ?? null,
         criteria,
+        firstGoal: fg,
+        // The creator OWNS the goal (createGoal's rule — created_by plus a 'lead'
+        // member row). Null for an unauthenticated/system create, which is the
+        // migration-160 posture: no owner, Archons act as one.
+        createdBy: (req.builder && req.builder.id) || null,
       }));
     } catch (err) {
       // TOCTOU: the getVersion() pre-check above runs outside the insert
@@ -222,7 +234,11 @@ module.exports = function buildVersionsRouter() {
       }
       throw err;
     }
-    res.status(201).json({ version, criteria: created });
+    // `goal` is returned because a caller that just made a version CANNOT file a
+    // task without one (BV1.R11) and cannot create one afterwards (R03) — so the
+    // id has to come back with the version or the caller is stuck. This is the
+    // half `bongos init` was missing (task 1003701).
+    res.status(201).json({ version, goal: goal || null, criteria: created });
   }, { errorCode: 'create_version_failed' }));
 
 

package/modules/provisioning/provisioning.js

@@ -441,6 +441,12 @@ ${lines}
 `;
 }
 
+// The reserved settings-jsonb key settingsPushOwed/recordSettingsPushOwed use
+// (task 1003524). Deliberately NOT in SETTINGS_VOCAB or PLANET_VOCAB — it is the
+// platform's own bookkeeping, not a setting an owner declares, and the test
+// asserts it stays out of both so it can never start projecting as one.
+const SETTINGS_PUSH_OWED_KEY = 'push_owed';
+
 // The instance's EFFECTIVE settings: the defaults overlaid with the stored,
 // on-vocabulary keys. An off-vocabulary or unknown stored value falls back to
 // its default rather than leaking into the read surface. PURE.
@@ -466,6 +472,30 @@ function planetChoice(row) {
   return out;
 }
 
+// Is a POLICY settings push OWED to this instance (task 1003524)? Set when the
+// row was written but its push demonstrably did not get carried: the open slot
+// was held by other work (409 intent_conflict), or the enqueue itself threw.
+// Both of those answer the owner "send it again" — and without this marker that
+// remedy is a NO-OP, because the re-send is by definition unchanged and takes
+// the "No change" branch, leaving the saved value stranded on the platform. (The
+// only way out was toggling to a third value and back.)
+//
+// It lives as a RESERVED key in the settings jsonb rather than a column so it
+// costs no migration — the provisioning_009 rationale, which is why that column
+// is jsonb in the first place. It can neither leak nor be client-written:
+// effectiveSettings / planetChoice / settingsEnvVars project ONLY vocabulary
+// keys, and the route builds its patch only from settingKeys.
+//
+// error_note is the sibling marker and the two do not overlap: that one latches
+// a push that WAS queued and then failed (F19), this one a push that was never
+// queued at all. Together they make "send it again" true on every branch that
+// says it. PURE.
+function settingsPushOwed(row) {
+  const stored = row && row.settings && typeof row.settings === 'object' && !Array.isArray(row.settings)
+    ? row.settings : {};
+  return stored[SETTINGS_PUSH_OWED_KEY] === true;
+}
+
 // A description as it may be STORED: trimmed, collapsed of runaway whitespace,
 // capped, and empty-means-absent. Returns null for anything that isn't real prose,
 // because null is what leaves the project dark-matter — an empty string stored in a
@@ -669,6 +699,25 @@ async function updateInstanceSettings(db, id, patch) {
   return rows[0] || null;
 }
 
+// Mark (or clear) the owed-push marker settingsPushOwed reads (task 1003524).
+// Same narrowness rule as recordDnsNote / clearErrorNote: no `status`, and no
+// `updated_at` — this is the platform's own bookkeeping, and bumping updated_at
+// would reshuffle the owner's card ordering (listInstancesForOwner orders by it)
+// for a write the owner did not make. Clearing DELETES the key rather than
+// storing false, so a row that never owed a push is byte-identical to one whose
+// debt was settled.
+async function recordSettingsPushOwed(db, id, owed) {
+  const { rows } = await db.query(
+    `UPDATE provisioning_instances
+        SET settings = CASE WHEN $2::boolean
+              THEN settings || $3::jsonb
+              ELSE settings - $4::text END
+      WHERE id = $1 RETURNING id, settings`,
+    [id, !!owed, JSON.stringify({ [SETTINGS_PUSH_OWED_KEY]: true }), SETTINGS_PUSH_OWED_KEY]
+  );
+  return rows[0] || null;
+}
+
 // Fill in (or change) the project-detail answers AFTER creation — the other half
 // of "skippable" (task 1002334). Skipping the step at creation is a supported
 // default, but it is only a default and not a dead end if there is a way back; this
@@ -1290,6 +1339,7 @@ module.exports = {
   // pure
   isValidSlug, costEstimateUsd, publicInstance, normalizeHostname,
   defaultDomainForSlug, isReservedHostname, effectiveSettings, planetChoice,
+  settingsPushOwed,
   normalizeDescription, normalizeProjectDetail, projectDetailPatch, projectDetail,
   // pure — GitHub App Manifest flow (task 2080)
   githubAppName, buildGithubAppManifest, manifestPostUrl, publicGithubApp,
@@ -1298,6 +1348,8 @@ module.exports = {
   getInstanceById, getInstanceBySlug, getInstanceByDomain, listInstancesForOwner, listAllInstances,
   // data access — verification overlay (task 1002696)
   listActiveInstancesForLiveness, recordLivenessProbe, recordDnsNote, clearErrorNote,
+  // data access — the owed-push marker (task 1003524)
+  recordSettingsPushOwed,
   createInstance, setInstanceStatus, updateInstanceDomain, updateInstanceSettings, updateInstanceDetail,
   createInstance, setInstanceStatus, updateInstanceDomain, clearReleasedDomains, updateInstanceSettings,
   enqueueIntent, enqueueTeardown, enqueueSettingsApply, enqueueRestart, getOpenIntent, claimNextIntent, resolveIntent,

package/modules/provisioning/routes/provisioning.js

@@ -853,7 +853,10 @@ module.exports = function provisioningRoutes() {
   // and when the value takes effect — never a claim the instance already runs
   // it; a client reads that back from the instance's own public GET /instance
   // manifest (brand.project). 409 intent_conflict (details.recorded: true) when
-  // the open slot is held by other work — the change IS saved.
+  // the open slot is held by other work — the change IS saved. A save whose push
+  // did not get carried (that 409, or an enqueue that threw) marks the push OWED,
+  // which is what makes the "send it again" both of those name actually re-queue
+  // instead of hitting the no-op "No change" branch (task 1003524).
   router.patch('/provisioning/instances/:id/settings', auth.requireBuilder, async (req, res) => {
     const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
     if (!id) return;
@@ -898,7 +901,13 @@ module.exports = function provisioningRoutes() {
       const policyKeys = Object.keys(provisioning.SETTINGS_VOCAB);
       const policyTouched = policyKeys.some((k) => patch[k] !== undefined);
       const policyChanged = policyKeys.some((k) => patch[k] !== undefined && before[k] !== patch[k]);
-      const policyResent = !!inst.error_note && policyTouched;
+      // A push is OWED when the last save's push did not get carried — a queued
+      // push that RAN and failed (error_note, the F19 re-kick), or one never queued
+      // at all (the 409 below, or an enqueue that threw; task 1003524). Both answer
+      // "send it again", and folding the second in is what makes that sentence
+      // true: the re-send is unchanged, so it would otherwise hit "No change".
+      const pushOwed = provisioning.settingsPushOwed(inst);
+      const policyResent = (!!inst.error_note || pushOwed) && policyTouched;
       const updated = changed ? await provisioning.updateInstanceSettings(pool, id, patch) : inst;
       if (changed) {
         await provisioning.recordEvent(pool, {
@@ -947,14 +956,25 @@ module.exports = function provisioningRoutes() {
         catch (err) {
           // The value IS saved — say so; a 500 here would deny a durable write.
           log.error('[provisioning] PATCH /provisioning/instances/:id/settings enqueue', err);
+          // The remedy this sentence names has to WORK (task 1003524): nothing is
+          // going to carry the saved value, so record the debt. Best-effort — a failed
+          // marker write must never turn a durable settings write into a 500.
+          await provisioning.recordSettingsPushOwed(pool, id, true).catch(() => {});
           push = receipt({ queued: false, restart: true, message: 'Saved, but the restart could not be queued just now — send it again to apply it.' });
         }
         if (r && r.conflict) {
+          // Saved, but the slot is held by work that will not carry this change, so
+          // "send it again once that settles" has to re-queue when they do (task 1003524).
+          await provisioning.recordSettingsPushOwed(pool, id, true).catch(() => {});
           return res.fail('intent_conflict', { status: 409,
             message: `The change was saved, but a '${r.intent.action}' run is currently ${r.intent.state} for this project — send it again once that settles to apply it.`,
             details: { action: r.intent.action, state: r.intent.state, recorded: true } });
         }
         if (r) {
+          // A push is now in hand — fresh, or a PENDING one that has not read the row
+          // yet — so either way it carries the current settings. Only written when
+          // there IS a debt, so the hot path stays a single UPDATE.
+          if (pushOwed) await provisioning.recordSettingsPushOwed(pool, id, false).catch(() => {});
           push = receipt({ queued: r.created, restart: true, message: r.created
             ? 'Saved. Your project will restart to pick this up — until then it keeps its current setting.'
             : 'Saved. A restart is already queued for this project and will carry this change.' });

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.676",
+  "version": "1.19.678",
   "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/scripts/gds/init.js

@@ -668,8 +668,30 @@ async function seedViaApi(spec, { dryRun, log = console.log, api = apiCall } = {
   if (!vres.ok && vres.status !== 409) {
     throw new Error(`POST /versions failed (${vres.status}): ${JSON.stringify(vres.data)}`);
   }
-  if (vres.status === 409) log(`  • version ${vp.id} already exists — continuing.`);
-  else log(`  ✓ created version ${vp.id} + 1 done-when goal`);
+  // The version's first goal — every task below needs its id (BV1.R11 refuses a
+  // goal-less task, and R03 refuses creating a goal on a version that is already
+  // 'building', which is what versionPayload makes). POST /versions now returns it
+  // alongside the version (task 1003701); on the 409 re-run path the version is
+  // already there, so read its goals back instead.
+  let goalId = vres.ok && vres.data && vres.data.goal ? vres.data.goal.id : null;
+  if (vres.status === 409) {
+    log(`  • version ${vp.id} already exists — continuing.`);
+    const gres = await api('GET', `/api/gds/goals?version=${encodeURIComponent(vp.id)}`);
+    const goals = gres.ok ? (Array.isArray(gres.data) ? gres.data : (gres.data && gres.data.goals) || []) : [];
+    const open = goals.find((g) => g && g.status === 'open' && !g.is_maintenance) || goals.find((g) => g && g.status === 'open');
+    goalId = open ? open.id : null;
+  } else {
+    log(`  ✓ created version ${vp.id} + its first goal`);
+  }
+  // Fail LOUD rather than filing a wave of tasks the server will refuse one by one:
+  // with no goal every POST below returns 400 goal_id_required, and the run would
+  // report a pile of identical failures instead of the single reason behind them.
+  if (goalId == null) {
+    throw new Error(
+      `could not determine a goal for version ${vp.id} — every task needs one (goal_id_required). ` +
+      `The version exists but has no open goal to file under; create one and re-run.`
+    );
+  }
   const criterionId = vp.criteria[0].criterion_id;
 
   // A tracked kickoff/starter task (status ready). Returns true on success.
@@ -681,7 +703,7 @@ async function seedViaApi(spec, { dryRun, log = console.log, api = apiCall } = {
   const postTask = async (t, extra = {}) => {
     attempted++;
     const res = await api('POST', '/api/gds/tasks', {
-      version_id: vp.id, title: t.title, description: t.description || '', status: 'ready',
+      version_id: vp.id, goal_id: goalId, title: t.title, description: t.description || '', status: 'ready',
       kind: t.kind || 'infra', discipline: t.discipline || 'engineer', source: 'bongos-init', ...extra,
     });
     if (!res.ok) failures.push({ title: t.title, status: res.status, detail: JSON.stringify(res.data) });

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.676'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.678'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/init.mjs

@@ -558,11 +558,21 @@ test('writeConfigs (greenfield, dry-run): mints no README', () => {
 // A fake apiCall that records calls and returns a configured response per path
 // substring (default: 200 ok). Lets us exercise the live seedViaApi branching
 // (POST the request; 404/error → fall back to the manual task) with no server.
+// POST /versions answers with the version's FIRST GOAL since task 1003701, and
+// seedViaApi cannot file a single task without its id (BV1.R11 refuses a task with
+// no goal_id, and R03 refuses creating one on a version that is already
+// 'building'). So the default version response carries one — a stub that omitted
+// it would not be a simpler fixture, it would be a server that cannot be seeded,
+// which is the bug this all fixes. FAKE_GOAL_ID is asserted on the task POSTs.
+const FAKE_GOAL_ID = 4242;
 function fakeApi(responses = []) {
   const calls = [];
   const api = async (method, path, body) => {
     calls.push({ method, path, body });
     for (const [match, res] of responses) if (path.includes(match)) return res;
+    if (path.endsWith('/versions')) {
+      return { ok: true, status: 201, data: { version: { id: (body && body.id) || 'V1' }, goal: { id: FAKE_GOAL_ID, status: 'open' }, criteria: [] } };
+    }
     return { ok: true, status: 200, data: {} };
   };
   api.calls = calls;
@@ -623,6 +633,9 @@ async function runSeedTests() {
     const calls = [];
     const api = async (method, path, body) => {
       calls.push({ method, path, body });
+      if (path.endsWith('/versions')) {
+        return { ok: true, status: 201, data: { version: { id: body.id }, goal: { id: FAKE_GOAL_ID, status: 'open' }, criteria: [] } };
+      }
       if (path.endsWith('/tasks') && /instance look/i.test((body && body.title) || '')) {
         return { ok: false, status: 400, data: { error: 'validation_failed' } };
       }
@@ -639,6 +652,61 @@ async function runSeedTests() {
     assert.match(text, new RegExp(`⚠ filed ${out.created} of ${out.attempted}`), 'summary is a warning with actual-vs-expected counts, not a green check');
   });
 
+  // ── the version's first goal (task 1003701) ──────────────────────────────
+  // `bongos init` could not seed a new instance at all: versionPayload creates the
+  // version at 'building', BV1.R11 refuses a task with no goal_id, and R03 refuses
+  // creating a goal on a version that is no longer 'planning'. Both halves were
+  // proved against live on 2026-09-07 — every starter and kickoff task 400'd.
+
+  await at('seedViaApi: EVERY task POST carries the goal_id the version create returned', async () => {
+    const api = fakeApi();
+    const out = await init.seedViaApi(provSpec({}), { log: () => {}, api });
+    const taskPosts = api.calls.filter((c) => c.path.endsWith('/tasks'));
+    assert.ok(taskPosts.length > 0, 'there are tasks to check');
+    for (const c of taskPosts) {
+      assert.equal(c.body.goal_id, FAKE_GOAL_ID, `${c.body.title} filed under the version's first goal`);
+    }
+    assert.equal(out.failures.length, 0, 'and none of them is refused');
+  });
+
+  await at('seedViaApi: a version create that answers with NO goal fails loudly, before filing anything', async () => {
+    // Fail closed and say the real reason ONCE. Without this every task POST comes
+    // back 400 goal_id_required and the run reports a pile of identical failures
+    // instead of the single cause behind them.
+    const api = fakeApi([['/versions', { ok: true, status: 201, data: { version: { id: 'V1' }, criteria: [] } }]]);
+    await assert.rejects(
+      () => init.seedViaApi(provSpec({}), { log: () => {}, api }),
+      /goal/i,
+      'the failure names the goal, not a task'
+    );
+    assert.equal(api.calls.filter((c) => c.path.endsWith('/tasks')).length, 0, 'nothing was filed');
+  });
+
+  await at('seedViaApi: on a 409 re-run it reads the goal back, preferring an ordinary open goal over the maintenance one', async () => {
+    const api = fakeApi([
+      ['/versions', { ok: false, status: 409, data: { error: 'version_exists' } }],
+      ['/goals', { ok: true, status: 200, data: { goals: [
+        { id: 900, status: 'open', is_maintenance: true },
+        { id: 901, status: 'achieved', is_maintenance: false },
+        { id: 902, status: 'open', is_maintenance: false },
+      ] } }],
+    ]);
+    const out = await init.seedViaApi(provSpec({}), { log: () => {}, api });
+    const taskPosts = api.calls.filter((c) => c.path.endsWith('/tasks'));
+    assert.ok(taskPosts.length > 0);
+    for (const c of taskPosts) assert.equal(c.body.goal_id, 902, 'the ordinary open goal, not the maintenance bucket and not the achieved one');
+    assert.equal(out.failures.length, 0);
+  });
+
+  await at('seedViaApi: a 409 re-run on a version with no open goal fails loudly too', async () => {
+    const api = fakeApi([
+      ['/versions', { ok: false, status: 409, data: { error: 'version_exists' } }],
+      ['/goals', { ok: true, status: 200, data: { goals: [{ id: 900, status: 'archived', is_maintenance: false }] } }],
+    ]);
+    await assert.rejects(() => init.seedViaApi(provSpec({}), { log: () => {}, api }), /goal/i);
+    assert.equal(api.calls.filter((c) => c.path.endsWith('/tasks')).length, 0, 'nothing was filed');
+  });
+
   await at('seedViaApi: no provisioning block → no provisioning POST, topo stays a normal kickoff task', async () => {
     const spec = init.normalizeSpec({ identity: { productName: 'X Co' }, repo: { owner: 'o', name: 'n' },
       firstAdmin: 'x', version: { id: 'V1', name: 'V1', done_when: 'ship' } });

package/tests/provisioning_settings_apply.mjs

@@ -132,7 +132,19 @@ let enqueueCalls = [];
 let enqueueResult = null;      // what enqueueSettingsApply reports (null → created:true)
 let enqueueThrows = null;      // an Error to throw from enqueueSettingsApply
 let events = [];
+let owedCalls = [];           // every recordSettingsPushOwed(id, owed) the route makes
 provisioning.getInstanceById = async (_db, id) => (instance ? { ...instance, id } : null);
+// The marker is a reserved key in the SAME settings jsonb, so the stub mutates the
+// fixture the way the real UPDATE does — that is what lets a test re-send against
+// the row its own previous save left behind.
+const realRecordSettingsPushOwed = provisioning.recordSettingsPushOwed;
+provisioning.recordSettingsPushOwed = async (_db, id, owed) => {
+  owedCalls.push({ id, owed });
+  const next = { ...(instance.settings || {}) };
+  if (owed) next.push_owed = true; else delete next.push_owed;
+  instance = { ...instance, settings: next };
+  return { id, settings: next };
+};
 provisioning.updateInstanceSettings = async (_db, id, patch) => {
   updateCalls.push({ id, patch, enqueuedSoFar: enqueueCalls.length });
   instance = { ...instance, settings: { ...(instance.settings || {}), ...patch } };
@@ -196,6 +208,7 @@ function reset({ inst, as } = {}) {
   enqueueResult = null;
   enqueueThrows = null;
   events = [];
+  owedCalls = [];
 }
 // every receipt carries the same four keys, and never a duration promise
 function receiptShape(push, { queued, restart, reachable }) {
@@ -354,6 +367,122 @@ await ta('ACTIVE dedicated: stored, NO intent, reachable:false, restart:true (a
   assert.doesNotMatch(r.body.push.message, /web\.env/, 'no file the owner has never seen');
 });
 
+console.log("\nthe owed push — making \"send it again\" true (task 1003524):");
+
+// THE HEADLINE, end to end, exactly as the bug was reported: the owner saves
+// visibility (queued), saves joinability one card below while the first push is
+// RUNNING (409), that run settles, and they do what the 409 told them to — re-send
+// the SAME joinability. Before this fix the re-send was unchanged, so it took the
+// "No change" branch and queued nothing: the value sat on the platform forever and
+// the only way out was toggling to a third value and back.
+await ta('save A queues → save B 409s while A RUNS → A settles → the UNCHANGED re-send of B queues a NEW push', async () => {
+  reset();
+
+  // 1. visibility: a clean queue.
+  let r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated' });
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(r.body.push.queued, true);
+  assert.equal(enqueueCalls.length, 1);
+
+  // 2. joinability, while that push is RUNNING — saved, but nothing carries it.
+  enqueueResult = { intent: { id: 5, action: 'settings-apply', state: 'running' }, created: false, conflict: 'open_intent' };
+  r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
+  assert.equal(r.status, 409, r.raw);
+  assert.equal(r.body.error.details.recorded, true, 'the value IS stored');
+  assert.match(r.body.error.message, /send it again once that settles/i, 'the remedy this test exists to make true');
+  assert.deepEqual(owedCalls, [{ id: 18, owed: true }], 'the debt is recorded at the moment the push is refused');
+
+  // 3. that run settles; the owner re-sends the SAME joinability.
+  enqueueResult = null;               // the slot is free again
+  const enqueuedBefore = enqueueCalls.length;
+  const writesBefore = updateCalls.length;
+  r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
+
+  assert.equal(r.status, 200, r.raw);
+  assert.doesNotMatch(r.body.push.message, /No change/, 'the whole bug: the remedy used to be a no-op');
+  assert.equal(r.body.push.queued, true, 'a NEW push is queued');
+  assert.equal(enqueueCalls.length, enqueuedBefore + 1, 'exactly one new intent');
+  assert.equal(updateCalls.length, writesBefore, 'nothing re-written — the value was already stored in step 2');
+  assert.deepEqual(owedCalls[owedCalls.length - 1], { id: 18, owed: false }, 'and the debt is settled');
+  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'open', visibility: 'public', join_grant: 'full' },
+    'the value that finally ships is the one the owner saved');
+});
+
+await ta('an enqueue that THROWS records the debt too — its "send it again" is the same sentence', async () => {
+  reset();
+  enqueueThrows = new Error('db down');
+  const r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
+  assert.equal(r.status, 200, r.raw);
+  assert.match(r.body.push.message, /send it again/i);
+  assert.deepEqual(owedCalls, [{ id: 18, owed: true }]);
+
+  // and the re-send it names now works
+  enqueueThrows = null;
+  const r2 = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
+  assert.equal(r2.body.push.queued, true, 'the unchanged re-send queues');
+  assert.equal(updateCalls.length, 1, 'still only the original write');
+});
+
+await ta('a push already in hand settles the debt; with no debt outstanding nothing is written (the hot path stays one UPDATE)', async () => {
+  // an identical PENDING push (created:false, no conflict) has not read the row yet,
+  // so it carries this change — the debt is settled just as for a fresh intent.
+  reset({ inst: { ...ACTIVE, settings: { platform_visibility: 'gated', push_owed: true } } });
+  enqueueResult = { intent: { id: 5, action: 'settings-apply', state: 'pending' }, created: false };
+  const r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated' });
+  assert.equal(r.status, 200, r.raw);
+  assert.deepEqual(owedCalls, [{ id: 18, owed: false }], 'a pending push carries it — debt settled');
+
+  reset();
+  await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated' });
+  assert.deepEqual(owedCalls, [], 'no debt, no bookkeeping write');
+});
+
+await ta('an owed push is a POLICY debt: a planet-only re-send neither re-kicks it nor clears it', async () => {
+  reset({ inst: { ...ACTIVE, settings: { planet_template: 'bead-obsidian-tint', push_owed: true } } });
+  const r = await patch('/provisioning/instances/18/settings', { planet_template: 'bead-obsidian-tint' });
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(enqueueCalls.length, 0, 'the planet reaches no instance, so it re-kicks nothing');
+  assert.deepEqual(owedCalls, [], 'and the policy debt survives, still owed');
+  assert.equal(provisioning.settingsPushOwed(instance), true);
+});
+
+await ta('the marker never leaks: not a vocabulary key, not in any projection, and a client cannot write it', async () => {
+  const row = { settings: { push_owed: true, joinability: 'open', planet_template: 'bead-obsidian-tint' } };
+  assert.equal(provisioning.settingsPushOwed(row), true);
+  assert.ok(!('push_owed' in provisioning.SETTINGS_VOCAB), 'not a policy setting');
+  assert.ok(!('push_owed' in provisioning.PLANET_VOCAB), 'not a planet setting');
+  assert.ok(!('push_owed' in provisioning.effectiveSettings(row)), 'never in the saved projection');
+  assert.ok(!('push_owed' in provisioning.planetChoice(row)), 'never in the planet projection');
+  const env = provisioning.settingsEnvVars(row, 'BONGOS');
+  for (const k of Object.keys(env)) assert.doesNotMatch(k, /PUSH_OWED/, 'never reaches the instance web.env');
+  assert.equal(provisioning.settingsPushOwed({ settings: {} }), false);
+  assert.equal(provisioning.settingsPushOwed({ settings: { push_owed: 'yes' } }), false, 'strictly true, never truthy');
+  assert.equal(provisioning.settingsPushOwed(null), false);
+
+  // strict validation refuses it on the way in, so it is server-only by construction
+  reset();
+  const r = await patch('/provisioning/instances/18/settings', { push_owed: true });
+  assert.equal(r.status, 400, r.raw);
+  assert.equal(updateCalls.length, 0);
+});
+
+await ta('recordSettingsPushOwed writes NOTHING but the marker — no status, no updated_at, and clearing deletes the key', async () => {
+  const seen = [];
+  const db = { query: async (sql, params) => { seen.push({ sql, params }); return { rows: [{ id: 18, settings: {} }] }; } };
+  await realRecordSettingsPushOwed(db, 18, true);
+  await realRecordSettingsPushOwed(db, 18, false);
+  for (const c of seen) {
+    assert.match(c.sql, /UPDATE provisioning_instances/);
+    assert.doesNotMatch(c.sql, /updated_at/, 'bookkeeping must not reshuffle the owner\'s card order');
+    assert.doesNotMatch(c.sql, /status/, 'and must not touch the lifecycle');
+    assert.match(c.sql, /settings - \$4::text/, 'clearing DELETES the key rather than storing false');
+    assert.equal(c.params[0], 18);
+  }
+  assert.equal(seen[0].params[1], true);
+  assert.equal(seen[1].params[1], false);
+  assert.equal(seen[0].params[3], 'push_owed', 'the reserved key, passed as a parameter not interpolated');
+});
+
 console.log('\nthe walls that did not move:');
 
 await ta("another builder's PATCH → 404; nothing stored, nothing queued", async () => {

package/tests/version_first_goal.mjs

@@ -0,0 +1,165 @@
+// tests/version_first_goal.mjs
+//
+// A version is created WITH its first goal, and its done-when criteria hang off
+// that goal (task 1003701, goal 1000106).
+//
+// THE BUG. `bongos init` could not seed a new instance at all. Two rules met in
+// the middle, both proved against live cloudbongos.com on 2026-09-07:
+//   • BV1.R11 (task 1003598) — POST /tasks refuses a task with no goal_id, so
+//     every starter and kickoff task 400'd `goal_id_required`.
+//   • R03 (task 1003591) — POST /goals refuses a new goal on a version that is
+//     not 'planning', and versionPayload creates the version at 'building', so
+//     init could not create a goal to file them under either.
+// There is no version-status transition route yet, so init could not create at
+// 'planning', seed, and promote. The way out is the version's OWN first goal,
+// created in the same transaction: that is not scope GROWTH on a closed version
+// (what R03 guards) but the version's initial scope, and it spends none of the
+// R07 Archon admission override that ADR 0250 §3 keeps counted.
+//
+// THE QUIETER DEFECT UNDERNEATH. Since ADR 0086 criteria live under goals, but
+// createVersion inserted done_when_criteria with no goal_id — the catch-all goals
+// came from migration 160's one-shot backfill with no trigger behind it, so every
+// version created after it got goal-less criteria. Since ADR 0183 criteria satisfy
+// themselves off LINKED tasks, a criterion nobody can link a task to can never
+// close. Stamping goal_id here is what gives them something to hang from.
+//
+// DB-FREE, through the module's OWN test seam: createVersion takes deps.pool and
+// honours it only under NODE_ENV=test (the listVersions / versionProgress idiom),
+// threading it into withTx so version, goal and criteria all run on the fake. The
+// fake client answers by statement shape and records every one, which is what lets
+// this pin the SQL's shape AND its order without a Postgres — and the goal INSERT
+// appearing inside the same BEGIN/COMMIT is the proof that createGoal rode the
+// caller's transaction rather than opening its own connection. (The live SQL is
+// exercised against a real database the same way the other write paths are — see
+// the versions_route.mjs note.)
+//
+// Run:  node tests/version_first_goal.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+let passed = 0, failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+// ── the fake connection ─────────────────────────────────────────────────────
+// Answers each statement by shape and records it. Returning a row for the goal
+// insert matters: createVersion stamps the criteria with `goal.id`, so a stub
+// that answered {rows: []} would silently reproduce the goal-less-criteria bug
+// it is here to catch.
+function fakeDb({ goalRow = { id: 77, title: 'Foundations' } } = {}) {
+  const log = [];
+  const client = {
+    query: async (sql, params) => {
+      log.push({ sql, params });
+      if (/^\s*(BEGIN|COMMIT|ROLLBACK)/i.test(sql)) return { rows: [] };
+      if (/INSERT INTO versions/i.test(sql)) return { rows: [{ id: params[0], name: params[1], status: params[2], track: params[3] }] };
+      if (/INSERT INTO goals/i.test(sql)) return { rows: [goalRow] };
+      if (/INSERT INTO done_when_criteria/i.test(sql)) {
+        return { rows: [{ id: log.length, version_id: params[0], criterion_id: params[1], criterion_md: params[2], sort_order: params[3], goal_id: params[4], satisfied: false }] };
+      }
+      return { rows: [] };
+    },
+    release() {},
+  };
+  return { log, pool: { connect: async () => client } };
+}
+
+// deps.pool is the module's own test seam and is honoured ONLY under NODE_ENV=test,
+// so this line is load-bearing: without it createVersion reaches for the real pool.
+process.env.NODE_ENV = 'test';
+const db = fakeDb();
+const { createVersion } = require('../modules/lifecycle/db-versions.js');
+
+const CRITERIA = [
+  { criterion_id: 'first-loop', criterion_md: 'A task reaches shipped with credits.' },
+  { criterion_id: 'second', criterion_md: 'And a second one does too.' },
+];
+
+console.log('createVersion — the version, its first goal, and its criteria:');
+
+const out = await createVersion({
+  id: 'V1', name: 'Foundations', status: 'building', track: 'product',
+  doneWhen: 'The loop closes.', criteria: CRITERIA, createdBy: 7,
+}, { pool: db.pool });
+
+await t('the version, a goal, and every criterion land in ONE transaction', async () => {
+  const kinds = db.log.map((c) => c.sql.trim().split(/\s+/).slice(0, 3).join(' ').toUpperCase());
+  assert.equal(kinds[0], 'BEGIN', 'opens a transaction');
+  assert.equal(kinds[kinds.length - 1], 'COMMIT', 'and commits it');
+  assert.ok(!db.log.some((c) => /ROLLBACK/i.test(c.sql)), 'nothing rolled back');
+  // A goal committed on its own connection would survive a rolled-back version
+  // create as a goal pointing at a version that does not exist.
+  assert.ok(db.log.some((c) => /INSERT INTO goals/i.test(c.sql)), 'the goal is created here, not by a second round-trip');
+});
+
+await t('the goal is created AFTER the version and BEFORE the criteria', async () => {
+  const at = (re) => db.log.findIndex((c) => re.test(c.sql));
+  const v = at(/INSERT INTO versions/i);
+  const g = at(/INSERT INTO goals/i);
+  const c = at(/INSERT INTO done_when_criteria/i);
+  assert.ok(v >= 0 && g >= 0 && c >= 0, 'all three statements ran');
+  assert.ok(v < g, 'the goal references the version, so the version exists first');
+  assert.ok(g < c, 'the criteria reference the goal, so the goal exists first');
+});
+
+await t('EVERY criterion carries the goal_id — the defect that made criteria uncloseable', async () => {
+  const crits = db.log.filter((c) => /INSERT INTO done_when_criteria/i.test(c.sql));
+  assert.equal(crits.length, CRITERIA.length, 'one insert per criterion');
+  for (const c of crits) {
+    // Assert the STATEMENT, not only the params. goal_id can sit in the insert
+    // list while VALUES still binds a literal NULL — which is this defect exactly,
+    // and a fixture that rebuilds the row out of params cannot see it happen.
+    assert.match(c.sql, /INSERT INTO done_when_criteria \(version_id, criterion_id, criterion_md, sort_order, goal_id\)/,
+      'goal_id is in the insert list');
+    assert.match(c.sql, /VALUES \(\$1, \$2, \$3, \$4, \$5\)/, 'and VALUES BINDS it, rather than a literal NULL');
+    assert.match(c.sql, /RETURNING[\s\S]*goal_id/, 'and the row comes back carrying it');
+    assert.equal(c.params[4], 77, "and it is THIS version's first goal");
+  }
+  for (const c of out.criteria) assert.equal(c.goal_id, 77, 'the returned rows say so too');
+});
+
+await t('the goal is returned, because the caller cannot file a task without its id', async () => {
+  assert.ok(out.goal, 'createVersion returns it');
+  assert.equal(out.goal.id, 77);
+  assert.equal(out.version.id, 'V1');
+});
+
+await t('the goal is titled for the version, and owned by its creator', async () => {
+  const g = db.log.find((c) => /INSERT INTO goals/i.test(c.sql));
+  assert.equal(g.params[0], 'V1', 'scoped to the version');
+  assert.equal(g.params[1], 'Foundations', 'named after the version by default');
+  assert.equal(g.params[5], 7, 'created_by is the caller — createGoal also makes them a lead');
+  assert.equal(g.params[2], 'The loop closes.', 'described by the version\'s done_when');
+});
+
+await t('an explicit firstGoal overrides the default title and description', async () => {
+  const d2 = fakeDb();
+  await createVersion({ id: 'V2', name: 'Ignored', doneWhen: 'also ignored', criteria: [],
+    firstGoal: { title: 'Project creation', description: 'The picker and the wizard.' } }, { pool: d2.pool });
+  const g = d2.log.find((c) => /INSERT INTO goals/i.test(c.sql));
+  assert.equal(g.params[1], 'Project creation');
+  assert.equal(g.params[2], 'The picker and the wizard.');
+});
+
+await t('a blank firstGoal title falls back to the version rather than creating an unnamed goal', async () => {
+  const d3 = fakeDb();
+  await createVersion({ id: 'V3', name: 'Third', criteria: [], firstGoal: { title: '   ' } }, { pool: d3.pool });
+  const g = d3.log.find((c) => /INSERT INTO goals/i.test(c.sql));
+  assert.equal(g.params[1], 'Third', 'goals.title is NOT NULL — a blank title must never reach it');
+});
+
+await t('a version with NO criteria still gets its goal (the goal is the point, not the criteria)', async () => {
+  const d4 = fakeDb();
+  const r = await createVersion({ id: 'V4', name: 'Fourth', criteria: [] }, { pool: d4.pool });
+  assert.ok(d4.log.some((c) => /INSERT INTO goals/i.test(c.sql)), 'still created');
+  assert.equal(r.goal.id, 77);
+  assert.equal(r.criteria.length, 0);
+});
+
+console.log(`\nversion_first_goal: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/versions_route.mjs

@@ -32,6 +32,7 @@ const VERSIONS_POST_SCHEMA = {
   done_when: { type: 'string', maxLength: 8000 },
   scope_doc_path: { type: 'string', maxLength: 256 },
   criteria: { type: 'array', maxItems: 100 },
+  first_goal: { type: 'object' },
 };
 
 // ---- the router builds (smoke: imports auth/db/branding/_helpers cleanly) ----
@@ -46,6 +47,17 @@ test('INIT: minimal create (id + name only) passes', () => {
   assert.equal(validate({ id: 'V1', name: 'Prove the loop' }, VERSIONS_POST_SCHEMA), null);
 });
 
+// The version's first goal (task 1003701). init does NOT send one — it takes the
+// default, which names the goal after the version — so the minimal create above
+// staying valid is half the contract, and this is the other half.
+test('INIT: an explicit first_goal object passes', () => {
+  assert.equal(validate({ id: 'V1', name: 'Prove the loop', first_goal: { title: 'Foundations' } }, VERSIONS_POST_SCHEMA), null);
+});
+
+test('BAD: first_goal as a string is refused (it is an object or nothing)', () => {
+  assert.notEqual(validate({ id: 'V1', name: 'n', first_goal: 'Foundations' }, VERSIONS_POST_SCHEMA), null);
+});
+
 test('INIT: full create with criteria array passes', () => {
   const body = {
     id: 'V1',