@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/version-literal-guard.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// scripts/bongos/version-literal-guard.js — no ops script names a version id
+// (task 1003166 / G02, goal 1000077; criterion guards-no-hardcoded-version).
+//
+// THE INCIDENT. smoke-write.sh hardcoded 'PMS-V1'. That version shipped, so
+// `version_closed` refused every create and the write-path smoke COULD NOT PASS
+// — while /merge-mode Step 5 went on telling the operator "4/4 expected". The
+// failure reads as a broken smoke, not a stale constant, which is why it sat
+// (idea 1000823). Nine scripts carried the same bomb; four of the versions they
+// named (PMS-V1, PMS-V2, GDS-V3, GDS-V4) had ALREADY shipped when this ran.
+//
+// WHAT IT CHECKS, narrowly: a version-shaped literal ASSIGNED TO A VERSION FIELD
+// or used as a version DEFAULT, in an executable script. Not any mention of a
+// version anywhere — smoke-claim-consistency.sh legitimately says "PMS-V2 P6 not
+// live yet" in a comment and an echo, and flagging that would be the over-broad
+// source assertion this repo has learned to avoid (learning 1000196). Comment
+// lines are stripped before matching for the same reason.
+//
+// EXCLUDED BY PATH, not by allowlist: seeders and tests. A seeder's whole subject
+// IS a specific historical version — `seed-v3-tasks.js` naming GDS-V3 is correct,
+// and asking it to resolve one at runtime would break it.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// Any prefix, so a version scheme invented next year is covered too — better
+// than enumerating PMS/GDS/BONGOS/CB and finding out later that OTB-V2 slipped.
+const VERSION_LITERAL = String.raw`['"][A-Z][A-Z0-9]*-V\d+['"]`;
+// A version FIELD or a version DEFAULT — the two shapes that actually rot.
+const VERSION_FIELD = String.raw`version_id|versionId|suggested_version|target_version|DEFAULT_VERSION|VERSION_ID`;
+const ASSIGNED = new RegExp(`(?:${VERSION_FIELD})\\s*['"]?\\s*[:=][^,;)]*${VERSION_LITERAL}`);
+const DEFAULTED = new RegExp(`--version[^\\n]*?\\|\\|\\s*${VERSION_LITERAL}`);
+// A version field FALLING BACK to a literal through `||`. ASSIGNED cannot see
+// this shape: its `[^,;)]*` stops at the first `)`, so any call between the `=`
+// and the literal hides it — `DEFAULT_VERSION = resolveEnv('X') || 'BONGOS-V1'`
+// scanned CLEAN while `DEFAULT_VERSION = 'BONGOS-V1'` was caught (task 1004071).
+// That is the exact line that served a sealed version as /status's default for
+// months. Kept as its own narrow pattern rather than loosening ASSIGNED to
+// `[^;]*`, which would fire on any line merely mentioning a field and a literal
+// — the over-broad source assertion this repo keeps relearning (learning 1000196).
+const FALLBACK = new RegExp(`(?:${VERSION_FIELD})\\s*['"]?\\s*[:=][^;]*?\\|\\|\\s*${VERSION_LITERAL}`);
+
+// path::reason. A justified entry, one line, like every other guard here.
+//
+// A REASON MAY CITE THE CODE'S SHAPE, NEVER THE DATABASE'S CONTENTS (task
+// 1004071). status.js was exempted because "TWO versions are currently building
+// — so 'most recent building' is not a derivable answer here." True the day it
+// was written; false once CB-V1 sealed. Nothing re-checks prose, so the entry
+// outlived its justification in silence and /status went on serving a SHIPPED
+// version's closing scoreboard as the project's current status. An entry whose
+// truth depends on rows is a timer nobody set. `version_literals.mjs` now fails
+// CI on an entry that is outright DEAD; it cannot police one that is merely
+// stale, which is why that judgement has to be made here, when the entry is
+// written.
+const VERSION_LITERAL_ALLOW = new Map([
+  ['scripts/bongos/grade-smoke.js',
+    'GOOD_TASK / BAD_TASK are in-memory fixtures handed to grader.gradeSubagent; they are never POSTed, so no version_closed can refuse them and the literal cannot rot into a failure.'],
+]);
+
+function isExempt(rel) {
+  return /(^|\/)seed-[^/]*\.js$/.test(rel)         // a seeder's subject IS that version
+    || /\.test\.js$/.test(rel)                     // fixtures pinned to a historical version
+    || /(^|\/)fixtures\//.test(rel)
+    || /(^|\/)version-literal-guard\.js$/.test(rel); // this file names the shapes it hunts
+}
+
+// Drop comment lines only — never inline content, which is where real code lives.
+function stripComments(src, rel) {
+  const lineComment = rel.endsWith('.sh') ? /^\s*#/ : /^\s*(\/\/|\*|\/\*)/;
+  return String(src).split('\n').map((l) => (lineComment.test(l) ? '' : l));
+}
+
+function scanScripts(files, read) {
+  const violations = [];
+  let scanned = 0;
+  for (const rel of files) {
+    if (isExempt(rel)) continue;
+    const src = read(rel);
+    if (src === null) continue;
+    scanned += 1;
+    if (VERSION_LITERAL_ALLOW.has(rel)) continue;
+    stripComments(src, rel).forEach((line, i) => {
+      if (ASSIGNED.test(line) || DEFAULTED.test(line) || FALLBACK.test(line)) {
+        violations.push(
+          `${rel}:${i + 1} names a version id where one should be RESOLVED: ${line.trim().slice(0, 90)}`
+          + ' — a literal works until that version ships, then version_closed refuses every write and the'
+          + ' failure reads as broken code. Use resolveDefaultVersion() from version-select.js'
+          + ' (bash: VERSION_ID=$(node scripts/bongos/version-select.js)), or allowlist it with a reason.'
+        );
+      }
+    });
+  }
+  return { violations, scanned };
+}
+
+function trackedScripts() {
+  const out = execFileSync('git', ['ls-files', 'scripts/*.js', 'scripts/*.sh', 'scripts/**/*.js', 'scripts/**/*.sh'], {
+    cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return String(out || '').split('\n').map((f) => f.trim()).filter(Boolean);
+}
+
+const NAME = 'no ops script hardcodes a version id (G02)';
+
+function checkNoVersionLiterals({ files = null, read = null } = {}) {
+  const list = files || trackedScripts();
+  if (!list.length) {
+    return { name: NAME, ok: false, hardFail: true,
+      violations: ['scan defect — enumerated 0 tracked scripts; a broken enumeration, not a clean result.'],
+      warnings: [], note: 'static scan of scripts/ for hardcoded version ids.' };
+  }
+  const reader = read || ((rel) => {
+    try { return fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8'); } catch { return null; }
+  });
+  const { violations, scanned } = scanScripts(list, reader);
+  return {
+    name: NAME,
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} executable script(s) under scripts/ scanned: none may assign a version-shaped literal to a version field or use one as a --version default. Seeders, *.test.js and fixtures are exempt by path (their subject IS a historical version); ${VERSION_LITERAL_ALLOW.size} justified allowlist entr${VERSION_LITERAL_ALLOW.size === 1 ? 'y' : 'ies'}.`,
+  };
+}
+
+function main() {
+  const r = checkNoVersionLiterals();
+  for (const v of r.violations) console.error(`✗ ${v}`);
+  console.log(`${r.hardFail ? 'FAIL' : 'PASS'}  ${r.note}`);
+  process.exit(r.hardFail ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = { checkNoVersionLiterals, scanScripts, stripComments, isExempt, VERSION_LITERAL_ALLOW, ASSIGNED, DEFAULTED, FALLBACK };

package/scripts/bongos/version-select.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// scripts/bongos/version-select.js — resolve "the version to use" at RUNTIME
+// (task 1003166 / G02, goal 1000077; criterion guards-no-hardcoded-version).
+//
+// THE BUG THIS ENDS. scripts/bongos/smoke-write.sh hardcoded 'PMS-V1'. That version
+// shipped, so `version_closed` correctly refuses the create — meaning the
+// write-path smoke CANNOT pass — while /merge-mode Step 5 still tells the
+// operator "4/4 expected". A literal version id is a time bomb with a long fuse:
+// it works until the version ships, and then it fails in a way that reads as a
+// broken smoke rather than a stale constant (idea 1000823).
+//
+// Nine scripts carried one. The rule they now share is capture.js's, which was
+// already right: the most recent BUILDING version. Extracted here so there is one
+// implementation rather than nine, and exposed as a CLI so the bash smokes get
+// the same answer as the JS callers instead of reimplementing the sort in python.
+//
+//   const { resolveDefaultVersion } = require('./version-select.js');   // JS
+//   VERSION_ID=$(node scripts/bongos/version-select.js) || exit 1          # bash
+
+'use strict';
+
+const { cliExit } = require('./cli-lib');
+
+// PURE, so the selection rule is unit-tested without a session or a network.
+// Returns a version id, or null when nothing is building — never a guess.
+function pickDefaultVersion(versions) {
+  if (!Array.isArray(versions)) return null;
+  const building = versions.filter((v) => v && v.status === 'building');
+  if (building.length === 0) return null;
+  // Most recent by started_at. A null started_at sorts last rather than
+  // throwing, so a half-filled row cannot decide the answer (capture.js's
+  // original behaviour, kept deliberately).
+  building.sort((a, b) => {
+    const ta = a.started_at ? new Date(a.started_at).getTime() : 0;
+    const tb = b.started_at ? new Date(b.started_at).getTime() : 0;
+    return tb - ta;
+  });
+  return building[0].id;
+}
+
+async function resolveDefaultVersion(deps = {}) {
+  const client = deps.cliClient || require('./cli-lib').cliClient;
+  const api = await client();
+  const r = await api.versions.getVersions();
+  if (!r.ok) return null;
+  return pickDefaultVersion(r.data?.versions ?? []);
+}
+
+// A version id is interpolated by bash callers into a quoted Python string, so
+// the ONE place that can guarantee it is safe is here, at the source, rather than
+// four escaping fixes downstream. Ids are `[A-Za-z][A-Za-z0-9._-]*` in practice;
+// anything else is refused rather than printed. Defense in depth: writing a
+// versions.id is already a privileged operation.
+const SAFE_ID = /^[A-Za-z][A-Za-z0-9._-]*$/;
+
+async function main() {
+  const id = await resolveDefaultVersion();
+  if (!id) {
+    // Exit non-zero rather than printing something a caller would interpolate:
+    // a smoke that creates a task against the empty string is worse than one
+    // that stops and says why.
+    console.error('version-select: no version is currently `building` — cannot resolve a default.');
+    console.error('  Open one, or pass an explicit --version to the caller.');
+    return cliExit(1);
+  }
+  if (!SAFE_ID.test(id)) {
+    console.error(`version-select: refusing to emit ${JSON.stringify(id)} — not a plain version id.`);
+    console.error('  Callers splice this into a quoted string; an id with a quote or backslash could break out.');
+    return cliExit(1);
+  }
+  process.stdout.write(id);
+  return cliExit(0);
+}
+
+if (require.main === module) {
+  main().catch((err) => { console.error(`version-select: ${err && err.message}`); cliExit(1); });
+}
+
+module.exports = { pickDefaultVersion, resolveDefaultVersion, SAFE_ID };

package/scripts/bongos/visual-review-nudge.js

@@ -0,0 +1,39 @@
+'use strict';
+
+// scripts/bongos/visual-review-nudge.js — the claim-time lines that tell a session
+// its task changes a page people see (task 1004202): use /design, check it in a
+// real browser, and get the human's OK on the before/after before shipping — the
+// project default for every builder since the owner's 2026-09-23 decision.
+//
+// A NUDGE, never a gate: as a gate, the human's OK would be a person's approval in
+// the land path, which ADR 0162 retired. "Is this UI work" is the ONE predicate the
+// artist review and the grader's copy lens already use (lifecycle/cascade.js), so
+// the three cannot disagree. Nothing has changed yet at claim time, so it is fed
+// the paths the task NAMES: its touches[] and any modules/*/public/ path written
+// in its description.
+
+const { hasCopyOrVisualWork } = require('../../modules/lifecycle/cascade.js');
+
+const PUBLIC_PATH_IN_TEXT = /modules\/[\w.-]+\/public\/[^\s`'"()<>[\]{}|,;]+/g;
+
+// pathsNamedIn — touches[] plus every public/ path the description mentions,
+// with sentence punctuation stripped off the end ("…/goal-forest-lib.js." → .js).
+function pathsNamedIn(task) {
+  const touches = Array.isArray(task && task.touches) ? task.touches.filter((t) => typeof t === 'string') : [];
+  const named = (String((task && task.description) || '').match(PUBLIC_PATH_IN_TEXT) || [])
+    .map((p) => p.replace(/[.:]+$/, ''));
+  return [...touches, ...named];
+}
+
+// visualReviewNudge — the lines to print, or null when the task is not UI work.
+function visualReviewNudge(task) {
+  if (!hasCopyOrVisualWork(task, pathsNamedIn(task))) return null;
+  return [
+    '🎨 This task changes a page people see.',
+    '  Build it with /design, and check it in a real browser at desktop and phone width, light and dark.',
+    '  Before you ship: open the before/after for your human (node scripts/bongos/review-sheet.js) and wait for their OK.',
+    '  /ship-check renders the pages you changed and names any text past its box or overlapping siblings (a signal, not a gate).',
+  ];
+}
+
+module.exports = { pathsNamedIn, visualReviewNudge };

package/scripts/bongos/wedge-remedy.js

@@ -0,0 +1,174 @@
+'use strict';
+//
+// scripts/bongos/wedge-remedy.js — a core move that failed on a KNOWN snag fixes the snag and
+// tries once more (task 1004448, goal 1000090 deploy self-heal).
+//
+// WHY. upgrade-outcome.js names three failures that are not a fault in the release and not a
+// decision the owner has to make, but a mess on the box with one known fix — the fixes the
+// owner has been doing over SSH (docs/recipes/upgrading-the-core.md, Gotchas):
+//   dirty_tree      — the project's checkout has uncommitted changes to tracked files (the
+//                     upgrade's own rewrites, left behind by an earlier move). Fix: commit them
+//                     inside the project.
+//   disk_full       — the move ran out of disk. Fix: prune this project's OWN nightly
+//                     pg_dumps down to the newest few (the only thing on the box this runner
+//                     knows is safe to delete — they are copies, and the newest are kept).
+//   schema_pending  — the project's database is behind the code it is running NOW. Fix:
+//                     migrate that database, with its own PGDATABASE, before the code moves.
+//   migrate_not_owner — a migration changed a table or function the project's own account
+//                     does not OWN: provisioning made them as postgres (task 1004735). Fix:
+//                     hand ownership of the project's schema to its account, as postgres.
+//                     Heals every project provisioned before provision-repo.js did this itself.
+// intent-retry.js retires every known_wedge at once, so on its own the failure only waited
+// for a person. This file runs the fix, records it as an event on the project, and re-pends
+// the move for ONE more try.
+//
+// AT MOST ONCE PER FAILURE. The reason a fix was applied for is stored on the intent
+// (provisioning_intents.remedied_reason, migration provisioning_032). If the retry fails on
+// the SAME reason, the fix did not hold: the move is retired as `unknown` /
+// remedy_did_not_hold, which is the class that reaches a person — never a second fix, never
+// a loop. A fix that itself fails is retired the same way (remedy_failed). A different
+// known reason on the retry gets its own one fix (a disk full after a dirty tree is a new
+// snag, not the same one twice); the attempt budget still bounds the whole run.
+//
+// 'tagged-not-published' needs nothing here: it is `not_published`, a transient failure that
+// intent-retry.js already waits out.
+//
+// planRemedy is PURE (the command, never run). remedyAfterFailure does the I/O through the
+// runner's own exec and db, so every fix is testable with an injected exec.
+
+const { CONFIG } = require('./provision-config.js');
+const { dbName, dbOwnershipCmd, instanceDbRole, selfInstanceRoot, standaloneRoot } = require('./provision-repo.js');
+const { migratePlan, CORE_MIGRATE_SCRIPT, ACCOUNT_RE } = require('./upgrade-migrate.js');
+const { isValidSlug } = require('../../modules/provisioning/provisioning.js');
+const outcome = require('./upgrade-outcome.js');
+const { DEFAULT_RETRY_DELAY_MS } = require('./intent-retry.js');
+
+const REMEDY_REASONS = Object.freeze(['dirty_tree', 'disk_full', 'schema_pending', 'migrate_not_owner']);
+// The newest dumps a disk-full prune always leaves behind: a week of nightlies. The nightly
+// job's own retention is 30 days; this only ever cuts below that when the disk is full.
+const DUMP_KEEP_FLOOR = 7;
+const REMEDY_EVENT = 'core-upgrade-remedy';
+// A value that reaches a shell string below. Narrower than what Postgres or a path allow, on
+// purpose: anything outside it is refused, never quoted.
+const SHELL_SAFE_RE = /^[A-Za-z0-9._/-]{1,200}$/;
+const DB_NAME_RE = /^[A-Za-z0-9_-]{1,63}$/;
+// ACCOUNT_RE is imported, not re-declared: this file and upgrade-migrate.js check the same
+// value for the same reason (it reaches `sudo -u`), and two copies of a security predicate
+// drift one edit at a time. provision-repo.js keeps its own UNIX_ACCOUNT_RE deliberately —
+// importing from here would point the provisioner at the upgrade CLI, the wrong direction.
+
+/**
+ * The fix for one known snag, as a command to run on the box. PURE.
+ * @param {object} inst   the provisioning_instances row
+ * @param {string} reason the failure's reason code
+ * @param {object} [o]    { privileged, runAs, instanceDir, selfRoot, backupDir, migrate }
+ * @returns {{ reason, cmd, cwd, env, describe } | { refused: string } | null}  null: no known fix
+ */
+function planRemedy(inst, reason, o = {}) {
+  if (!REMEDY_REASONS.includes(reason)) return null;
+  if (!inst || !isValidSlug(inst.slug)) return { refused: 'the project name is not a valid slug' };
+  const dir = o.instanceDir || (inst.hosting_shape === 'cloud-host' ? standaloneRoot(inst) : (o.selfRoot || selfInstanceRoot)());
+  if (!SHELL_SAFE_RE.test(dir)) return { refused: 'the project folder is not a path this runner will put in a command' };
+  const db = dbName(inst);
+  if (!DB_NAME_RE.test(db)) return { refused: 'the project database name is not one this runner will put in a command' };
+
+  if (reason === 'dirty_tree') {
+    // TRACKED files only (`add -u`): the snag is the upgrade's own rewrites of tracked files.
+    // A new untracked file is not swept into the owner's history on a guess — if that is the
+    // dirt, the retry fails the same way and a person looks. Runs as the runner, which owns
+    // the checkout (pushUpgradePin's shape), with hooks off and a runner identity so the
+    // commit says who made it.
+    const g = `git -C ${dir} -c core.hooksPath=/dev/null -c user.name=bongos-runner -c user.email=runner@bongos.invalid`;
+    return {
+      reason, cwd: null, env: null,
+      cmd: `${g} add -u && ${g} commit -m "chore: commit changes left in the working tree (automatic fix before a core move)"`,
+      describe: `committed the uncommitted changes in ${dir} so the core move could run`,
+    };
+  }
+  if (reason === 'disk_full') {
+    const backupDir = o.backupDir || CONFIG.backupDir;
+    if (!SHELL_SAFE_RE.test(backupDir)) return { refused: 'the backup folder is not a path this runner will put in a command' };
+    // EXACTLY db-backup-nightly.sh's name, so this never touches a sibling project's dumps
+    // (`test` must not prune `test-nk`'s — task 1003948). The timestamp sorts by name, so
+    // `sort | head -n -K` drops all but the newest K. Nothing is deleted when K or fewer exist.
+    const D = '[0-9]';
+    const glob = `${db}-${D}${D}${D}${D}-${D}${D}-${D}${D}T${D}${D}${D}${D}${D}${D}Z.sql.gz`;
+    return {
+      reason, cwd: null, env: null,
+      cmd: `find ${backupDir} -maxdepth 1 -type f -name '${glob}' | sort | head -n -${DUMP_KEEP_FLOOR} | xargs -r rm -f --`,
+      describe: `pruned ${db}'s old database backups in ${backupDir}, keeping the newest ${DUMP_KEEP_FLOOR}`,
+    };
+  }
+  if (reason === 'migrate_not_owner') {
+    // A control plane migrates as its own app user, which created its tables — there is no
+    // separate project account to hand them to, so the snag cannot be this one there.
+    if (inst.hosting_shape === 'control-plane') return { refused: 'the control plane has no separate project account to hand its tables to' };
+    const role = instanceDbRole(inst);
+    return { reason, cwd: null, env: null, cmd: dbOwnershipCmd(inst, { privileged: o.privileged }), describe: `handed ownership of ${db}'s tables and functions to ${role}, the account its migrations run as` };
+  }
+  // schema_pending — the project's OWN migrate command (a declared script wins, else the
+  // core's migrate.sh: upgrade-migrate.js), aimed at its OWN database. migrate.sh defaults to
+  // production when PGDATABASE is unset, so it is always set, never inherited.
+  const plan = (o.migrate || migratePlan)(dir);
+  const run = plan.via === 'npm-script' ? 'npm run migrate' : `bash ${CORE_MIGRATE_SCRIPT}`;
+  const initCwd = plan.via === 'npm-script' ? '' : `INIT_CWD=${dir} `;
+  if (o.privileged) {
+    if (!ACCOUNT_RE.test(String(o.runAs || ''))) return { refused: 'no account to run the migration as' };
+    return { reason, cwd: dir, env: null, cmd: `sudo -u ${o.runAs} env PGDATABASE=${db} ${initCwd}${run}`, describe: `migrated ${db} to match the code it is running` };
+  }
+  return { reason, cwd: dir, env: { PGDATABASE: db, ...(initCwd ? { INIT_CWD: dir } : {}) }, cmd: run, describe: `migrated ${db} to match the code it is running` };
+}
+
+// The account the project's DATABASE belongs to, probed the way the move itself probes
+// (task 1004128). `migrateAs`, not `runAs`: since task 1004512 those are two different
+// answers, and this remedy is a migration — it needs the Postgres login role, which the
+// account that owns the checkout is not.
+function runAsFor(inst, deps) {
+  try { return require('./provision-core-upgrade.js').resolveRunAs(inst, deps).migrateAs; } catch { return null; }
+}
+
+/**
+ * After a core move failed: apply the known fix, record it, and re-pend the move once.
+ *
+ * Returns `{ repended: true }` when the move will be tried again, otherwise
+ * `{ repended: false, failure, error }` — the failure the drain loop should RETIRE with,
+ * which is the original one when there is no fix for it, and `unknown` when a fix was
+ * already spent on this reason or the fix itself failed.
+ */
+async function remedyAfterFailure({ intent, inst, result, deps }) {
+  const failure = result && result.failure;
+  const reason = failure && failure.reason;
+  const none = { repended: false, failure, error: result && result.error };
+  if (!intent || intent.action !== 'core-upgrade' || !failure || failure.class !== 'known_wedge') return none;
+  const { db, provisioning, log = () => {}, apply } = deps;
+  if (!apply) return none;
+  if (intent.remedied_reason === reason) {
+    return {
+      repended: false, failure: outcome.classifyFailure('remedy_did_not_hold'),
+      error: `${result.error || 'core move failed'} — the automatic fix for this (${reason}) was already tried once and did not clear it, so a person needs to look`,
+    };
+  }
+  const boxExec = inst.hosting_shape === 'cloud-host' ? (deps.controlExec || deps.exec) : deps.exec;
+  const plan = planRemedy(inst, reason, { privileged: deps.privileged, runAs: reason === 'schema_pending' && deps.privileged ? runAsFor(inst, deps) : null, selfRoot: deps.selfInstanceRoot, migrate: deps.migratePlan });
+  if (!plan) return none;
+  const giveUp = async (why) => {
+    await provisioning.recordEvent(db, { instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: REMEDY_EVENT, detail: `could not fix ${reason} automatically: ${why}`, actor: 'runner' }).catch(() => {});
+    return { repended: false, failure: outcome.classifyFailure('remedy_failed'), error: `${result.error || 'core move failed'} — the automatic fix for ${reason} did not work (${why}), so a person needs to look` };
+  };
+  if (plan.refused) return giveUp(plan.refused);
+  log(`  [remedy] ${reason}: ${plan.cmd}`);
+  const r = boxExec(plan.cmd, { allowFail: true, ...(plan.cwd ? { cwd: plan.cwd } : {}), ...(plan.env ? { env: plan.env } : {}) });
+  if (!r || r.softFailed === true || r.ok === false) {
+    const said = String((r && (r.stderr || r.stdout || r.error)) || 'the command failed').trim().split('\n').pop().slice(0, 160);
+    return giveUp(said);
+  }
+  await provisioning.recordEvent(db, { instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: REMEDY_EVENT, detail: `${plan.describe}; trying the move to ${intent.target_version} once more`, actor: 'runner' }).catch(() => {});
+  await db.query(
+    `UPDATE provisioning_intents SET state='pending', last_error=$2, remedied_reason=$3, failure_class=$4, failure_reason=$5,
+            not_before = now() + ($6 * interval '1 millisecond'), updated_at=now() WHERE id=$1`,
+    [intent.id, result.error || 'core move failed', reason, failure.class, failure.reason, DEFAULT_RETRY_DELAY_MS]);
+  log(`  ✓ fixed ${reason} on ${inst.slug}; the move to ${intent.target_version} will be tried once more`);
+  return { repended: true };
+}
+
+module.exports = { REMEDY_REASONS, DUMP_KEEP_FLOOR, REMEDY_EVENT, planRemedy, remedyAfterFailure };

package/scripts/bongos/worktree-claim-guard.js

@@ -0,0 +1,130 @@
+// scripts/bongos/worktree-claim-guard.js — worktree-per-claim, enforced at CLAIM
+// time instead of discovered at ship time (task 1002579).
+//
+// THE FAILURE THIS KILLS. A builder with direct repo access runs
+// `git checkout -b task-N` in the PRIMARY worktree (the main checkout) rather
+// than in a dedicated `.claude/worktrees/<name>`. Everything looks fine for the
+// whole session — and then ship.js's local auto-merge finds the receiving tree
+// is the very tree holding the feature branch, so there is nowhere to merge
+// INTO. The ship bails with "the main checkout is on <branch>, not main"
+// (ship-merge.js) and the task strands at `confirmed` until the server
+// reconciler or /merge-mode catches it. The cause is at claim time; the symptom
+// was hours away at ship time.
+//
+// Worktree-per-claim has been the documented default since task 1642 and the
+// claim-time context pack has warned about it since task 1002573 — but both
+// speak AFTER the claim lands, and neither stops anything. Owner directive
+// (2026-08-05): make it the enforced project default for ALL builders.
+//
+// The whole decision is the pure function below so it can be unit-tested without
+// a git repo; claim.js supplies the two facts (which kind of tree, which branch)
+// from resolveWorktreeRoot() — the SAME probe the context pack and
+// skill-preflight already use, so there is one answer to "is this the main
+// checkout", not three that can disagree.
+
+'use strict';
+
+// The documented escape hatch. Named here so the refusal text and claim.js's
+// argv parse can never drift apart.
+const ESCAPE_FLAG = '--here';
+
+// Decide whether a claim may proceed in the tree it is being run from.
+//
+//   isMainCheckout  true | false | null   — null means "could not tell" (git
+//                                           unavailable / odd checkout)
+//   branch          the current branch name, or null when unknown
+//   defaultBranch   the branch the main checkout must stay parked on
+//   allowMainCheckout  the builder passed the escape hatch
+//   taskId          only used to spell the remedy commands concretely
+//
+// Returns { verdict: 'allow' | 'warn' | 'refuse', reason, lines }.
+// - 'allow'  — a linked worktree (the correct setup), or a tree we cannot
+//              classify. NEVER refuse on a guess: an unknown tree fails open,
+//              because a false refusal blocks real work and the ship-time bail
+//              still catches the real thing.
+// - 'refuse' — the main checkout, no escape hatch. Exit before the claim lands.
+// - 'warn'   — the main checkout WITH the escape hatch: the builder has said
+//              they mean it, so say loudly what it costs and continue.
+function decideWorktreeClaim({
+  isMainCheckout,
+  branch = null,
+  defaultBranch = 'main',
+  allowMainCheckout = false,
+  taskId = null,
+} = {}) {
+  if (isMainCheckout !== true) {
+    return { verdict: 'allow', reason: isMainCheckout === false ? 'linked worktree' : 'tree kind unknown', lines: [] };
+  }
+
+  // Two shapes of the same mistake, and the second is already broken: a main
+  // checkout parked OFF its default branch has ALREADY lost the merge target,
+  // so say that rather than warning about a future that has happened.
+  const parked = branch && branch !== defaultBranch && branch !== 'HEAD';
+  const headline = parked
+    ? `the main checkout is already parked on \`${branch}\`, not \`${defaultBranch}\``
+    : `you are in the main checkout (on \`${branch || defaultBranch}\`), not a per-claim worktree`;
+  const cost = parked
+    ? `The local auto-merge at ship time merges INTO this tree — while it holds \`${branch}\` there is nowhere to merge to, so the ship strands at \`confirmed\`.`
+    : `Branching here parks the main checkout off \`${defaultBranch}\`, and the local auto-merge at ship time then has nowhere to merge INTO: the ship strands at \`confirmed\` until the server reconciler (or /merge-mode) catches it.`;
+
+  const id = taskId == null ? '<task-id>' : String(taskId);
+  const remedy = [
+    '  Work this claim in its own worktree instead:',
+    `    node scripts/bongos/worktree.js add ${id}`,
+    `    cd .claude/worktrees/task-${id}`,
+    `    node scripts/bongos/claim.js ${id}`,
+  ];
+
+  if (allowMainCheckout) {
+    return {
+      verdict: 'warn',
+      reason: headline,
+      lines: [
+        `⚠ Claiming in the MAIN CHECKOUT (${ESCAPE_FLAG} given) — ${headline}.`,
+        `  ${cost}`,
+        '  Automation that resets this tree mid-session can also take your uncommitted work with it.',
+        ...remedy,
+      ],
+    };
+  }
+
+  return {
+    verdict: 'refuse',
+    reason: headline,
+    lines: [
+      `✗ Refusing to claim here — ${headline}.`,
+      `  ${cost}`,
+      '  Worktree-per-claim is the project default (task 1642); this is the check behind it.',
+      ...remedy,
+      `  If you genuinely mean to work in the main checkout, re-run with ${ESCAPE_FLAG} (you will land at \`confirmed\` and finish through /merge-mode).`,
+    ],
+  };
+}
+
+// task 1002871 — the OTHER end of the same failure. decideWorktreeClaim stops a
+// builder parking the main checkout at CLAIM time; this speaks at RELEASE time,
+// when a claim worked under the `--here` hatch is given up and the main checkout
+// is left holding the feature branch. Nobody is watching that tree, and the next
+// ship to reach for it — possibly another builder's — is who pays: the 2026-07-28
+// incident was one parked checkout blocking the auto-merge leg for 9 tasks.
+//
+// IT WARNS AND NEVER RESTORES, deliberately. Switching the tree back to main
+// would be a destructive guess: the parked branch may hold real uncommitted work,
+// and release.js has no way to tell that from debris. Naming it is enough — the
+// person reading has the context to decide.
+//
+// Pure; returns an array of lines (empty when there is nothing to say).
+function parkedMainCheckoutWarning({ branch, defaultBranch = 'main', dirty = false } = {}) {
+  if (!branch || branch === defaultBranch || branch === 'HEAD') return [];
+  return [
+    `⚠ The main checkout is still on \`${branch}\`, not \`${defaultBranch}\`.`,
+    dirty
+      ? '  It also has uncommitted changes, so nothing here will touch it.'
+      : '  Nothing here will touch it — the branch may hold work you still want.',
+    `  While it stays parked, the local auto-merge at ship time has nowhere to merge INTO,`,
+    '  so the next ship on this machine strands at `confirmed` — including someone else\'s.',
+    `  When you are done with it:  git -C <main checkout> checkout ${defaultBranch}`,
+  ];
+}
+
+module.exports = { decideWorktreeClaim, parkedMainCheckoutWarning, ESCAPE_FLAG };