@bongos/core 1.18.18 → 1.19.2

package/scripts/gds/provision.js

@@ -399,10 +399,55 @@ function installedCoreTarball({ instanceRoot, fsImpl = fs } = {}) {
   return null;
 }
 
-// Clone the (empty) target_ref → standaloneRoot → materialize config/ + .claude/ + a
-// file:-pinned @bongos/core + lockfile (via `bongos init --vendor-core`, task 2053)
-// → commit + push. Idempotent (skips once the repo carries a package.json) and dry-run
-// safe (every mutation goes through the injected exec/writeFile). ADR 0108 / 0125.
+// The onboard mode a provisioning row carries (migration provisioning_004, task 1002562).
+// 'adopt' means target_ref is a repo the owner ALREADY has, so the scaffold must LAYER
+// onto its history. Anything else — including a row written before the column existed, or
+// an unrecognized value — resolves to 'greenfield', deliberately the SAFE direction:
+// greenfield pushes a fresh tree and (carrying no --force) is REJECTED by a repo with
+// history, whereas wrongly choosing 'adopt' would start rewriting a repo nobody declared.
+function onboardMode(inst) {
+  return String((inst && inst.onboard_mode) || '') === 'adopt' ? 'adopt' : 'greenfield';
+}
+
+// Has the scaffold already completed in `root`? The marker is MODE-DEPENDENT, and reusing
+// the greenfield one for adopt is a real bug: greenfield's marker is "package.json exists"
+// (a fresh empty repo has none until we scaffold it), but an adopted repo is an existing
+// project that almost certainly HAS a package.json already — so the greenfield check would
+// report "already scaffolded" on the very first run and the instance would never become
+// bootable. For adopt the honest marker is the thing the layering itself contributes: a
+// @bongos/core dependency (both scope aliases the loader accepts, matching
+// installedCoreTarball). fs injectable for tests; read-only, so dry-run safe.
+function alreadyScaffolded(root, mode, { fsImpl = fs } = {}) {
+  const pkgPath = path.join(root, 'package.json');
+  if (!fsImpl.existsSync(pkgPath)) return false;
+  if (mode !== 'adopt') return true;
+  let pkg;
+  try { pkg = JSON.parse(fsImpl.readFileSync(pkgPath, 'utf8')); }
+  catch { return false; }   // unparseable → let the adopt layer report it, don't skip
+  const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
+  return !!(deps['@bongos/core'] || deps['@cloudbongos/core']);
+}
+
+// Materialize + push the instance's own repo. TWO paths, chosen by onboard_mode:
+//
+//   greenfield — the target_ref repo is EMPTY (github-repos.createUserRepo makes it with
+//                auto_init:false), so there is nothing to clone: `git init` locally,
+//                materialize, and push the first commit at main.
+//   adopt      — the target_ref repo is the owner's OWN existing project. CLONE it (so its
+//                history and files come along), LAYER the instance config additively via
+//                `bongos init --adopt --accept` (which never overwrites a pre-existing
+//                file), and push the layer commit as an ordinary fast-forward on top.
+//
+// Both end at a repo carrying config/ + .claude/ + a file:-pinned @bongos/core + lockfile,
+// which is what makes it `npm ci --omit=dev`-installable by the rest of provisioning.
+//
+// NEITHER PATH EVER USES --force. That is a safety property, not an oversight: since ADR
+// 0155 the credential here can write to every repo the owner owns, so a force-push would
+// be a route to destroying a user's work. A rejected push is the correct, recoverable
+// outcome. Asserted by tests.
+//
+// Idempotent (see alreadyScaffolded) and dry-run safe (every mutation goes through the
+// injected exec/writeFile). ADR 0108 / 0121 / 0125.
 async function scaffoldStandaloneRepo(inst, deps) {
   // The scaffold BUILDS + pushes the instance's repo (git clone, package-core,
   // `bongos init`, git push) — control-plane work that needs the packaging tools +
@@ -414,12 +459,12 @@ async function scaffoldStandaloneRepo(inst, deps) {
   const writeFile = deps.controlWriteFile || deps.writeFile;
   const root = standaloneRoot(inst);
   const repo = parseTargetRef(inst.target_ref);
+  const mode = onboardMode(inst);
   if (!repo) {
     throw new Error(`standalone instance ${inst.slug}: target_ref "${inst.target_ref || '(unset)'}" is not an owner/repo — set it (e.g. <owner>/${inst.slug}) so the scaffold knows which repo to clone + push.`);
   }
-  // Idempotent: a completed scaffold leaves package.json (the file:-pinned core). Skip.
-  if (fs.existsSync(path.join(root, 'package.json'))) {
-    log(`  [scaffold] ${root} already scaffolded (package.json present) — skipping`);
+  if (alreadyScaffolded(root, mode)) {
+    log(`  [scaffold] ${root} already scaffolded (mode=${mode}) — skipping`);
     return { already: true };
   }
   const coreV = coreVersionSafe();
@@ -427,7 +472,9 @@ async function scaffoldStandaloneRepo(inst, deps) {
     throw new Error('cannot resolve the core version (src/module-api CORE_VERSION) — run the scaffold from the control-plane checkout.');
   }
   const remote = instanceRepoRemote(repo);
-  log(`  [scaffold] ${repo.owner}/${repo.name} → ${root} (clone → materialize → pin core ${coreV} → commit → push)`);
+  log(mode === 'adopt'
+    ? `  [scaffold] ${repo.owner}/${repo.name} → ${root} (ADOPT: clone → layer additively → pin core ${coreV} → commit → fast-forward push)`
+    : `  [scaffold] ${repo.owner}/${repo.name} → ${root} (clone → materialize → pin core ${coreV} → commit → push)`);
 
   // Owner login = the founding firstAdmin. Best-effort; the spec falls back to the repo owner.
   let ownerLogin = null;
@@ -438,79 +485,21 @@ async function scaffoldStandaloneRepo(inst, deps) {
     } catch { /* fall back to the repo owner */ }
   }
 
-  // 1. Materialize the working tree + set the initial branch to `main`. A freshly-created
-  //    instance repo is EMPTY (github-repos.createUserRepo, auto_init:false), so there is
-  //    NOTHING to clone — and a git DEPLOY KEY is per-repo, so the shared PROVISION_GIT_SSH_ALIAS
-  //    key (e.g. `github-instances`, a deploy key scoped to ONE repo) can't even READ a
-  //    consumer's brand-new repo under their own account: `git clone` 500s with "Repository not
-  //    found." This is the clone-side twin of the task-1002317 push bug. So `git init` locally
-  //    instead of cloning, and set `origin` to the SSH remote for the no-token fallback push
-  //    below; the OAuth-preferred push (its token CREATED the repo, so it can write) handles the
-  //    upload for consumer repos. A re-run after a partial init reuses the existing dir.
-  if (!fs.existsSync(path.join(root, '.git'))) {
-    exec(`mkdir -p ${root}`);
-    exec(`git -C ${root} init -q`);
-    exec(`git -C ${root} remote add origin ${remote}`);
-  }
-  exec(`git -C ${root} checkout -B main`);
-
-  // Core-install path (ADR 0134, task 2090). DEFAULT = vendor a tarball built from THIS
-  // control-plane checkout (offline, proven — task 2053). OPT-IN = pull the PRIVATE
-  // @bongos/core from the npm registry (PROVISION_CORE_FROM_REGISTRY=1). The registry
-  // path needs NPM_TOKEN at `npm ci` time; if the flag is set but no token is present we
-  // FAIL SOFT to the vendored path so a tokenless standup still works (never a broken
-  // instance). The env is injectable for tests; the runner falls back to process.env.
-  const env = deps.env || process.env;
-  const wantRegistry = registryCoreRequested(env);
-  const useRegistry = wantRegistry && hasNpmToken(env);
-  if (wantRegistry && !useRegistry) {
-    log('  [scaffold] PROVISION_CORE_FROM_REGISTRY set but no NPM_TOKEN in env — falling back to the vendored-tarball core (ADR 0134 fail-soft).');
-  }
-
-  // materialize config/ + .claude/ + a pinned package.json + lockfile via `bongos init`.
-  // --no-seed: the instance's own DB is seeded by migrate, not here. Two mutually
-  // exclusive core-resolution shapes:
-  //   registry (--registry-core): caret pin + env-fed .npmrc; `npm ci` pulls from the
-  //     registry. init generates the lockfile (NPM_TOKEN is present — we gated on it).
-  //   vendored (--vendor-core, default): a tarball built from this checkout, file:-pinned.
-  const spec = instanceInitSpec(inst, { ownerLogin });
-  const specPath = path.join(os.tmpdir(), `bongos-init-${inst.slug}.json`);
-  writeFile(specPath, JSON.stringify(spec, null, 2));
-  if (useRegistry) {
-    log(`  [scaffold] core install: registry — PRIVATE @bongos/core@${coreV} via env-fed NPM_TOKEN (ADR 0134)`);
-    exec(`node scripts/gds/init.js --from ${specPath} --dir ${root} --no-seed --force --registry-core`);
-  } else {
-    // Vendored tarball. PREFER a pre-built pinned tarball this control plane already has
-    // (a consumer instance's own `file:` core pin) — rebuilding via package-core.js aborts
-    // with an EMPTY core set when this runner IS a consumer instance (REPO_ROOT is inside
-    // gitignored node_modules), which left new repos empty (task 1002275). Only rebuild
-    // from source when there is no such pin (a genuine core source checkout).
-    let tgz = installedCoreTarball({ instanceRoot: deps.instanceRoot });
-    if (tgz) {
-      log(`  [scaffold] core install: reusing the pinned core tarball this control plane runs (${path.basename(tgz)}) — no source rebuild (task 1002275)`);
-    } else {
-      log(`  [scaffold] core install: building a fresh vendored tarball from source (package-core.js)`);
-      exec(`node scripts/gds/package-core.js`);                      // cwd = REPO_ROOT → dist/bongos-core-<v>.tgz
-      tgz = path.join(REPO_ROOT, 'dist', `bongos-core-${coreV}.tgz`);
-    }
-    exec(`node scripts/gds/init.js --from ${specPath} --dir ${root} --no-seed --force --vendor-core ${tgz}`);
-  }
-
-  // 4. commit + push the scaffold to the instance's own main (keep node_modules out).
-  writeFile(path.join(root, '.gitignore'), INSTANCE_GITIGNORE);
-  exec(`git -C ${root} config user.name "Cloud Bongos"`);
-  exec(`git -C ${root} config user.email "bot@cloudbongos.com"`);
-  exec(`git -C ${root} add -A`);
-  exec(`git -C ${root} commit -m "chore: scaffold ${inst.slug} on a pinned @bongos/core ${coreV} (provision.js, ADR 0108)"`, { allowFail: true });
-  // Push. A GitHub DEPLOY KEY is per-repo, so the box's shared key can't write to a NEW
-  // project repo — the second empty-repo cause (task 1002317). PREFER the instance owner's
-  // OAuth token (it CREATED the repo via github-repos.createUserRepo, so `public_repo`
-  // already grants write). The token rides a chmod-600 git credential-store file — never
-  // the logged command or makeExec's env (both are surfaced) — and is removed right after
-  // (finally, so a failed push can't leave it on disk). No token (org-owned repo, or
-  // secret-box off) → fall back to the SSH `origin` push (unchanged; e.g. an instance whose
-  // matching deploy key was cloned into origin). `deps.getGithubToken` is injectable for
-  // tests; production resolves it lazily against the core db slice with the runner's pool.
+  // Resolve the instance owner's OAuth token BEFORE any git network op.
+  //
+  // Greenfield only needed it at PUSH time, so the lookup used to live down beside the
+  // push. Adopt needs it EARLIER: its first act is to clone the owner's own repo, and a
+  // PRIVATE one is unreadable by the control plane's shared deploy key (a deploy key is
+  // per-repo). Since ADR 0155 this token carries the `repo` scope, so it can both read and
+  // write the owner's private repos — which is what makes adopt possible at all.
+  //
+  // A GitHub DEPLOY KEY is per-repo, so the box's shared key also can't WRITE to a new
+  // project repo — the second empty-repo cause (task 1002317) — hence preferring this
+  // token on both paths. It rides a chmod-600 git credential-store file, never the logged
+  // command or makeExec's env (makeExec surfaces both), and is removed in a `finally` so a
+  // failed git op can't leave it on disk. No token (org-owned repo, or secret-box off) →
+  // fall back to the SSH `origin` remote. `deps.getGithubToken` is injectable for tests;
+  // production resolves it lazily against the core db slice with the runner's pool.
   let ownerToken = null;
   if (inst.owner_builder_id) {
     try {
@@ -520,21 +509,166 @@ async function scaffoldStandaloneRepo(inst, deps) {
       ownerToken = r && r.token ? r.token : null;
     } catch (e) { log(`  [scaffold] owner OAuth token lookup failed (${e && e.message}) — using the SSH remote`); }
   }
-  if (ownerToken) {
-    const credFile = path.join(os.tmpdir(), `bongos-gitcred-${inst.slug}-${process.pid}`);
-    writeFile(credFile, `https://x-access-token:${ownerToken}@github.com\n`, { mode: 0o600 });
-    const httpsUrl = `https://x-access-token@github.com/${repo.owner}/${repo.name}.git`;
-    try {
-      exec(`git -C ${root} -c credential.helper='store --file=${credFile}' push ${httpsUrl} HEAD:main`);
-      log(`  [scaffold] pushed to ${repo.owner}/${repo.name}@main via the owner's GitHub token (task 1002317)`);
-    } finally {
-      exec(`rm -f ${credFile}`, { allowFail: true });
+  // The credential-store file + the credential-LESS URL git resolves against it. The URL
+  // carries only the `x-access-token` username (no secret), so it is safe in a logged argv.
+  const credFile = ownerToken ? path.join(os.tmpdir(), `bongos-gitcred-${inst.slug}-${process.pid}`) : null;
+  const httpsUrl = `https://x-access-token@github.com/${repo.owner}/${repo.name}.git`;
+  const credOpt = credFile ? `-c credential.helper='store --file=${credFile}' ` : '';
+  if (credFile) writeFile(credFile, `https://x-access-token:${ownerToken}@github.com\n`, { mode: 0o600 });
+
+  try {
+    // 1. Materialize the working tree.
+    //
+    //    ADOPT — CLONE the owner's existing repo, so its history + files come along and the
+    //    layer commit lands as an ordinary descendant of its current tip. This is the whole
+    //    point: `git init`ing a fresh tree here produces an UNRELATED history, which the
+    //    remote rejects as a non-fast-forward (and, were it ever forced, would erase the
+    //    owner's work). Cloning over the token's HTTPS URL also covers the private case the
+    //    shared deploy key cannot read.
+    //
+    //    GREENFIELD — a freshly-created instance repo is EMPTY (github-repos.createUserRepo,
+    //    auto_init:false), so there is NOTHING to clone; and the shared PROVISION_GIT_SSH_ALIAS
+    //    deploy key can't even READ a consumer's brand-new repo under their own account
+    //    (`git clone` fails "Repository not found" — the clone-side twin of the task-1002317
+    //    push bug). So `git init` locally and set `origin` to the SSH remote for the no-token
+    //    fallback push. Unchanged behavior.
+    //
+    //    Either way a re-run after a partial attempt reuses the existing dir.
+    const hasGit = fs.existsSync(path.join(root, '.git'));
+    if (mode === 'adopt') {
+      if (!hasGit) {
+        exec(`mkdir -p ${root}`);
+        exec(`git ${credOpt}clone ${credFile ? httpsUrl : remote} ${root}`);
+        // Normalize `origin` to the SSH remote, matching what the greenfield path leaves
+        // behind. Two reasons: the clone URL would otherwise persist as origin, and the
+        // ongoing deploy (standalonePullCmd → `git pull --ff-only origin main`, and the box
+        // timer's `git reset --hard origin/main`) reads origin — it must be a form that can
+        // authenticate durably, which the one-shot token URL cannot (its credential file is
+        // deleted below). Nothing durable ever holds the token either way; the pushes here
+        // always pass an explicit URL.
+        if (credFile) exec(`git -C ${root} remote set-url origin ${remote}`);
+      } else {
+        exec(`git -C ${root} ${credOpt}fetch ${credFile ? httpsUrl : 'origin'} main`);
+      }
+      // The rest of provisioning is main-only (standalonePullCmd is `git pull --ff-only
+      // origin main`, and the box's deploy timer does `git reset --hard origin/main`), so a
+      // repo whose default branch is not `main` would be layered and pushed somewhere the
+      // deploy never reads. Fail loudly with the fix rather than silently half-working.
+      const head = exec(`git -C ${root} rev-parse --abbrev-ref HEAD`, { allowFail: true });
+      const branch = String((head && head.stdout) || '').trim();
+      if (branch && branch !== 'main' && branch !== 'HEAD') {
+        throw new Error(`standalone instance ${inst.slug}: adopting ${repo.owner}/${repo.name} but its default branch is "${branch}", not "main". The instance deploy only ever reads origin/main, so the layer would never be served. Rename the default branch to main (or point target_ref at a repo whose default is main) and re-run.`);
+      }
+      exec(`git -C ${root} checkout main`, { allowFail: true });
+    } else {
+      if (!hasGit) {
+        exec(`mkdir -p ${root}`);
+        exec(`git -C ${root} init -q`);
+        exec(`git -C ${root} remote add origin ${remote}`);
+      }
+      exec(`git -C ${root} checkout -B main`);
     }
-  } else {
-    exec(`git -C ${root} push -u origin main`);
-    log(`  [scaffold] pushed initial scaffold to ${repo.owner}/${repo.name}@main (SSH origin)`);
+
+    // Core-install path (ADR 0134, task 2090). DEFAULT = vendor a tarball built from THIS
+    // control-plane checkout (offline, proven — task 2053). OPT-IN = pull the PRIVATE
+    // @bongos/core from the npm registry (PROVISION_CORE_FROM_REGISTRY=1). The registry
+    // path needs NPM_TOKEN at `npm ci` time; if the flag is set but no token is present we
+    // FAIL SOFT to the vendored path so a tokenless standup still works (never a broken
+    // instance). The env is injectable for tests; the runner falls back to process.env.
+    const env = deps.env || process.env;
+    const wantRegistry = registryCoreRequested(env);
+    const useRegistry = wantRegistry && hasNpmToken(env);
+    if (wantRegistry && !useRegistry) {
+      log('  [scaffold] PROVISION_CORE_FROM_REGISTRY set but no NPM_TOKEN in env — falling back to the vendored-tarball core (ADR 0134 fail-soft).');
+    }
+
+    // materialize config/ + .claude/ + a pinned package.json + lockfile via `bongos init`.
+    // --no-seed: the instance's own DB is seeded by migrate, not here (and on the adopt path
+    // the REAL-state seeding + backlog import happen when the owner runs `bongos init --adopt`
+    // themselves, against the live instance — the step the wizard walks them through).
+    //
+    // MODE FLAGS. Greenfield passes --force (overwrite is safe on an empty repo). Adopt passes
+    // --adopt --accept instead and NEVER --force: --adopt takes init's layering path, which
+    // writes each config only where absent and leaves pre-existing files untouched, and
+    // --accept clears the interactive pre-flight gate for this non-interactive runner (a
+    // BLOCKING pre-flight finding still hard-stops — it cannot be waved through). init refuses
+    // --adopt together with --force, so the two flag sets are mutually exclusive by design.
+    //
+    // Two mutually exclusive core-resolution shapes, orthogonal to the mode:
+    //   registry (--registry-core): caret pin + env-fed .npmrc; `npm ci` pulls from the
+    //     registry. init generates the lockfile (NPM_TOKEN is present — we gated on it).
+    //   vendored (--vendor-core, default): a tarball built from this checkout, file:-pinned.
+    const modeFlags = mode === 'adopt' ? '--adopt --accept' : '--force';
+    const spec = instanceInitSpec(inst, { ownerLogin });
+    const specPath = path.join(os.tmpdir(), `bongos-init-${inst.slug}.json`);
+    writeFile(specPath, JSON.stringify(spec, null, 2));
+    if (useRegistry) {
+      log(`  [scaffold] core install: registry — PRIVATE @bongos/core@${coreV} via env-fed NPM_TOKEN (ADR 0134)`);
+      exec(`node scripts/gds/init.js --from ${specPath} --dir ${root} --no-seed ${modeFlags} --registry-core`);
+    } else {
+      // Vendored tarball. PREFER a pre-built pinned tarball this control plane already has
+      // (a consumer instance's own `file:` core pin) — rebuilding via package-core.js aborts
+      // with an EMPTY core set when this runner IS a consumer instance (REPO_ROOT is inside
+      // gitignored node_modules), which left new repos empty (task 1002275). Only rebuild
+      // from source when there is no such pin (a genuine core source checkout).
+      let tgz = installedCoreTarball({ instanceRoot: deps.instanceRoot });
+      if (tgz) {
+        log(`  [scaffold] core install: reusing the pinned core tarball this control plane runs (${path.basename(tgz)}) — no source rebuild (task 1002275)`);
+      } else {
+        log(`  [scaffold] core install: building a fresh vendored tarball from source (package-core.js)`);
+        exec(`node scripts/gds/package-core.js`);                      // cwd = REPO_ROOT → dist/bongos-core-<v>.tgz
+        tgz = path.join(REPO_ROOT, 'dist', `bongos-core-${coreV}.tgz`);
+      }
+      exec(`node scripts/gds/init.js --from ${specPath} --dir ${root} --no-seed ${modeFlags} --vendor-core ${tgz}`);
+    }
+
+    // 4. commit + push to the instance's own main (keep node_modules out).
+    //
+    // .gitignore: greenfield OWNS the file. Adopt must not clobber the owner's existing
+    // ignores, so it only writes one where none exists — and where one does, it APPENDS the
+    // entries we actually require (node_modules/, the vendored-core exceptions, the generated
+    // nav docs) if they are missing, since `npm ci` + `git reset --hard` on the box depend on
+    // them. Duplicate lines in a .gitignore are harmless, so the append is idempotent-safe.
+    const giPath = path.join(root, '.gitignore');
+    if (mode === 'adopt' && fs.existsSync(giPath)) {
+      const existing = fs.readFileSync(giPath, 'utf8');
+      const missing = INSTANCE_GITIGNORE.split('\n')
+        .filter((l) => l.trim() && !l.startsWith('#'))
+        .filter((l) => !existing.split('\n').some((e) => e.trim() === l.trim()));
+      if (missing.length) {
+        writeFile(giPath, `${existing.replace(/\n*$/, '\n')}\n# Added by Cloud Bongos (adopt) — required by the instance deploy.\n${missing.join('\n')}\n`);
+        log(`  [scaffold] appended ${missing.length} required .gitignore entr(ies) — existing rules left intact`);
+      } else {
+        log('  [scaffold] .gitignore already covers the required entries — left untouched');
+      }
+    } else {
+      writeFile(giPath, INSTANCE_GITIGNORE);
+    }
+    exec(`git -C ${root} config user.name "Cloud Bongos"`);
+    exec(`git -C ${root} config user.email "bot@cloudbongos.com"`);
+    exec(`git -C ${root} add -A`);
+    const commitMsg = mode === 'adopt'
+      ? `chore: adopt Cloud Bongos onto ${inst.slug} on a pinned @bongos/core ${coreV} (provision.js, ADR 0121)`
+      : `chore: scaffold ${inst.slug} on a pinned @bongos/core ${coreV} (provision.js, ADR 0108)`;
+    exec(`git -C ${root} commit -m "${commitMsg}"`, { allowFail: true });
+
+    // Push. NO --force on either path, ever (see the function header): the ADR 0155 `repo`
+    // credential can write to every repo the owner owns, so a force here would be a route to
+    // destroying their work. Adopt's commit is a descendant of the tip it cloned, so an
+    // ordinary push fast-forwards; if the remote moved underneath us the rejection is the
+    // correct outcome and a re-run picks up the new tip.
+    if (credFile) {
+      exec(`git -C ${root} ${credOpt}push ${httpsUrl} HEAD:main`);
+      log(`  [scaffold] ${mode === 'adopt' ? 'pushed the adopt layer' : 'pushed'} to ${repo.owner}/${repo.name}@main via the owner's GitHub token (task 1002317)`);
+    } else {
+      exec(`git -C ${root} push -u origin main`);
+      log(`  [scaffold] pushed ${mode === 'adopt' ? 'the adopt layer' : 'initial scaffold'} to ${repo.owner}/${repo.name}@main (SSH origin)`);
+    }
+    return { ok: true, scaffolded: true, mode };
+  } finally {
+    // Always remove the credential file — a failed clone/push must not leave it on disk.
+    if (credFile) exec(`rm -f ${credFile}`, { allowFail: true });
   }
-  return { ok: true, scaffolded: true };
 }
 
 // The per-instance systemd unit (the infra/cloudbongos.service shape): one Node process
@@ -1767,6 +1901,8 @@ module.exports = {
   standaloneRoot, standalonePullCmd, standaloneInstallCmd, standaloneMigrateCmd,
   // standalone scaffold (ADR 0108 / 0125, task 2055; consumer-core fix task 1002275)
   parseTargetRef, instanceRepoRemote, instanceInitSpec, installedCoreTarball, scaffoldStandaloneRepo, coreVersionSafe,
+  // adopt vs greenfield onboarding (ADR 0121, task 1002562)
+  onboardMode, alreadyScaffolded,
   zoneForDomain, dnsUpsertEnv, classifyZoneScope, checkDnsTokenScope,
   caddyBlock, caddySnippetPath, healthzCmd, dedicatedUserData, nextFreePort,
   // executors + orchestration (injectable deps for tests)

package/scripts/gds/run-unit-tests.js

@@ -74,7 +74,7 @@ const INTEGRATION = new Set([
   // .github/workflows/consumer-layout-boot.yml, not this DB-free gate (task 2142).
   'consumer_layout_boot',
   'claim_gate_rebase', 'clawback_confirmed_backlog', 'discord_autojoin', 'discord_oauth',
-  'linkify_refs', 'memory_isolation',
+  'governance_fold_bench', 'governance_live_proof', 'linkify_refs', 'memory_isolation',
   'memory_pull', 'needs_rebase', 'parallel-load', 'reward_mode_cost_plus_only',
   'session_records', 'setup_smoke',
   'status-probe', 'subdomain_auth',
@@ -96,6 +96,14 @@ const KNOWN_FAILING = new Set([
   'autotile_variants',
   'autotile_xverify',
   'anti_grid',
+  // #1002617: red in every clean environment (Linux CI and a Windows checkout
+  // alike), surfaced by the unit lane's first-ever runs. Parked so the `unit`
+  // check can be required (a gate that's already red gates nothing); per-test
+  // diagnoses live in that task. Remove each here as it is fixed.
+  // PAIRING: tests/known_failing_ratchet.mjs keeps EXECUTING each parked test
+  // and fails the suite the moment one starts passing — so this set cannot rot.
+  'platform_boot',
+  'served_paths_shipped',
 ]);
 
 // Discover modules/<key>/tests/*.mjs. Pure-ish (reads disk; `isEnabled` is

package/scripts/gds/sandbox-stage.js

@@ -199,6 +199,28 @@ function restartPreview(deps = {}) {
   run(cmd, argv, { stdio: 'inherit' });
 }
 
+// task 1002607: the discriminator probe URL — same origin as the health URL, at
+// the API healthz path only the FULL server mounts. Pure + exported for tests.
+function apiHealthzProbeUrl(healthUrl) {
+  try { return new URL('/api/gds/healthz', healthUrl).toString(); } catch { return null; }
+}
+
+// task 1002607: is the thing answering the health URL actually the MAIN server?
+// The game-only preview entry (ADR 0052) mounts no /api/gds, so a 200 from the
+// API healthz proves the answerer is the full server — whose default bind is the
+// SAME 127.0.0.1:3000 the box health check probes — not the preview. A probe
+// error/404 means "not the main server", which is the expected preview answer.
+async function answeredByMainServer(healthUrl, fetchImpl) {
+  const probe = apiHealthzProbeUrl(healthUrl);
+  if (!probe) return false;
+  try {
+    const res = await fetchImpl(probe, { signal: AbortSignal.timeout(5_000) });
+    return res.status === 200;
+  } catch {
+    return false;
+  }
+}
+
 async function waitHealthy(deps = {}) {
   const fetchImpl = deps.fetchImpl || fetch;
   const healthUrl = deps.healthUrl || HEALTH_URL;
@@ -207,7 +229,19 @@ async function waitHealthy(deps = {}) {
   while (Date.now() < deadline) {
     try {
       const res = await fetchImpl(healthUrl, { signal: AbortSignal.timeout(5_000) });
-      if (res.status < 500) return { ok: true };
+      // task 1002607: was `< 500`, which called a 404 "healthy" — any wrong server
+      // with nothing at '/' passed. And a good status alone doesn't prove the
+      // PREVIEW answered: the main server binds the same port, so a dead preview
+      // "passed" whenever the full server was up. Cross-examine the answerer.
+      if (res.status < 400) {
+        if (await answeredByMainServer(healthUrl, fetchImpl)) {
+          return {
+            ok: false,
+            reason: `${healthUrl} is answered by the MAIN server (/api/gds/healthz responded 200), not the game preview — the preview did not start (its port is taken by the full server)`,
+          };
+        }
+        return { ok: true };
+      }
       lastErr = `HTTP ${res.status}`;
     } catch (e) {
       lastErr = e.message;
@@ -536,9 +570,7 @@ async function runShipGate({ taskId, files, skipStage, tty, approved }, deps = {
   if (!staged.ok) {
     // #1068: a HARD failure (couldn't sync the worktree to the served checkout,
     // or the preview verifiably served stale code) means a review here would be
-    // a LIE — abort with the claim intact so the builder fixes it. A SOFT
-    // failure (the preview simply didn't come up) must not brick shipping — the
-    // gate is a review aid, not a wall: warn loudly and continue.
+    // a LIE — abort with the claim intact so the builder fixes it.
     if (staged.hard) {
       return {
         ok: false,
@@ -547,8 +579,16 @@ async function runShipGate({ taskId, files, skipStage, tty, approved }, deps = {
         reason: `sandbox staging could not be trusted (${staged.reason}) — fix it, then re-run /builder-ship (or --skip-stage to bypass the review). Your claim is still active`,
       };
     }
-    console.error(`warn: sandbox staging failed (${staged.reason}); continuing without the review step.`);
-    return { ok: true };
+    // task 1002607 (§4.4 station 9): a SOFT failure (the preview didn't come up)
+    // used to WARN one stderr line and return ok — the review gate silently
+    // turned itself off and the ship went on as if the review had happened.
+    // Fail closed like the smoke gate (task 1002605): abort with the claim
+    // intact; --skip-stage is the explicit, visible bypass. No review:true —
+    // this is a failure to present, not a calm review pause.
+    return {
+      ok: false,
+      reason: `sandbox staging failed (${staged.reason}) — the sandbox review step DID NOT run. Fix the preview and re-run /builder-ship, or run /builder-ship --skip-stage to explicitly ship WITHOUT the sandbox review. Your claim is still active`,
+    };
   }
 
   if (d.action === 'stage_abort') {
@@ -578,10 +618,20 @@ async function runShipGate({ taskId, files, skipStage, tty, approved }, deps = {
   return { ok: true, sandboxReview: approvalRecord('tty', staged.url, deps) };
 }
 
+// task 1002607: the old message ("this clone has no game preview entry") implied
+// the BUILDER's clone was at fault, when the commonest cause is that the checkout
+// simply carries no game — src/preview-server.js is an instance's product file
+// (the ADR 0052 game-only server); the core repo does not ship one. Name what is
+// actually missing and both real causes. Exported so the wording is pinned.
+const NO_SANDBOX_MSG =
+  'No sandbox here: this machine is not a dev box, and this checkout has no game preview entry (src/preview-server.js — the ADR 0052 game-only server).';
+const NO_SANDBOX_DETAIL =
+  'That entry file comes from an instance\'s product layer. This repo does not ship one, and a partial/sparse clone of an instance that has one also lacks it — nothing here can be staged or previewed.';
+
 async function cliMain() {
   const cmd = process.argv[2] || 'stage';
   const ctx = resolvePreviewContext();
-  const NO_SANDBOX = 'No sandbox here — not a dev box, and this clone has no game preview entry (src/preview-server.js).';
+  const NO_SANDBOX = NO_SANDBOX_MSG;
 
   if (cmd === 'url') {
     console.log(ctx && ctx.url ? ctx.url : '(no sandbox here — not a dev box, and no local game preview in this clone)');
@@ -606,9 +656,12 @@ async function cliMain() {
     process.exit(2);
   }
   if (!ctx) {
+    // task 1002607: an explicit `stage` invocation that can stage nothing is a
+    // FAILED command, not a quiet success — exit 1 was exit 0, which read as
+    // "staged fine" to any caller that only checks the code.
     console.log(NO_SANDBOX);
-    console.log('A full local clone gets a private localhost preview; a partial clone does not.');
-    return;
+    console.log(NO_SANDBOX_DETAIL);
+    process.exit(1);
   }
   const res = await stage({});
   if (!res.ok) {
@@ -643,6 +696,10 @@ module.exports = {
   syncWorktreeToServed,
   pickVerifyTarget,
   verifyServedFresh,
+  // task 1002607: the health truth table + the honest no-sandbox wording, pinned.
+  waitHealthy,
+  apiHealthzProbeUrl,
+  NO_SANDBOX_MSG,
 };
 
 if (require.main === module) {

package/scripts/gds/search-ingest-md.js

@@ -48,6 +48,7 @@ const SENSITIVE_DOC_GLOBS = [
   'docs/canonical-permissions.md',  // the rank-ladder / authority reference
   'docs/security/',                 // threat models + red-team reports
   'docs/audits/',                   // security + architecture audit findings
+  'docs/governance/',               // the gate ENUMERATION + choke-point map — task 1002598
   'docs/adr/0016-trust-boundary-server-enforced-permissions.md',
   'docs/adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md',
 ];