@bongos/core 1.19.37 → 1.19.39

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.37",
-  "core_contract": "1.19.37",
-  "source_commit": "606cc770b09032c6ab385e1326f79b08c19e0083",
+  "core_version": "1.19.39",
+  "core_contract": "1.19.39",
+  "source_commit": "d61c48b44f6f117383794f20d49b5bd7b83d35d7",
   "source_ref": "HEAD",
-  "built_at": "2026-08-11T16:06:38.933Z",
+  "built_at": "2026-08-11T16:25:51.076Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 287,
+    "docs_redacted": 288,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1211,
+    "functional_verbatim": 1212,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1519,
-  "tree_sha256": "faa022ab6fb5e04c311cd4d24d2991b07d15fb5fa565dffa0862d87fdf1e546d",
+  "file_count": 1521,
+  "tree_sha256": "14c889242599811c768effd9bc7ef844e4a6ee4ef0a041c74ff1629fda6f8907",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -159,6 +159,11 @@
       "mode": "0000644",
       "sha256": "e0bf90fa006499aee0a7d75f10fe4b5972c9501129b1e432e7d6e192b367a54c"
     },
+    {
+      "path": ".claude/skills/grader-health/SKILL.md",
+      "mode": "0000644",
+      "sha256": "b9823a6a14b4197f7dae90c8ad6713fcc5b3ce672d03d7b59c8e868d5d6ba70e"
+    },
     {
       "path": ".claude/skills/idea-triage/SKILL.md",
       "mode": "0000644",
@@ -1357,7 +1362,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "a499551f07ce8f6382aba46641fb06fa8e499d486433ee3bf266f264abac29ca"
+      "sha256": "f51d3978f50ec9b2a34dc12b8fa3b9e8874543e5ab3503f72a09d7d2b06c565b"
     },
     {
       "path": "docs/handoff-template.md",
@@ -3377,7 +3382,7 @@
     {
       "path": "modules/lifecycle/github-push.js",
       "mode": "0000644",
-      "sha256": "60b9338ed47d01e9f38fe3fa9f2f2cde6ff241b8e47efcb8fcf4c4f19d32c766"
+      "sha256": "9658ccf0dd332d6c4ce1e269c2966ebe2e2bed5f909d5d503722d8e8cfb1ebbc"
     },
     {
       "path": "modules/lifecycle/goal-advisory.js",
@@ -3432,7 +3437,7 @@
     {
       "path": "modules/lifecycle/publish-reconciler.js",
       "mode": "0000644",
-      "sha256": "964af2331007a4cfb9142e7245d7625cf21c973e4f885e0171855b9e188b9e95"
+      "sha256": "ad57ad242956c6ee3dc4aeddd66e980af48737fab644765aa3c400720f4a9668"
     },
     {
       "path": "modules/lifecycle/routes/analytics.js",
@@ -4017,12 +4022,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "acab5dbbe8ab00da496f534457882de0c115d441e9f0e38fae6f5a901a4b3f47"
+      "sha256": "12291ed6b1927973c8d8c42c5384d7ba2368779b9a39c566336253069214cfb2"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "c33f5baf3eddd6b7bdcf80af532dc04d290e394b5c51b90931aa52d0ead94e6a"
+      "sha256": "18139931183bcb89c64704ae5167ab99d1e8ae9841728870b277959af8523069"
     },
     {
       "path": "public-docs/index.html",
@@ -5642,7 +5647,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "8066ee5e98e151dfc62228626a99a86f362697410aac483de27c75851cc3bdea"
+      "sha256": "5f51d5f403c88eedf838dab85e4a9ddfa8ff575ec07b5f1189e12999001a335a"
     },
     {
       "path": "src/module-loader/loader.js",
@@ -6412,7 +6417,7 @@
     {
       "path": "tests/github_push_merge_driver.mjs",
       "mode": "0000644",
-      "sha256": "1e038780532078d8d1a20feebb95ee6762fb300101f71cfff7076d2fa0d38b1b"
+      "sha256": "850113ed91babc9eb54dc22231f194d283fd3f94cee9deef1e6e0bf6f3a969c2"
     },
     {
       "path": "tests/github_repos_helpers.mjs",
@@ -7142,7 +7147,7 @@
     {
       "path": "tests/publish_reconciler.mjs",
       "mode": "0000644",
-      "sha256": "240337de03354de198d6baaaca9f33b267aceb40a8ba43d31303eb21fad9226c"
+      "sha256": "1aeb87a14e411160784c94ee5392f323a2ad0a373bd9acf91337289041e8d2bc"
     },
     {
       "path": "tests/rank_gate.mjs",
@@ -7464,6 +7469,11 @@
       "mode": "0000644",
       "sha256": "76bed8e6fae3bd77d4b45be14d9f80bda71b2f92323fa5697a7e4f07b65d3ba2"
     },
+    {
+      "path": "tests/skill_grader_health.mjs",
+      "mode": "0000644",
+      "sha256": "4557c934704a009612ed8858c0f59c5b53facb5d92fa2c0740b1aecb079aa5c9"
+    },
     {
       "path": "tests/skill_prefs.mjs",
       "mode": "0000644",

package/.claude/skills/grader-health/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: grader-health
+description: Read-only health check over recent grades — consecutive outage runs, pass-rate drift vs baseline, per-grade cost anomalies, and stale model pins. The routine that would have caught the 21-outage 0.0-score streak on day one. Triggers when the user says "/grader-health", "check the grader", "is the grader healthy", "grader health check", "why are grades failing lately", or as part of a periodic ops sweep. Reports and emits exact remediation lines; changes nothing (ADR 0162 — no new gates, describe only). Optional --probe runs a live paid calibration (Metic+).
+---
+
+You are running a health check over the grading panel. Everything here is **read-only**: you read live surfaces, compare against known baselines, and emit findings + exact remediation commands. You never confirm, flip, or re-grade anything yourself — the builder (or /grade-recover) acts on what you report.
+
+## The four axes
+
+### 1 — Outage runs (the pattern this skill exists to catch)
+
+A grader outage used to be recorded as a 0.0 "quality failure": one builder accumulated **21 zero-score rows** over a month before anyone noticed, and the public tile showed a phantom 5-day 0%-pass crater. Since the outage-as-zero fix, aggregates exclude outage rounds and bucket them as `n_unavailable` — so the streak is now directly readable.
+
+1. Read the public trend: `node scripts/gds/api.js GET "/api/gds/public/grades?days=30"` — scan `trend[]` for days where the average is 0 (or null) with passes 0 and n ≥ 2, and for any nonzero `n_unavailable` streak.
+2. (Archon) Read the per-builder split: `node scripts/gds/api.js GET "/api/gds/grades/by-builder?days=30"` — a single builder with pass_rate 0.000 or a large `n_unavailable` bucket is the 21×0.0 shape localized to one machine or one environment.
+3. **Confirm outage vs rejection before alarming anyone.** For each task in a suspect window: `node scripts/gds/api.js GET "/api/gds/tasks/<id>?include=grade"` — `signals.panel_outcome='unavailable'` (with `grader_unavailable_reason` and per-worker errors in `signals.workers`) is an outage, **not a quality rejection**; a real FAIL carries findings in `issues[]`.
+4. For every task parked at `completed` by a confirmed outage, emit the exact remediation line, one per task:
+
+```bash
+node scripts/gds/ship.js <id> --regrade
+```
+
+5. Check the local spawn leg: the panel spawns `claude -p` subprocesses, so verify the CLI is present and authenticated, and run `node scripts/gds/doctor.js` for the hooks/worktree leg.
+
+### 2 — Pass-rate drift
+
+Baselines: the 14-agent evaluation window measured a **90.6%** pass rate, already above the 87% that ADR 0024 called "suspiciously high" and built the adversarial panel to fix. From `/api/gds/public/grades` compute the rolling pass rate and compare:
+
+- **Creeping up** past the baseline → grade inflation; the panel is rubber-stamping (report; candidate causes: score compression, reused grades, trivial-path overuse).
+- **Collapsing** far below it → either a real quality regression or an unconfirmed outage window — axis 1 disambiguates.
+
+### 3 — Cost anomalies
+
+Benchmark: mean panel cost **$2.14** per grade, and ~90% of it is **fixed** re-exploration cost, independent of diff size. Read grader spend: `node scripts/gds/api.js GET "/api/gds/public/cost-summary?source=grader&days=30"` and divide by the grade count from axis 2's window.
+
+- Mean drifting well above the benchmark → panel re-rolls/retries or timeout-and-retry loops (not "big diffs" — the fixed-cost share means diff size barely moves the mean).
+- Near-zero spend with grades still recording → the trivial path or grade reuse dominating; spot-check that gating lenses are actually running.
+
+### 4 — Model pins
+
+The evaluation found every grade ran on a generation-stale pin. Read the live pin from the repo: `DEFAULT_GRADER_MODEL` and `selectGraderModel` in `modules/grading/grader.js`, plus the rubric version in `modules/grading/grader-rubric.json`. Report when the pinned family is a generation behind the current Claude family, or when `selectGraderModel` would throw on a current builder model id (it throws on ids lacking opus/sonnet/haiku — a stranded-ship risk).
+
+## Optional: `--probe` (live calibration, spends real money)
+
+With `--probe`, run the live panel calibration: `node scripts/gds/grade-smoke.js`. It grades known-good and known-bad fixtures against the real panel and reports miscalibration. **Costs ~$0.30–0.90 per run; Metic+ only.** Never run it implicitly — only when the user passed `--probe` or asked for a live calibration.
+
+## Report shape
+
+End with a compact findings list, most severe first: axis, evidence (the numbers you read), verdict (outage / drift / anomaly / stale-pin / healthy), and the exact remediation command or the skill to hand off to (`/grade-recover` for a single stuck task; a GDS task via `capture.js` for systemic fixes). A clean bill of health is one line per axis.
+
+## Constraints
+
+- **Read-only, describe-only (ADR 0162).** No confirms, no regrades run by this skill, no status flips, no new gates. The remediation lines are FOR the builder to run.
+- **Confirm before alarming.** Axis 1's outage-vs-rejection check comes before any "the grader is down" conclusion — a real FAIL streak on one surface is signal, not outage.
+- **`--probe` spends money** — explicit opt-in only, Metic+.
+
+## Files this skill touches
+
+- Reads: `GET /api/gds/public/grades`, `GET /api/gds/grades/by-builder` (Archon), `GET /api/gds/public/cost-summary?source=grader`, `GET /api/gds/tasks/:id?include=grade`, `modules/grading/grader.js`, `modules/grading/grader-rubric.json`.
+- Runs (read-only): `node scripts/gds/doctor.js`; with `--probe` only: `node scripts/gds/grade-smoke.js`.
+- Writes: nothing.

package/docs/file-map.md

@@ -351,6 +351,7 @@ tests/
 ├── goal-create/SKILL.md           ← /goal-create — plan and create ONE goal (the module-scoped workspace between version and criteria, ADR 0086) in one session: <redacted>, scope wall, 2-4 criteria, seed tasks; also the auto-pickup when a task is created with no goal to live in (goal_advisory); Metic+ (Archon for a protected-module scope)
 ├── goal-review/SKILL.md           ← /goal-review — walk the criterion review queue: each auto-flagged 'met — pending review' criterion gets confirm / reject / defer; confirming a goal's last criterion auto-achieves it (ADR 0086 §6); Metic+
 ├── grade-recover/SKILL.md         ← /grade-recover N — the 'my grade failed, now what' loop: diagnose outage vs fabricated fail vs genuine fail from the persisted grade, then run the right recovery (--regrade or the auditable override-request); adds no ship-path gate (ADR 0162, task 1002655)
+├── grader-health/SKILL.md         ← /grader-health — read-only grader health check: outage runs (n_unavailable streaks, outage-vs-rejection confirmation), pass-rate drift vs baseline, per-grade cost anomalies, stale model pins; emits exact --regrade remediation lines; optional --probe live calibration (Metic+, paid) (task 1002656)
 ├── idea-triage/SKILL.md           ← /idea-triage — daily walk through the GDS idea_inbox (promote / discard / merge); Metic+
 ├── ideate/SKILL.md                ← /ideate — ideation-session playbook for ideator-discipline tasks; inverts the loop (human drives, Claude is the sounding board) ([#1267](https://example.com/builders#/task/1267))
 ├── merge-mode/SKILL.md            ← /merge-mode — manual fallback for the auto-merge: land every confirmed task (merge + smoke + deploy)

package/modules/lifecycle/github-push.js

@@ -675,6 +675,40 @@ async function mergeIfGreen({ branch }, deps = {}) {
   return { ...base, reason: `merge_api_${res.status}`, detail: detail.slice(0, 160) };
 }
 
+// task 1002666 — the carrier race. Publish-on-merge (ADR 0161) pushes a carrier
+// commit to main after EVERY land, so under an up-to-date branch-protection rule
+// a PR whose checks report after the previous merge's carrier goes BEHIND:
+// green, mergeable, and permanently stalled (GitHub's update-branch also disarms
+// auto-merge, so re-arming alone cannot recover it — observed on PR #48,
+// 2026-08-11). Server-side remedy: update the branch; checks re-run on the fresh
+// head and the next sweep's mergeIfGreen lands it. Fires ONLY on the definitive
+// BEHIND shape — GitHub reports the strict-up-to-date green-PR stall as BEHIND
+// once checks have reported; BLOCKED means checks are pending/missing and stays
+// untouched (updating there would loop on PRs that can never go green).
+// The state is re-read here even though the sweep's mergeIfGreen just read it:
+// update-branch is a WRITE, and the re-read guards against acting on a state
+// that changed between the two calls (e.g. the PR merged meanwhile) — the same
+// read-before-write discipline mergeIfGreen itself applies.
+async function updateBranchIfBehind({ branch }, deps = {}) {
+  const s = await getMergeState({ branch }, deps);
+  const base = { number: s.number, updated_now: false, merge_state: s.merge_state, reason: null };
+  if (s.merged) return { ...base, reason: 'already_merged' };
+  if (s.pr_state !== 'open') return { ...base, reason: 'no_open_pr' };
+  if (s.merge_state !== 'BEHIND') return { ...base, reason: mergeBlockReason(s) };
+  const token = await resolveToken(deps);
+  const repoInfo = deps.repoInfo || loadRepoInfo();
+  const { owner, repo } = repoInfo;
+  const doFetch = deps.fetchImpl || fetch;
+  const res = await doFetch(`https://api.github.com/repos/${owner}/${repo}/pulls/${s.number}/update-branch`, {
+    method: 'PUT',
+    headers: { ...ghHeaders(token), 'Content-Type': 'application/json' },
+    body: JSON.stringify(s.head_sha ? { expected_head_sha: s.head_sha } : {}),
+  });
+  if (res.ok) return { ...base, updated_now: true };
+  const detail = await res.text().catch(() => '');
+  return { ...base, reason: `update_api_${res.status}`, detail: detail.slice(0, 160) };
+}
+
 // task 1139 (ADR 0058): server-set commit status — the TRUSTLESS rank attestation the
 // gate-review CI check reads. Only the server (holding the App/PAT credential AND the
 // authenticated builder's server-resolved rank) can set it, so CI can trust it where it
@@ -1043,6 +1077,7 @@ module.exports = {
   getPublishStatus,
   getMergeState,
   mergeIfGreen,
+  updateBranchIfBehind,
   setCommitStatus,
   setGateOwnerApproved,
   listOpenPullRequests,

package/modules/lifecycle/publish-reconciler.js

@@ -200,6 +200,7 @@ async function runSweep(deps = {}) {
   let merged = 0;
   let resolvedConflicts = 0;
   let refreshedStale = 0; // task 1915: PRs whose stale generated indexes we regen+pushed
+  let behindUpdated = 0;  // task 1002666: green PRs behind main (carrier race) whose branch we updated
   let errors = 0;
   let unprovable = 0;   // confirmed tasks the sweep could not prove landed this pass
   let staleStrands = 0; // of those, the ones older than STALE_CONFIRMED_MS (WARN'd)
@@ -305,6 +306,38 @@ async function runSweep(deps = {}) {
             } catch (e) {
               errFn(`[publish-reconciler] conflict-resolve for task ${r.task_id} (non-blocking): ${e && e.message}`);
             }
+          } else if (
+            m && !m.merged && m.reason === 'branch_behind_base' &&
+            typeof push.updateBranchIfBehind === 'function'
+          ) {
+            // task 1002666: the ADR 0161 carrier race — every land pushes a
+            // carrier commit to main, so a green PR whose checks reported after
+            // the previous merge sits BEHIND forever (GitHub's update-branch
+            // disarms auto-merge, so it cannot recover on its own). Update the
+            // branch server-side; checks re-run on the fresh head and the NEXT
+            // sweep's mergeIfGreen lands it. Attempt-capped per branch on the
+            // shared heal map — on a hot fleet every update re-opens the race
+            // window, and a treadmill must surface, not spin.
+            const bKey = `behind:${branch}`;
+            const bn = attempts.get(bKey) || 0;
+            if (bn >= MAX_STALE_HEAL_ATTEMPTS) {
+              logFn(
+                `[publish-reconciler] task ${r.task_id} (${branch}) PR #${m.number} still behind main after ${bn} update-branch attempt(s) — capped (merge traffic is outracing this PR); left for a human`
+              );
+            } else {
+              attempts.set(bKey, bn + 1);
+              try {
+                const u = await push.updateBranchIfBehind({ branch });
+                if (u && u.updated_now) {
+                  behindUpdated++;
+                  logFn(
+                    `[publish-reconciler] task ${r.task_id} (${branch}) PR #${u.number} was green but behind main (carrier race) — server-updated the branch; checks re-run, lands next sweep`
+                  );
+                }
+              } catch (e) {
+                errFn(`[publish-reconciler] update-branch for task ${r.task_id} (non-blocking): ${e && e.message}`);
+              }
+            }
           } else if (
             m && couldBeStaleGenerated(m) &&
             typeof resolver.refreshStaleGenerated === 'function'
@@ -544,14 +577,17 @@ async function runSweep(deps = {}) {
   }
 
   // Prune the treadmill guard so it can't leak: a branch that left the confirmed set
-  // (landed, or released) never returns under the same name, so drop it.
+  // (landed, or released) never returns under the same name, so drop it. Keys may be
+  // namespaced ('behind:<branch>', task 1002666) — compare on the branch itself so a
+  // live branch's cap survives across sweeps and a departed branch's keys still prune.
   for (const b of attempts.keys()) {
-    if (!branchesSeen.has(b)) attempts.delete(b);
+    const plain = b.startsWith('behind:') ? b.slice('behind:'.length) : b;
+    if (!branchesSeen.has(plain)) attempts.delete(b);
   }
 
-  if (reconciled || merged || resolvedConflicts || refreshedStale) {
+  if (reconciled || merged || resolvedConflicts || refreshedStale || behindUpdated) {
     logFn(
-      `[publish-reconciler] swept ${rows.length} confirmed task(s); merged ${merged} stalled PR(s); auto-resolved ${resolvedConflicts} generated/index conflict(s); regen-healed ${refreshedStale} stale-generated PR(s); reconciled ${reconciled} → shipped`
+      `[publish-reconciler] swept ${rows.length} confirmed task(s); merged ${merged} stalled PR(s); auto-resolved ${resolvedConflicts} generated/index conflict(s); regen-healed ${refreshedStale} stale-generated PR(s); branch-updated ${behindUpdated} behind-main PR(s); reconciled ${reconciled} → shipped`
     );
   }
   if (staleStrands) {
@@ -559,7 +595,7 @@ async function runSweep(deps = {}) {
       `[publish-reconciler] ${staleStrands} stale strand(s): confirmed >${Math.round(STALE_CONFIRMED_MS / 60_000)}min with no provable land — credited but unlanded; see STRAND lines above`
     );
   }
-  return { checked: rows.length, reconciled, merged, resolvedConflicts, refreshedStale, errors, unprovable, staleStrands, strandsFlagged };
+  return { checked: rows.length, reconciled, merged, resolvedConflicts, refreshedStale, behindUpdated, errors, unprovable, staleStrands, strandsFlagged };
 }
 
 // task 1366 — server-side session-cost reconcile, piggybacked on the same 5-min

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.37",
+  "version": "1.19.39",
   "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/src/module-api.js

@@ -501,8 +501,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.35 with no explicit bump. run 31509715311. (task 1002620)
 //   1.19.37 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.36 with no explicit bump. run 31510590459. (task 1002620)
+//   1.19.38 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.37 with no explicit bump. run 31511537558. (task 1002620)
+//   1.19.39 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.38 with no explicit bump. run 31512284325. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.37'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.39'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/github_push_merge_driver.mjs

@@ -169,6 +169,64 @@ test('mergeBlockReason maps the common blocker states', () => {
   assert.equal(gh.mergeBlockReason({ ...open, merged: true }), null);
 });
 
+// --- task 1002666: updateBranchIfBehind (the carrier-race branch updater) ---
+
+// fetchImpl serving graphql + recording the update-branch PUT.
+function mkUpdateFetch({ node, updateStatus = 202 } = {}) {
+  const calls = { graphql: 0, update: 0, updateArgs: null };
+  const fetchImpl = async (url, opts = {}) => {
+    if (String(url).includes('/graphql')) {
+      calls.graphql++;
+      return {
+        ok: true, status: 200,
+        json: async () => ({ data: { repository: { pullRequests: { nodes: node ? [node] : [] } } } }),
+      };
+    }
+    if (String(url).includes('/update-branch')) {
+      calls.update++;
+      calls.updateArgs = { url, body: JSON.parse(opts.body || '{}') };
+      return {
+        ok: updateStatus >= 200 && updateStatus < 300,
+        status: updateStatus,
+        text: async () => '{}',
+      };
+    }
+    throw new Error(`unexpected fetch: ${url}`);
+  };
+  return { fetchImpl, calls };
+}
+
+test('updateBranchIfBehind updates a BEHIND PR, pinning the expected head sha', async () => {
+  const { fetchImpl, calls } = mkUpdateFetch({ node: prNode({ mergeStateStatus: 'BEHIND', oid: 'headsha' }) });
+  const u = await gh.updateBranchIfBehind({ branch: 'claude/wt' }, DEPS(fetchImpl));
+  assert.equal(u.updated_now, true);
+  assert.equal(calls.update, 1);
+  assert.match(String(calls.updateArgs.url), /\/pulls\/125\/update-branch$/);
+  assert.equal(calls.updateArgs.body.expected_head_sha, 'headsha', 'a raced head 422s instead of updating blind');
+});
+
+test('updateBranchIfBehind refuses every non-BEHIND shape without calling the API', async () => {
+  for (const [node, reason] of [
+    [prNode({ mergeStateStatus: 'CLEAN' }), 'clean'],
+    [prNode({ merged: true }), 'already_merged'],
+    [prNode({ state: 'CLOSED' }), 'no_open_pr'],
+    [prNode({ mergeStateStatus: 'BLOCKED' }), 'blocked_required_review_or_pending_check'],
+  ]) {
+    const { fetchImpl, calls } = mkUpdateFetch({ node });
+    const u = await gh.updateBranchIfBehind({ branch: 'claude/wt' }, DEPS(fetchImpl));
+    assert.equal(u.updated_now, false);
+    assert.equal(calls.update, 0, 'no update PUT for a non-BEHIND PR');
+    if (reason) assert.equal(u.reason, reason);
+  }
+});
+
+test('updateBranchIfBehind surfaces an API refusal as update_api_<status>', async () => {
+  const { fetchImpl } = mkUpdateFetch({ node: prNode({ mergeStateStatus: 'BEHIND' }), updateStatus: 403 });
+  const u = await gh.updateBranchIfBehind({ branch: 'claude/wt' }, DEPS(fetchImpl));
+  assert.equal(u.updated_now, false);
+  assert.equal(u.reason, 'update_api_403');
+});
+
 setTimeout(() => {
   console.log(`\ngithub-push merge driver (task 1162) tests: ${passed} passed, ${failed} failed`);
   process.exit(failed > 0 ? 1 : 0);

package/tests/publish_reconciler.mjs

@@ -57,9 +57,10 @@ function mkDeps({
   broadcastImpl,
   conflictResolveImpl,
   refreshStaleImpl,
+  updateByBranch = {},
   healAttempts = new Map(),
 } = {}) {
-  const calls = { ship: [], broadcast: [], status: [], merge: [], ancestry: [], search: [], resolve: [], refresh: [], flag: [], events: [], logs: [], errors: [] };
+  const calls = { ship: [], broadcast: [], status: [], merge: [], ancestry: [], search: [], resolve: [], refresh: [], update: [], flag: [], events: [], logs: [], errors: [] };
   // isSafeBranch mirrors github-push's pattern enough for the test (rejects
   // option-like / traversal refs); we use the REAL module so the contract can't drift.
   const githubPush = require('../modules/lifecycle/github-push.js');
@@ -110,6 +111,15 @@ function mkDeps({
         if (f instanceof Error) throw f;
         return f || null;
       },
+      // task 1002666: the carrier-race branch updater. Default: no open PR (a
+      // no-op), so pre-1002666 tests keep their exact behavior. Script per
+      // branch via updateByBranch; an Error value throws (swallowed, non-blocking).
+      updateBranchIfBehind: async ({ branch }) => {
+        calls.update.push(branch);
+        const u = updateByBranch[branch];
+        if (u instanceof Error) throw u;
+        return u || { updated_now: false, reason: 'no_open_pr' };
+      },
       // task 1313 head_sha land-check. Default: not on main. An Error value throws
       // (to prove a transient compare-API miss is swallowed, leaving it for next sweep).
       isAncestorOfDefaultBranch: async ({ sha }) => {
@@ -790,6 +800,79 @@ test('1915 mergeable-but-red PR → regen-heal fires on the right branch; refres
   assert.equal(deps._calls.ship.length, 0, 'the heal never ships (no phantom-ship — land still needs the tip proof)');
 });
 
+// --- task 1002666: the carrier race — green PR behind main gets its branch updated ---
+
+// mergeIfGreen shape for a green, mergeable PR that fell behind main (the ADR 0161
+// carrier landed after this PR's checks reported).
+const behindGreen = (number = 48) => ({
+  pr_state: 'open', number, merged: false, merged_now: false, mergeable: 'MERGEABLE', reason: 'branch_behind_base',
+});
+
+test('1002666 green-but-behind PR (carrier race) → server updates the branch; NOT shipped this sweep', async () => {
+  const deps = mkDeps({
+    rows: [{ task_id: 500, builder_id: 5, worktree_name: 'wt-behind' }],
+    statusByBranch: { 'claude/wt-behind': PENDING },
+    mergeByBranch: { 'claude/wt-behind': behindGreen() },
+    updateByBranch: { 'claude/wt-behind': { number: 48, updated_now: true, merge_state: 'BEHIND', reason: null } },
+  });
+  const r = await reconciler.runSweep(deps);
+  assert.equal(r.behindUpdated, 1, 'the behind PR was branch-updated');
+  assert.deepEqual(deps._calls.update, ['claude/wt-behind'], 'the update is invoked on exactly this task\'s branch');
+  assert.equal(r.reconciled, 0, 'no ship this sweep — checks re-run on the new head, lands next sweep');
+  assert.equal(deps._calls.ship.length, 0, 'the update never ships (land still needs the tip proof)');
+  assert.ok(deps._calls.logs.some((l) => /carrier race/.test(l)), 'the log names the carrier race');
+});
+
+test('1002666 update-branch attempts are capped on the shared heal map (a hot fleet must surface, not spin)', async () => {
+  const healAttempts = new Map([['behind:claude/wt-behind', 3]]);
+  const deps = mkDeps({
+    rows: [{ task_id: 501, builder_id: 5, worktree_name: 'wt-behind' }],
+    statusByBranch: { 'claude/wt-behind': PENDING },
+    mergeByBranch: { 'claude/wt-behind': behindGreen() },
+    updateByBranch: { 'claude/wt-behind': { number: 48, updated_now: true } },
+    healAttempts,
+  });
+  const r = await reconciler.runSweep(deps);
+  assert.equal(deps._calls.update.length, 0, 'at the cap the updater is not invoked');
+  assert.equal(r.behindUpdated, 0);
+  assert.ok(deps._calls.logs.some((l) => /capped/.test(l)), 'the cap is logged, not silent');
+});
+
+test('1002666 the behind-cap ACCUMULATES across sweeps for a live branch (the prune must not reset it)', async () => {
+  const healAttempts = new Map();
+  const mk = () => mkDeps({
+    rows: [{ task_id: 503, builder_id: 5, worktree_name: 'wt-behind' }],
+    statusByBranch: { 'claude/wt-behind': PENDING },
+    mergeByBranch: { 'claude/wt-behind': behindGreen() },
+    updateByBranch: { 'claude/wt-behind': { number: 48, updated_now: true } },
+    healAttempts,
+  });
+  for (let i = 1; i <= 3; i++) {
+    await reconciler.runSweep(mk());
+    assert.equal(healAttempts.get('behind:claude/wt-behind'), i, `attempt ${i} is remembered after the sweep's prune`);
+  }
+  const fourth = mk();
+  const r = await reconciler.runSweep(fourth);
+  assert.equal(fourth._calls.update.length, 0, 'the 4th sweep is capped — a permanently-behind PR surfaces instead of spinning');
+  assert.equal(r.behindUpdated, 0);
+  // A branch that LEAVES the confirmed set prunes its namespaced key too (no leak).
+  const empty = mkDeps({ rows: [], healAttempts });
+  await reconciler.runSweep(empty);
+  assert.equal(healAttempts.has('behind:claude/wt-behind'), false, 'departed branch prunes its behind: key');
+});
+
+test('1002666 an update-branch API failure is swallowed (non-blocking) and the sweep continues', async () => {
+  const deps = mkDeps({
+    rows: [{ task_id: 502, builder_id: 5, worktree_name: 'wt-behind' }],
+    statusByBranch: { 'claude/wt-behind': PENDING },
+    mergeByBranch: { 'claude/wt-behind': behindGreen() },
+    updateByBranch: { 'claude/wt-behind': new Error('update-branch 403') },
+  });
+  const r = await reconciler.runSweep(deps);
+  assert.equal(r.behindUpdated, 0);
+  assert.ok(deps._calls.errors.some((l) => /update-branch/.test(l)), 'the failure is logged to errFn');
+});
+
 test('1915 mergeable-but-red PR where regen yields NO diff → not healed, logged as a real check failure', async () => {
   const deps = mkDeps({
     rows: [{ task_id: 401, builder_id: 5, worktree_name: 'wt-realfail' }],

package/tests/skill_grader_health.mjs

@@ -0,0 +1,48 @@
+// tests/skill_grader_health.mjs — the /grader-health skill exists and covers
+// the four health axes from the grader-hardening evaluation §6 (task 1002656):
+// outage runs, pass-rate drift, cost anomalies, and stale model pins — reading
+// LIVE data surfaces, emitting exact --regrade remediation lines, and staying
+// read-only (describe, never confirm/flip — ADR 0162).
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SKILL = path.join(ROOT, '.claude', 'skills', 'grader-health', 'SKILL.md');
+
+// .claude/skills is INSTANCE-materialized; a neutral core checkout carries none
+// (task 1002470) — skip there, same guard shape as file_map.mjs.
+const skillsDirExists = existsSync(path.join(ROOT, '.claude', 'skills'));
+
+test('/grader-health exists and covers the four health axes on live data', (t) => {
+  if (!skillsDirExists) return t.skip('.claude/skills not materialized in this checkout');
+  assert.ok(existsSync(SKILL), '.claude/skills/grader-health/SKILL.md must exist (task 1002656)');
+  const md = readFileSync(SKILL, 'utf8');
+
+  // Live data surfaces, named concretely.
+  assert.match(md, /\/api\/gds\/public\/grades/, 'reads the public grade trend');
+  assert.match(md, /\/api\/gds\/grades\/by-builder/, 'reads the per-builder split (Archon)');
+  assert.match(md, /\/api\/gds\/public\/cost-summary/, 'reads grader spend');
+
+  // Axis 1 — outage runs: the 21×0.0 pattern and outage-vs-rejection confirmation.
+  assert.match(md, /n_unavailable/, 'names the outage bucket the aggregates expose');
+  assert.match(md, /panel_outcome='unavailable'/, 'confirms outage vs rejection per task');
+
+  // Axis 2 — pass-rate drift vs the evaluation baseline.
+  assert.match(md, /90\.6%/, 'names the eval-window pass-rate baseline');
+
+  // Axis 3 — cost anomalies vs the fixed-cost benchmark.
+  assert.match(md, /\$2\.14/, 'names the mean per-grade cost benchmark');
+
+  // Axis 4 — model pins.
+  assert.match(md, /DEFAULT_GRADER_MODEL|selectGraderModel/, 'checks the live model pin');
+
+  // Remediation + probe + the read-only contract.
+  assert.match(md, /node scripts\/gds\/ship\.js <(?:task-)?id> --regrade/, 'emits the exact remediation line');
+  assert.match(md, /--probe/, 'offers the optional live calibration probe');
+  assert.match(md, /grade-smoke\.js/, 'names the probe script');
+  assert.match(md, /read-only/i, 'states the read-only contract');
+  assert.match(md, /ADR 0162/, 'anchors the no-new-gates constraint');
+});