@bongos/core 1.19.916 → 1.19.917

package/modules/lifecycle/db.js

@@ -185,6 +185,7 @@ const {
   getActiveClaimsForBuilderWithStale,
   getBuildersRoster,
   getClaimPublishedSha,
+  shippedTasksByPublishedSha,
   listConfirmedTasksForReconcile,
   mergeTask,
   needsRebaseTasksForBuilder,
@@ -330,6 +331,7 @@ module.exports = {
   listConfirmedTasksForReconcile, // task 1134 — server-owned publish reconciler feed
   setClaimPublishedSha, // task 1547 — record the SERVER-pushed tip for per-task land proof
   getClaimPublishedSha, // task 1547 — read the published tip for the reconcile gate
+  shippedTasksByPublishedSha, // task 1004090 / BV2.R15 — the reverse read, for removal attribution
   getActiveClaimsForBuilder,
   moduleScopeForActiveClaims, // goal 1000051 / R92 — dev-box task-scoped source access (ADR 0148 §2)
   activeClaimCountForBuilder, // task 1002729 — distinguishes "no claim" from "claim with an empty goal wall"

package/modules/lifecycle/removal-derivation.js

@@ -0,0 +1,332 @@
+'use strict';
+
+// modules/lifecycle/removal-derivation.js — WHAT A SHIP DELETED, AND WHOSE WORK
+// IT WAS (task 1004090 / BV2.R15, goal 1000095; ADR 0313).
+//
+// Brightness (R20) is the live share of a descent, so something has to be able to
+// say that shipped work was later removed. Nothing recorded that: `shipped` is
+// terminal, there is no reverted status, and `tasks.merged_into_task_id` is
+// CHECK-constrained to abandoned rows. This file derives the signal.
+//
+// It produces a QUESTION, never a verdict. The rule in ./cascade.js files a task
+// at backlog; a person confirms it (R16). Nothing here changes a status, and
+// nothing here touches credits — ADR 0313 is explicit that the ledger is never
+// rewritten, because refactors, renames and file moves all look like deletions to
+// a diff and a derived-only signal would dim the sky continuously.
+//
+// ── WHY NOT THE SIGNAL THAT ALREADY EXISTS ──────────────────────────────────
+//
+// `netNegativeBonusAmount` is the nearest existing thing and is unusable, for
+// three reasons ADR 0313 sets out:
+//   • It has no TARGET. `removed > added` over a whole ship says that deletion
+//     happened, never what was deleted or whose work it was. Brightness needs the
+//     target; the boolean carries none.
+//   • It is CLIENT-SUPPLIED — it reads `signals.diff_stats` from the grade request
+//     body, and `grader-score.js` already documents defending against a forged
+//     `diff_stats`.
+//   • Brightness sits beside money. Deriving it from a forgeable, target-less
+//     counter would be wrong even where it was convenient.
+//
+// So the signal comes from the SERVER's own view of the merge instead. Landing is
+// server-mediated (ADR 0055): the server holds the authority and can ask GitHub
+// what the pull request actually changed, rather than be told by the box that
+// built it.
+
+const api = require('../../src/module-api');
+const githubPush = require('./github-push');
+
+// How many deleted paths one ship will be attributed — and therefore the HARD
+// CEILING on GitHub calls this derivation can make per ship. Each path costs one
+// commit-history request, and they run on the server's shared push credential,
+// which the publish path itself depends on: spending that budget to answer a
+// question nobody asked for would be a poor trade.
+//
+// A ship that removes more than this is a sweep — a directory move, a vendored
+// drop, a module deletion — where the proposal is least useful and the cost is
+// highest. Eight is deliberately small: a genuine "this ship removed someone's
+// feature" is a handful of files, and beyond that the truncation note tells a
+// reader to weigh the ship as a move rather than a removal.
+//
+// The cap is on the ATTRIBUTION, not the detection: the deletion count is still
+// reported honestly so the proposal can say its list is partial.
+const MAX_ATTRIBUTED_PATHS = 8;
+
+// listCommitsForPath — the shas of the commits that touched ONE path, newest
+// first. The read behind attribution: a deleted file is blamed back to the commit
+// that introduced it, and that sha is resolved through `claims.published_head_sha`.
+//
+// IT LIVES HERE RATHER THAN IN github-push.js, which is where its siblings live,
+// because that file sits ON the 1500-line ratchet ceiling — the same reason
+// `pr-assign.js` was carved out of it, and this module's CLAUDE.md says so in as
+// many words. Its only consumer is the derivation below.
+//
+// WHY THE API AND NOT `git log`. The server keeps no persistent clone — pushBundle
+// works in a temp dir off a bundle and throws it away — so there is no working tree
+// to blame in. GitHub holds the history. Same reason getPullRequestFiles reads the
+// REST files API rather than diffing locally.
+//
+// `until` bounds the walk to commits at or before the merge being examined, so a
+// LATER commit that re-added the path cannot be mistaken for the one that
+// introduced it.
+//
+// Caps at ONE page of 100. Attribution only needs to find a published tip, and a
+// path with more than 100 commits above the one that introduced it is old enough
+// that the introducing claim almost certainly predates `published_head_sha`
+// (migrations/171) — in which case the correct output is no attribution at all,
+// which is exactly what an exhausted page yields. Paging further would spend rate
+// limit to reach the same silence.
+async function listCommitsForPath({ path: filePath, until = null }, deps = {}) {
+  // resolveToken is injectable for the same reason fetchImpl and repoInfo are:
+  // this function is the one place a rate-limit response is classified, and that
+  // classification has to be testable without a live credential.
+  const token = deps.resolveToken ? await deps.resolveToken(deps) : await githubPush.resolveToken(deps);
+  if (!token) throw new Error('PUSH_UNCONFIGURED');
+  if (typeof filePath !== 'string' || !filePath) throw new Error('BAD_PATH');
+  const info = deps.repoInfo || api.repoInfo;
+  if (!info || info.error || !info.owner || !info.repo) throw new Error('NO_REPO_INFO');
+  const doFetch = deps.fetchImpl || fetch;
+  const qs = new URLSearchParams({ path: filePath, per_page: '100' });
+  if (until) qs.set('until', String(until));
+  const res = await doFetch(
+    `https://api.github.com/repos/${info.owner}/${info.repo}/commits?${qs.toString()}`,
+    { headers: githubPush.ghHeaders(token) }
+  );
+  // A path that has never existed is a 404 and an EMPTY history, not an error: the
+  // caller asks "who introduced this", and "nobody we can see" is an answer.
+  if (res.status === 404) return [];
+  // RATE LIMITING IS NOT A PER-PATH FAILURE — it is a statement about the whole
+  // credential, so it must not be retried and must not be walked past. GitHub
+  // signals it as 403 or 429 with the remaining count at zero (a 403 for any
+  // other reason keeps a non-zero remaining, or sends no header at all, and is
+  // treated as an ordinary failure). Thrown with a recognisable name so the
+  // caller can ABANDON the rest of the walk rather than spend the next seven
+  // requests learning the same thing.
+  if (res.status === 429 || res.status === 403) {
+    const remaining = res.headers && typeof res.headers.get === 'function'
+      ? res.headers.get('x-ratelimit-remaining')
+      : null;
+    if (res.status === 429 || remaining === '0') {
+      const e = new Error('RATE_LIMITED');
+      e.rateLimited = true;
+      throw e;
+    }
+  }
+  if (!res.ok) throw new Error(`STATUS_FETCH_FAILED ${res.status}`);
+  const commits = await res.json();
+  if (!Array.isArray(commits)) return [];
+  return commits.map((c) => c && c.sha).filter((sha) => typeof sha === 'string' && sha);
+}
+
+// ---------------------------------------------------------------------------
+// The pure half
+// ---------------------------------------------------------------------------
+
+// WHAT COUNTS AS REMOVED. ADR 0313 names three exclusions, and each is a status
+// the REST files API already distinguishes — which is exactly why the derivation
+// reads that API rather than counting lines:
+//
+//   • 'renamed'  — a rename or move is NOT a removal. Git's own rename detection
+//                  resolves it and the work still stands. This is the exclusion
+//                  that matters most: a directory reorganisation would otherwise
+//                  propose a removal for every file in it.
+//   • 'modified' — a rewrite in place is NOT a removal. Lines changing is how
+//                  code lives, and this is where a line-count heuristic
+//                  (`removed > added`) goes wrong.
+//   • 'added' / 'copied' / 'changed' — nothing was lost.
+//
+// Only 'removed' survives. The third ADR exclusion — a cold body is not a remnant
+// — is not expressible here: it is enforced downstream by attributing solely to
+// tasks that actually SHIPPED (see shippedTasksByPublishedSha), because an idea
+// declined at triage never ignited and nothing was built to lose.
+//
+// Pure: hand it the files array and it answers. No network, no clock, no DB.
+function deletedPathsFrom(files) {
+  if (!Array.isArray(files)) return [];
+  const out = [];
+  for (const f of files) {
+    if (!f || typeof f !== 'object') continue;
+    // `deleted` is getPullRequestFiles' own mapping of status === 'removed'.
+    // Both are read, and they must AGREE: trusting `deleted` alone would follow a
+    // caller that set it by hand, and trusting `status` alone would miss a caller
+    // that shaped the row the other way. Where only one is present, it decides.
+    const status = typeof f.status === 'string' ? f.status.toLowerCase() : null;
+    const flagged = f.deleted === true;
+    const isRemoval = status ? status === 'removed' : flagged;
+    if (!isRemoval) continue;
+    if (typeof f.path !== 'string' || !f.path) continue;
+    out.push(f.path);
+  }
+  return [...new Set(out)];
+}
+
+// Group attributed paths by the task that published them, so the proposal reads
+// as "this task lost these files" rather than a flat list a person has to sort.
+// Pure. Insertion order is preserved, which keeps the rendered body stable for a
+// given diff rather than reshuffling between runs.
+function groupByTask(attributions) {
+  const byTask = new Map();
+  for (const a of Array.isArray(attributions) ? attributions : []) {
+    if (!a || a.taskId == null) continue;
+    const key = String(a.taskId);
+    if (!byTask.has(key)) byTask.set(key, { taskId: key, title: a.title || null, paths: [] });
+    const row = byTask.get(key);
+    if (a.path && !row.paths.includes(a.path)) row.paths.push(a.path);
+  }
+  return [...byTask.values()];
+}
+
+// ---------------------------------------------------------------------------
+// The impure half — one network read per deleted path, then one DB read
+// ---------------------------------------------------------------------------
+
+// Resolve deleted paths to the shipped tasks that published them.
+//
+// For each path: ask GitHub which commits touched it up to the merge, then look
+// those shas up against `claims.published_head_sha`. The OLDEST matching commit is
+// taken as the one that introduced the file — the newest would attribute a file to
+// whoever last edited it, which is a different and wrong question.
+//
+// `shipTaskId` is excluded: a ship that deletes its OWN earlier file is a builder
+// tidying up inside one piece of work, not a removal of someone else's.
+//
+// Everything is best-effort per path. One path whose history cannot be read costs
+// that path its attribution and nothing else — the other paths still resolve, and
+// a total failure yields an empty list, which files no proposal at all.
+async function attributeDeletions({ paths, shipTaskId, until = null }, deps = {}) {
+  const listCommits = deps.listCommitsForPath || listCommitsForPath;
+  const lookup = deps.shippedTasksByPublishedSha;
+  const errors = [];
+  if (typeof lookup !== 'function') return { attributions: [], errors: ['no sha lookup provided'] };
+
+  const wanted = (Array.isArray(paths) ? paths : []).slice(0, MAX_ATTRIBUTED_PATHS);
+  const perPath = [];
+  for (const path of wanted) {
+    try {
+      // Newest first from the API; reversed so the OLDEST visible commit wins.
+      const shas = await listCommits({ path, until });
+      perPath.push({ path, shas: [...(Array.isArray(shas) ? shas : [])].reverse() });
+    } catch (e) {
+      // A rate-limit refusal ends the WALK, not just this path. Continuing would
+      // spend the remaining budget on requests already known to fail, on the same
+      // credential the publish path needs — the opposite of backing off. There is
+      // deliberately no retry and no sleep: this runs on the ship path, and
+      // waiting there to dim a star later is the wrong trade (ADR 0313).
+      if (e && e.rateLimited) {
+        errors.push('removal: GitHub rate limit reached — attribution abandoned for this ship');
+        break;
+      }
+      errors.push(`removal: history for ${path} unreadable (${e && e.message})`);
+    }
+  }
+
+  // ONE database read for every path's shas together, rather than one per path.
+  let shaToTask;
+  try {
+    shaToTask = await lookup(perPath.flatMap((p) => p.shas));
+  } catch (e) {
+    return { attributions: [], errors: [...errors, `removal: sha lookup failed (${e && e.message})`] };
+  }
+  if (!(shaToTask instanceof Map)) return { attributions: [], errors: [...errors, 'removal: sha lookup returned no map'] };
+
+  const attributions = [];
+  for (const { path, shas } of perPath) {
+    for (const sha of shas) {
+      const hit = shaToTask.get(sha);
+      if (!hit) continue;
+      if (shipTaskId != null && String(hit.taskId) === String(shipTaskId)) break;
+      attributions.push({ path, taskId: hit.taskId, title: hit.title, sha });
+      break;
+    }
+  }
+  return { attributions, errors };
+}
+
+// THE WHOLE DERIVATION, as the one call the cascade context resolver makes.
+//
+// NON-BLOCKING IS THE CONTRACT, not a nicety. This runs on the path a ship
+// already takes, and ADR 0313 says so in as many words: "a derivation that errors
+// files nothing and never fails the merge. Landing work is more important than
+// dimming a star on time." So every failure mode below returns a report rather
+// than throwing, and the caller treats an empty `removals` as "file nothing".
+async function deriveRemovalsForShip({ taskId, prNumber, until = null }, deps = {}) {
+  const empty = (errors) => ({ removals: [], deletedCount: 0, truncated: false, errors });
+  try {
+    if (prNumber == null) return empty(['removal: no pull request for this ship — nothing to read']);
+
+    const getFiles = deps.getPullRequestFiles
+      || ((args) => githubPush.getPullRequestFiles(args));
+
+    let files;
+    try {
+      files = await getFiles({ number: Number(prNumber) });
+    } catch (e) {
+      return empty([`removal: PR files unreadable (${e && e.message})`]);
+    }
+
+    const deleted = deletedPathsFrom(files);
+    if (!deleted.length) return empty([]);
+
+    const { attributions, errors } = await attributeDeletions(
+      { paths: deleted, shipTaskId: taskId, until },
+      deps
+    );
+
+    return {
+      removals: groupByTask(attributions),
+      deletedCount: deleted.length,
+      truncated: deleted.length > MAX_ATTRIBUTED_PATHS,
+      errors,
+    };
+  } catch (e) {
+    return empty([`removal: ${e && e.message}`]);
+  }
+}
+
+// removalCandidatesForTask — the whole resolver the ship listener wires, as ONE
+// testable function rather than a closure inside the listener.
+//
+// IT LIVES HERE BECAUSE THE CLOSURE VERSION SHIPPED A DEAD FEATURE. Written
+// inline in routes/lifecycle.js it read `pr.number` from findTaskPullRequest,
+// which returns `pr_number` — so `prNumber` was null on every real ship,
+// deriveRemovalsForShip short-circuited every time, and the rule could never
+// fire in production. Every test injected `removalCandidates` or
+// `getPullRequestFiles` directly, so the whole suite passed over a feature that
+// did nothing: the parts agreed with each other and none of them was wired to
+// the part that was wrong.
+//
+// A closure inside a listener registration is not reachable from a test without
+// rebuilding the router and intercepting the registration. Naming it makes the
+// field read testable, and leaves the listener a single line that cannot hide a
+// second one.
+//
+// Resolving the PR here rather than inside deriveRemovalsForShip keeps THAT
+// function free of the task->PR question, which github-push already answers.
+// A task with no findable PR derives nothing, which files nothing.
+async function removalCandidatesForTask(task, deps = {}) {
+  const empty = { removals: [], deletedCount: 0, truncated: false, errors: [] };
+  const findPr = deps.findTaskPullRequest
+    || ((args) => githubPush.findTaskPullRequest(args));
+  let prNumber = null;
+  try {
+    const pr = await findPr({ taskId: task && task.id });
+    // `pr_number`, NOT `pr.number` — findTaskPullRequest returns
+    // { branch, pr_number, pr_state, merged }. Pinned by test, because reading
+    // the wrong field here is silent: it yields null, which is a legal "no PR"
+    // answer, so the feature simply never runs and nothing ever complains.
+    prNumber = pr && pr.pr_number != null ? pr.pr_number : null;
+  } catch (_) {
+    // Never let the PR lookup cost the ship. Same contract as everything below.
+    return empty;
+  }
+  return deriveRemovalsForShip({ taskId: task && task.id, prNumber }, deps);
+}
+
+module.exports = {
+  MAX_ATTRIBUTED_PATHS,
+  removalCandidatesForTask,
+  listCommitsForPath,
+  deletedPathsFrom,
+  groupByTask,
+  attributeDeletions,
+  deriveRemovalsForShip,
+};

package/modules/lifecycle/routes/lifecycle.js

@@ -28,6 +28,7 @@ const api = require('../../../src/module-api');
 const lifecycle = require('../lifecycle');
 const db = require('../db');
 const cascade = require('../cascade');
+const removalDerivation = require('../removal-derivation');
 
 // task 1003549 — the cross-role cascade listener. `task.shipped` already exists
 // as a kernel event (emitted post-commit by the publish reconciler and the ship
@@ -78,6 +79,29 @@ function registerSeams() {
     // HOLDS a deploy can never be read differently. At 'off' the artist-review
     // rule files nothing.
     artistGateMode: () => api.artistGate.artistGateMode(),
+    // WHAT THIS SHIP DELETED (task 1004090 / BV2.R15, ADR 0313). The derivation
+    // asks GitHub what the pull request actually changed and blames the deleted
+    // paths back through `claims.published_head_sha` — the SERVER's own view of
+    // the merge, never the client-supplied `diff_stats` the net-negative bonus
+    // reads, which is target-less and already known-forgeable.
+    //
+    // Resolving the PR number here rather than inside the derivation keeps that
+    // file free of the task->PR question, which github-push already answers.
+    // A task with no findable PR derives nothing, which files nothing.
+    //
+    // Every failure is swallowed into an empty result: this runs on the ship
+    // path, and ADR 0313 is explicit that landing work matters more than dimming
+    // a star on time.
+    //
+    // The resolver itself is `removalCandidatesForTask`, NOT a closure here. It
+    // was a closure, and it read the wrong field off findTaskPullRequest
+    // (`number` for `pr_number`), which made the whole rule dead in production
+    // while every test passed — because every test injected this dep. A closure
+    // inside a listener registration is not reachable from a test; a named
+    // function is, and this line is now too small to hide a bug of its own.
+    removalCandidates: (task) => removalDerivation.removalCandidatesForTask(task, {
+      shippedTasksByPublishedSha: (shas) => db.shippedTasksByPublishedSha(shas),
+    }),
     log: api.logger ? api.logger('lifecycle') : null,
   }));
 }

package/modules/lifecycle/tests/cascade.mjs

@@ -194,15 +194,32 @@ const shippedCopy = (over = {}) => ({
   ...over,
 });
 
-await test('the artist review is the one production rule, keyed and disciplined', () => {
-  assert.equal(cascade.CASCADES.length, 1);
-  const r = cascade.CASCADES[0];
-  assert.equal(r.key, 'artist-review-on-ship');
+await test('the artist review is keyed and disciplined, and the table stays well-formed', () => {
+  // This pinned CASCADES.length === 1 until task 1004090 appended the removal
+  // proposal (BV2.R15). A count is the wrong pin for a table whose whole contract
+  // is "extend by appending an entry" (ADR 0242) — it fails on the one change it
+  // is meant to permit, and says nothing about WHICH rules are there.
+  //
+  // So it pins the rule by KEY instead, and pins the SET of keys separately below:
+  // a rule vanishing and a rule being added are different events and should fail
+  // differently.
+  const r = cascade.CASCADES.find((x) => x.key === 'artist-review-on-ship');
+  assert.ok(r, 'the artist review rule is gone from CASCADES');
   assert.equal(r.discipline, 'artist', 'the review is FOR the artist, whatever role shipped the work');
   assert.equal(r.kind, 'unclassified', 'a valid kind — not the invalid "chore" the spec used to default to');
   assert.deepEqual(cascade.validateCascades(), [], 'and the shipped table is well-formed');
 });
 
+await test('the production rule set is exactly what is declared', () => {
+  // The other half of the pin above: adding a rule is a deliberate act, so it
+  // should have to be recorded here. Duplicate keys would collide on source_ref
+  // and silently suppress one another, which validateCascades already refuses.
+  assert.deepEqual(
+    cascade.CASCADES.map((r) => r.key).sort(),
+    ['artist-review-on-ship', 'removal-proposed-on-ship'],
+  );
+});
+
 await test('a copy/visual ship generates the two-step artist review', () => {
   const { matched } = cascade.cascadesFor(shippedCopy());
   assert.equal(matched.length, 1);

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.916",
+  "version": "1.19.917",
   "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/provision-repo.js

@@ -201,6 +201,56 @@ function grantInstanceRepoReadCmd(inst, { privileged = false } = {}) {
   return `${privileged ? 'sudo ' : ''}usermod -aG ${APP_USER} ${instanceUser(inst)}`;
 }
 
+// Can this plane give a child instance its OWN unix account AT ALL? (task 1004018, ADR 0317)
+//
+// ensureInstanceUserCmd above needs uid 0 — directly, or through the `privileged` sudo
+// prefix. The self-host image runs `USER node` and installs no sudo, so there it cannot
+// run, and every child on that plane would share one uid: exactly the /proc/<pid>/environ
+// vector ADR 0281 exists to close. Probed, not configured — a runner either reaches root
+// on this plane or it does not, and an operator who wants provisioning to proceed needs
+// privilege, not a flag that says to pretend.
+//
+// The probe runs the SAME escalation the mutation will, so a pass is evidence rather than
+// inference. Read-only, no mutation, and no pipeline: a pipeline's exit status is the last
+// stage's, which would erase the difference below.
+//
+// A shell that RAN AND ANSWERED is the only failure that proves the plane cannot. Under
+// remote exec boxExec is `ssh <host> bash -s`, so an unreachable co-hosting box throws
+// here too — and answering that with "this plane cannot create accounts, provision
+// elsewhere" would be a confident wrong diagnosis that burns the intent's retry budget on
+// a network blip. Exit 1 (not root) and 127 (no sudo binary) are read as proof; ssh
+// reports its own failures as 255, so both still mean what they say across the hop.
+const ACCOUNT_PROOF_STATUS = new Set([1, 127, 9009]);
+function accountPlaneGap(exec, { privileged = false } = {}) {
+  // sh -c, not a bare test: under sudo the outer (unprivileged) shell would expand
+  // $(id -u) before sudo ever ran, and the probe would answer about the wrong user.
+  const cmd = `${privileged ? 'sudo ' : ''}sh -c 'test "$(id -u)" = 0'`;
+  try { exec(cmd); return null; } catch (e) {
+    // e.stderr is a zero-length Buffer when the command failed SILENTLY — truthy, and
+    // String()s to '' — so it has to be length-checked or it shadows the only cause there
+    // is. `test` exiting 1 writes nothing, and that is this probe's commonest refusal.
+    const stderr = e && e.stderr && e.stderr.length ? e.stderr : null;
+    const why = String(stderr || (e && e.message) || e).trim().slice(0, 200) || `exit status ${e && e.status}`;
+    if (!ACCOUNT_PROOF_STATUS.has(e && e.status)) {
+      return `could not confirm the runner can create a per-instance unix account on this plane: '${cmd}' failed (${why}). Every instance is given its own account, so provisioning refuses rather than assume — re-run once the box answers.`;
+    }
+    return `this plane cannot create a per-instance unix account, so every child instance would run as one uid and could read its siblings' secrets: '${cmd}' failed (${why}). Provision from a host where the runner is root or holds sudo (PROVISION_SUDO=1) — a shared uid is the isolation ADR 0281 exists to provide, not a detail.`;
+  }
+}
+
+// The preflight around accountPlaneGap: the narration its sibling preflights carry,
+// including the dry-run line without which the plan prints step 1c's useradd as though it
+// will work. Returns the refusal, or null to proceed. `dedicated` skips it — that account
+// is created by cloud-init, which runs as root. Lives here beside the account it guards.
+function accountPreflight({ exec, apply, log, shape, privileged = false, probe = accountPlaneGap }) {
+  if (shape === 'dedicated') return null;
+  if (!apply) { log('  [preflight] would probe whether the runner can create this instance\'s own unix account'); return null; }
+  const missing = probe(exec, { privileged });
+  if (missing) return `Account preflight failed: ${missing}`;
+  log('  [preflight] the runner can create the instance\'s own unix account ✓');
+  return null;
+}
+
 // Create-or-rotate the instance's PG login role and hand it its OWN database — and
 // nothing else. Three statements, one psql, ON_ERROR_STOP:
 //   1. CREATE ROLE ... LOGIN PASSWORD, or ALTER ... PASSWORD when it already exists (the
@@ -1020,6 +1070,8 @@ async function refreshStandaloneCorePin(inst, deps) {
 
 module.exports = {
   APP_USER,
+  accountPlaneGap,
+  accountPreflight,
   CORE_PKG_DIR,
   INSTANCE_GITIGNORE,
   alreadyScaffolded,

package/scripts/gds/provision.js

@@ -50,7 +50,7 @@ const cp = require('node:child_process');
 const crypto = require('node:crypto');
 
 const { CONFIG, MANIFEST_UA, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES, MAX_INTENT_ATTEMPTS, REPO_ROOT, coreVersionSafe, hasFlag, loadDeps, oauthSecret, provisionerBotEmail } = require('./provision-config.js');
-const { APP_USER, alreadyScaffolded, buildCorePinRefreshCommit, coreCheckoutHasGit, dbCreateCmd, dbName, dbRoleCmd, dbRoleCmdShown, dbRoleGrantsCmd, ensureInstanceUserCmd, generateDbPassword, grantInstanceRepoReadCmd, instanceDbRole, instanceStateDir, instanceUser, deployKeyPath, deployKeyTitle, ensurePrivateRepoAccess, installedCorePackDir, installedCoreTarball, instanceInitSpec, instanceRepoRemote, migrateCmd, onboardMode, ownerLoginOf, parseTargetRef, planCorePinRefresh, refreshStandaloneCorePin, resolveOwnerGithubToken, resolveVendorableCoreTarball, safeVersionLabel, scaffoldStandaloneRepo, seedFirstVersionCmd, standaloneInstallCmd, standaloneMigrateCmd, standalonePullCmd, standaloneRegenDocsCmd, standaloneRoot } = require('./provision-repo.js');
+const { APP_USER, accountPreflight, alreadyScaffolded, buildCorePinRefreshCommit, coreCheckoutHasGit, dbCreateCmd, dbName, dbRoleCmd, dbRoleCmdShown, dbRoleGrantsCmd, ensureInstanceUserCmd, generateDbPassword, grantInstanceRepoReadCmd, instanceDbRole, instanceStateDir, instanceUser, deployKeyPath, deployKeyTitle, ensurePrivateRepoAccess, installedCorePackDir, installedCoreTarball, instanceInitSpec, instanceRepoRemote, migrateCmd, onboardMode, ownerLoginOf, parseTargetRef, planCorePinRefresh, refreshStandaloneCorePin, resolveOwnerGithubToken, resolveVendorableCoreTarball, safeVersionLabel, scaffoldStandaloneRepo, seedFirstVersionCmd, standaloneInstallCmd, standaloneMigrateCmd, standalonePullCmd, standaloneRegenDocsCmd, standaloneRoot } = require('./provision-repo.js');
 const { backupScriptPath, backupService, backupServicePath, backupTimer, backupTimerPath, backupUnitName, instanceManifestCmd, originEnvVarsFor, serviceUnit, serviceUnitPath, settingsConsumed, settingsEnvVarsFor, upsertEnvVars, webEnvBody, webEnvPath } = require('./provision-units.js');
 const { caddyBlock, caddySnippetPath, checkCaddyWiring, checkDnsTokenScope, classifyZoneScope, dnsReleaseEnv, dnsUpsertEnv, federateInstance, federationHubOrigin, healthzCmd, identityCmd, identityVerdict, ingressPlaneGap, ingressPreflight, shouldFederate, zoneForDomain } = require('./provision-net.js');
 const { resolveProcessManager } = require('./provision-process.js');
@@ -276,6 +276,12 @@ async function provisionInstance(inst, deps) {
   // skipped 0303 entirely, reached step 6 and died on the snippet write.
   const ingressGap = ingressPreflight({ exec: boxExec, apply, log, shape: inst.hosting_shape, probe: deps.ingressPlaneGap });
   if (ingressGap) return { ok: false, error: ingressGap };
+  // Account preflight (task 1004018, ADR 0317). The third and last PLANE question — can this
+  // box give the child its own unix account? — before 0303 below asks the per-DOMAIN one. A
+  // plane that cannot would run every child as one uid, the ADR 0281 vector, and step 1c's
+  // useradd would crash mid-provision instead of refusing.
+  const accountGap = accountPreflight({ exec: boxExec, apply, log, shape: inst.hosting_shape, privileged, probe: deps.accountPlaneGap });
+  if (accountGap) return { ok: false, error: accountGap };
   // Caddy preflight (task 1002860, ADR 0303): a box whose base Caddyfile has no tls-check ask
   // can never certify this domain, so refuse before touching it. Injectable like the DNS check.
   const caddyCheck = deps.checkCaddyWiring || checkCaddyWiring;

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.916'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.917'; // 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');