@bongos/core 1.19.1037 → 1.19.1039

package/modules/grading/model-provider.js

@@ -0,0 +1,257 @@
+// modules/grading/model-provider.js — the ModelProvider port (ADR 0089 §3,
+// task 1002840): how a judge's model is called, as an adapter behind one seam
+// instead of a hard-coded `claude` spawn.
+//
+// WHY. Every platform LLM call funnels through runSubagent (grader-subagent.js):
+// the panel workers, the no-artifact shots, architect-audit, and the agents
+// module through the grade port. Until this file that function WAS the Claude
+// CLI spawn, so a judge from another model family — the property ADR 0089's
+// ensemble exists for — had no way in. Now a call names a provider and the
+// provider makes it. Every provider answers in the SAME shape the Claude spawn
+// always has: a `claude -p --output-format json`-style envelope on stdout and the
+// same error codes (SUBAGENT_SPAWN_FAILED / SUBAGENT_TIMEOUT /
+// SUBAGENT_NONZERO_EXIT). So nothing downstream changes — runWorker's retry, the
+// outage detection, extractAssistantResult / extractCostUsd, the LLM cache.
+//
+// THE MODEL REFERENCE. A model is still ONE STRING everywhere it travels
+// (signals.workers[].model, grader_model, the cache key). A string with no
+// provider prefix is an anthropic-cli model — every id this project uses today —
+// so today's calls are byte-identical. `<provider>:<model>` routes to a
+// REGISTERED provider (`deepinfra:deepseek-ai/DeepSeek-V3.1`,
+// `ollama:qwen2.5-coder:32b`). Only a prefix that names a registered provider is
+// split off; anything else stays a Claude model id, so a colon inside an id can
+// never re-route a call by accident.
+//
+// PROVIDERS.
+//   anthropic-cli      the `claude -p` spawn (grader-subagent.js registers it).
+//                      The default, and the only provider shipped config uses.
+//   openai-compatible  one adapter for DeepInfra / OpenRouter / Together /
+//                      Fireworks / Groq / vLLM / Ollama — POST
+//                      <base_url>/chat/completions with a BYOK key read from the
+//                      env var the instance names. PROMPT-ONLY: it has no Read
+//                      tool, so such a judge sees exactly what its prompt carries.
+//
+// INSTANCE CONFIG (the ADR 0062 host-owned pattern). Providers are declared in
+// config/grader-providers.json at the instance root; the core ships
+// grader-providers.neutral.json beside this file with NO providers, so a vanilla
+// instance is Claude-only. A key never lives in a config file — only the NAME
+// of the env var holding it. Declaring a provider is an owner decision: it sends
+// the diff under review to that vendor and it costs money per call (ADR 0089 §3).
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const api = require('../../src/module-api');
+
+const DEFAULT_PROVIDER = 'anthropic-cli';
+const PROVIDER_NAME_RE = /^[a-z][a-z0-9-]{1,39}$/;
+const API_KEY_ENV_RE = /^[A-Z][A-Z0-9_]{1,63}$/;
+const KINDS = new Set(['openai-compatible']);
+const DEFAULT_TIMEOUT_MS = 240_000;
+const ERROR_BODY_MAX = 2000;
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+
+const providers = new Map(); // name -> { name, kind, run }
+
+// One place a refusal is reported, so a malformed instance config is loud
+// without scattering console calls (the fitness console ratchet counts them).
+function refuse(msg) {
+  console.error(`grade model-provider: ${msg}`);
+}
+
+function registerModelProvider(provider) {
+  if (!provider || typeof provider.run !== 'function' || typeof provider.name !== 'string' || !provider.name) {
+    throw new TypeError('registerModelProvider: a provider needs a name and a run({ prompt, opts }) function');
+  }
+  const held = providers.get(provider.name);
+  if (held && held !== provider) throw new Error(`model provider '${provider.name}' is already registered`);
+  providers.set(provider.name, provider);
+  return provider;
+}
+
+function resolveModelProvider(name = DEFAULT_PROVIDER) {
+  const p = providers.get(name);
+  if (!p) throw new Error(`model provider '${name}' is not registered`);
+  return p;
+}
+
+function listModelProviders() {
+  return [...providers.keys()].sort();
+}
+
+// `<provider>:<model>` → { provider, model }, split ONLY when the prefix names a
+// registered provider other than the default; everything else is one Claude id.
+function parseModelRef(ref) {
+  const s = String(ref == null ? '' : ref);
+  const i = s.indexOf(':');
+  if (i > 0) {
+    const name = s.slice(0, i);
+    if (name !== DEFAULT_PROVIDER && providers.has(name)) return { provider: name, model: s.slice(i + 1) };
+  }
+  return { provider: DEFAULT_PROVIDER, model: s };
+}
+
+function codeError(code, message, extra = {}) {
+  return Object.assign(new Error(message), { code, ...extra });
+}
+
+// base_url must be https, or plain http to THIS machine only (a local vLLM /
+// Ollama): a key must never cross a network in cleartext.
+function checkBaseUrl(raw) {
+  let u;
+  try { u = new URL(String(raw)); } catch { return null; }
+  const loopback = LOOPBACK_HOSTS.has(u.hostname);
+  if (u.protocol !== 'https:' && !(u.protocol === 'http:' && loopback)) return null;
+  if (u.username || u.password || u.search || u.hash) return null;
+  return { url: u.toString().replace(/\/+$/, ''), loopback };
+}
+
+// Validate one declared provider: { def } normalised, or { error } saying why
+// not — never throws, so one bad entry cannot take the grader down.
+function validateProviderDef(name, def) {
+  if (!PROVIDER_NAME_RE.test(name) || name === DEFAULT_PROVIDER) return { error: `provider name '${name}' must match ${PROVIDER_NAME_RE} and not be '${DEFAULT_PROVIDER}'` };
+  if (!def || typeof def !== 'object') return { error: `provider '${name}' must be an object` };
+  if (!KINDS.has(def.kind)) return { error: `provider '${name}': kind must be one of ${[...KINDS].join(', ')}` };
+  const base = checkBaseUrl(def.base_url);
+  if (!base) return { error: `provider '${name}': base_url must be https:// (http:// only to localhost), with no credentials or query` };
+  const keyEnv = def.api_key_env == null ? null : String(def.api_key_env);
+  if (keyEnv != null && !API_KEY_ENV_RE.test(keyEnv)) return { error: `provider '${name}': api_key_env must be an env var NAME (${API_KEY_ENV_RE}) — never the key itself` };
+  if (keyEnv == null && !base.loopback) return { error: `provider '${name}': a remote provider needs api_key_env` };
+  const prices = {};
+  for (const [model, p] of Object.entries(def.price_per_mtok || {})) {
+    const input = Number(p && p.input);
+    const output = Number(p && p.output);
+    if (!(Number.isFinite(input) && input >= 0 && Number.isFinite(output) && output >= 0)) {
+      return { error: `provider '${name}': price_per_mtok['${model}'] needs non-negative input and output` };
+    }
+    prices[model] = { input, output };
+  }
+  return { def: { name, kind: def.kind, baseUrl: base.url, apiKeyEnv: keyEnv, prices } };
+}
+
+// USD for one call from the reply's token usage, or null when the model has no
+// declared price — a cost signal never fabricates a number it does not have.
+function priceCall(prices, model, usage) {
+  const p = prices[model];
+  if (!p || !usage) return null;
+  const inTok = Number(usage.prompt_tokens);
+  const outTok = Number(usage.completion_tokens);
+  if (!Number.isFinite(inTok) || !Number.isFinite(outTok)) return null;
+  return (inTok * p.input + outTok * p.output) / 1_000_000;
+}
+
+// The openai-compatible adapter. `fetchImpl` and `env` are injectable so the
+// whole adapter is testable against a stub with no key and no network.
+function createOpenAICompatibleProvider(def, { fetchImpl = globalThis.fetch, env = process.env } = {}) {
+  const run = async ({ prompt, opts = {} }) => {
+    const started = Date.now();
+    const model = String(opts.model || '');
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const key = def.apiKeyEnv ? env[def.apiKeyEnv] : null;
+    // Refused BEFORE any request: no key means nothing is sent anywhere.
+    if (def.apiKeyEnv && !key) {
+      throw codeError('SUBAGENT_SPAWN_FAILED', `provider ${def.name}: no API key — set ${def.apiKeyEnv} (bring-your-own key)`, { run_ms: 0, stdout: '', stderr: '' });
+    }
+    const scrub = (t) => (key ? String(t).split(key).join('[redacted]') : String(t));
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    let text;
+    try {
+      res = await fetchImpl(`${def.baseUrl}/chat/completions`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...(key ? { authorization: `Bearer ${key}` } : {}) },
+        body: JSON.stringify({ model, messages: [{ role: 'user', content: String(prompt) }] }),
+        signal: controller.signal,
+      });
+      text = await res.text();
+    } catch (err) {
+      const run_ms = Date.now() - started;
+      if (controller.signal.aborted) {
+        throw codeError('SUBAGENT_TIMEOUT', `provider ${def.name}: timed out after ${timeoutMs}ms`, { run_ms, stdout: '', stderr: '' });
+      }
+      throw codeError('SUBAGENT_SPAWN_FAILED', `provider ${def.name}: request failed: ${scrub(err && err.message)}`, { run_ms, stdout: '', stderr: scrub(err && err.message) });
+    } finally {
+      clearTimeout(timer);
+    }
+    const run_ms = Date.now() - started;
+    if (!res.ok) {
+      throw codeError('SUBAGENT_NONZERO_EXIT', `provider ${def.name}: HTTP ${res.status}`, {
+        exit_code: res.status, run_ms, stdout: '', stderr: scrub(text).slice(0, ERROR_BODY_MAX),
+      });
+    }
+    let body = null;
+    try { body = JSON.parse(text); } catch { /* an unparseable 200 → empty result → the worker's parse_error path */ }
+    const content = body && body.choices && body.choices[0] && body.choices[0].message
+      ? body.choices[0].message.content : null;
+    const usage = body && body.usage ? body.usage : null;
+    const cost = priceCall(def.prices, model, usage);
+    const envelope = {
+      type: 'result',
+      result: typeof content === 'string' ? content : '',
+      ...(cost != null ? { total_cost_usd: cost } : {}),
+      provider: def.name,
+      model,
+      usage,
+    };
+    return { stdout: JSON.stringify(envelope), stderr: '', run_ms, exit_code: 0, cost_usd: cost };
+  };
+  return { name: def.name, kind: def.kind, run };
+}
+
+// ---------- instance config ----------
+//
+// The host's config/grader-providers.json, else the neutral starter beside this
+// file (which declares none). A missing instance file is the ordinary case; one
+// that does not parse falls back to the neutral starter — fail to vanilla, never
+// to dead — and each invalid entry is refused by name while the rest load.
+const NEUTRAL_PATH = path.join(__dirname, 'grader-providers.neutral.json');
+const INSTANCE_PATH = path.join(api.resolveInstanceRoot(), 'config', 'grader-providers.json');
+
+function readPack(file) {
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch { return null; }
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch { return null; }
+}
+
+function loadProviderConfig({ instancePath = INSTANCE_PATH, neutralPath = NEUTRAL_PATH } = {}) {
+  const instance = readPack(instancePath);
+  const pack = instance || readPack(neutralPath) || {};
+  const defs = [];
+  const refused = [];
+  const declared = pack.providers && typeof pack.providers === 'object' && !Array.isArray(pack.providers) ? pack.providers : {};
+  for (const [name, def] of Object.entries(declared)) {
+    const v = validateProviderDef(name, def);
+    if (v.error) refused.push(v.error); else defs.push(v.def);
+  }
+  return { source: instance ? instancePath : neutralPath, defs, refused };
+}
+
+// Register every provider the instance declares. Idempotent: an already
+// registered name is left alone. Returns the provider names now resolvable.
+function registerConfiguredProviders(opts = {}) {
+  const { defs, refused } = loadProviderConfig(opts);
+  for (const reason of refused) refuse(`${reason} — refused, grading continues without it`);
+  for (const def of defs) {
+    if (!providers.has(def.name)) registerModelProvider(createOpenAICompatibleProvider(def, opts));
+  }
+  return listModelProviders();
+}
+
+registerConfiguredProviders();
+
+module.exports = {
+  DEFAULT_PROVIDER,
+  createOpenAICompatibleProvider,
+  listModelProviders,
+  loadProviderConfig,
+  parseModelRef,
+  registerConfiguredProviders,
+  registerModelProvider,
+  resolveModelProvider,
+  validateProviderDef,
+};

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1037",
+  "version": "1.19.1039",
   "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/release-notes.json

@@ -7507,5 +7507,21 @@
       "id": "1004280",
       "text": "The project's own notes no longer claim a past decision banned all new checks; each one now gives its real reason, and a test stops the wrong claim coming back."
     }
+  ],
+  "1.19.1038": [
+    {
+      "id": "1004289",
+      "text": "When the code host refuses to run the automatic tests at all, for example because the account's allowance ran out, the shipping tool now says so plainly and names the owner's fix, instead of telling the builder to fix code tha"
+    },
+    {
+      "id": "1002840",
+      "text": "The grader can now call AI models from other companies through one plug-in point, ready for a second-opinion reviewer; nothing changes today — it still uses only Claude and spends nothing new."
+    }
+  ],
+  "1.19.1039": [
+    {
+      "id": "1004290",
+      "text": "A new release of the core is now published only after the check that it can set up a brand-new empty database has passed, so a release that cannot install cleanly can no longer reach projects."
+    }
   ]
 }

package/scripts/gds/plain-cards.js

@@ -169,6 +169,11 @@ const CARDS = Object.freeze({
     'An automatic test failed on your work, so it has not been added to the project.',
     'I will run that test here, fix what it found, and send the work again. Sending the same work again would fail the same way.',
     null, FAULT),
+  // task 1004289: the tests never ran at all (the account cannot run them right now).
+  ci_not_started: card(
+    'The automatic tests never ran on your work: the code host did not start them, because the account has run out of test time or has a payment problem. Nothing was tested, so nothing needs fixing.',
+    'I will not change the work. Once the owner restores the test time, I will start the tests again on the same work and it will be added on its own.',
+    'The project owner, to restore the account\'s test time on the code host.', FAULT),
   non_required_check_failing: card(
     'An optional automatic test failed on your work.',
     'I will look at what it found. It does not stop the work being added, but it is usually worth fixing.',

package/scripts/gds/publish-integration-gate.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// scripts/gds/publish-integration-gate.js — the publish lane waits for the integration
+// lane's verdict on the exact commit it is about to release (task 1004290).
+//
+// WHY. publish.yml fires on the `unit` workflow's success, and `unit` is DB-free by
+// design. The proof that the packaged core can set up an EMPTY database and serve a
+// DB-backed route — tests/consumer_layout_boot.mjs, task 1002863 — runs in the
+// `integration` workflow, on the same main push. Without this gate that result arrived
+// after the publish and gated nothing: a core that installs and boots but cannot migrate
+// its own database still reached npm, and from there the nightly tenant upgrade sweep.
+//
+// WHAT IT COSTS, MEASURED 2026-09-26 (not assumed). Both lanes start on the same push, and
+// integration is the SHORTER one: on the two commits right after task 1002863 landed,
+// integration took 247s and 245s against unit's 351s and 335s. So when unit's success fires
+// the publish, integration has usually already answered and this gate is a single API
+// read. It runs inside the existing publish job — no new job — and it polls only in the
+// rare case integration is still going. Over 299 main pushes (2026-09-20 → 26) integration
+// was green 254 times, cancelled 41 times (a newer merge superseded it) and red 3 times,
+// all three the Actions-budget outage of 2026-09-25 — so it is not a flaky lane that would
+// stall every release.
+//
+// THE VERDICTS (decideIntegrationGate, pure):
+//   go          the newest push-event run on this commit succeeded → publish
+//   wait        no run yet, or it is still going → poll
+//   superseded  it was cancelled — almost always a newer merge's run replacing it under
+//               integration.yml's cancel-in-progress group. Nothing is published; that
+//               newer merge fires its own publish, which asks about its own commit.
+//   red         anything else (failure, timed_out, startup_failure …) → refuse, loudly
+// Only PUSH-event runs count: the weekly scheduled run on main carries HEAD's sha but runs
+// only the parked-set ratchet, so its conclusion says nothing about this commit.
+//
+// OUTPUT: `go=true|false` to $GITHUB_OUTPUT. Exit 0 for go and superseded, 1 for red,
+// timeout or an unreadable API (a refusal that must be seen), 2 for bad arguments.
+//
+//   node scripts/gds/publish-integration-gate.js --sha <40-hex> --repo <owner/name>
+//        [--timeout-min 12] [--interval-s 20]      token: GH_TOKEN or GITHUB_TOKEN
+
+'use strict';
+
+const fs = require('node:fs');
+
+const WORKFLOW_FILE = 'integration.yml';
+const DEFAULT_TIMEOUT_MIN = 12; // inside publish.yml's 20-minute job, leaving room to pack + publish
+const DEFAULT_INTERVAL_S = 20;
+const SHA_RE = /^[0-9a-f]{40}$/;
+const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+
+// decideIntegrationGate — PURE. `runs` is list-workflow-runs' `workflow_runs` for one
+// head sha and the push event. The newest run decides (a re-push of the same sha, or a
+// re-run, supersedes an older verdict).
+function decideIntegrationGate(runs) {
+  const list = Array.isArray(runs) ? runs.filter((r) => r && typeof r === 'object') : [];
+  if (!list.length) return { verdict: 'wait', run: null };
+  const newest = list.slice().sort((a, b) =>
+    (Number(b.run_number) || 0) - (Number(a.run_number) || 0)
+    || String(b.created_at || '').localeCompare(String(a.created_at || '')))[0];
+  if (newest.status !== 'completed') return { verdict: 'wait', run: newest };
+  if (newest.conclusion === 'success') return { verdict: 'go', run: newest };
+  if (newest.conclusion === 'cancelled') return { verdict: 'superseded', run: newest };
+  return { verdict: 'red', run: newest };
+}
+
+function runsUrl(repo, sha) {
+  return `https://api.github.com/repos/${repo}/actions/workflows/${WORKFLOW_FILE}/runs?head_sha=${sha}&event=push&per_page=20`;
+}
+
+// waitForIntegration — poll until the gate has a verdict or the time is up. A 401/403/404
+// is not something waiting fixes (a missing `actions: read`, a renamed workflow), so it
+// ends the wait at once as 'unreadable'. Any other failed read is retried. Everything that
+// touches the world is injectable for tests/publish_integration_gate.mjs.
+async function waitForIntegration({
+  sha, repo, token, timeoutMs, intervalMs,
+  fetchImpl = globalThis.fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now,
+}) {
+  const deadline = now() + timeoutMs;
+  let last = { verdict: 'wait', run: null, why: 'no read yet' };
+  for (;;) {
+    try {
+      const res = await fetchImpl(runsUrl(repo, sha), {
+        headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28' },
+      });
+      if ([401, 403, 404].includes(res.status)) return { verdict: 'unreadable', run: null, why: `HTTP ${res.status}` };
+      if (res.ok) {
+        const body = await res.json();
+        last = { ...decideIntegrationGate(body && body.workflow_runs), why: null };
+        if (last.verdict !== 'wait') return last;
+      } else {
+        last = { ...last, why: `HTTP ${res.status}` };
+      }
+    } catch (e) {
+      last = { ...last, why: (e && e.message) || String(e) };
+    }
+    if (now() + intervalMs > deadline) return { verdict: 'timeout', run: last.run, why: last.why };
+    await sleep(intervalMs);
+  }
+}
+
+// The one line per outcome the Actions log shows, and what the rest of the lane reads.
+function reportLines(verdict, { sha, run, why, timeoutMin }) {
+  const short = String(sha).slice(0, 8);
+  const url = run && run.html_url ? ` ${run.html_url}` : '';
+  switch (verdict) {
+    case 'go':
+      return { go: true, code: 0, line: `integration is green on ${short}${url} — publishing.` };
+    case 'superseded':
+      return { go: false, code: 0, line: `::notice title=not published — integration was cancelled on ${short}::Usually a newer merge's run replaced it; that merge fires its own publish, which checks its own commit.${url}` };
+    case 'red':
+      return { go: false, code: 1, line: `::error title=not published — integration is red on ${short}::The integration lane (${run && run.conclusion}) runs the proof that the packaged core can migrate an empty database (task 1002863). A core that fails it must not reach npm. Fix main; the next merge publishes everything.${url}` };
+    case 'unreadable':
+      return { go: false, code: 1, line: `::error title=not published — cannot read the integration lane::${why}. publish.yml needs 'permissions: actions: read', and the workflow file must still be ${WORKFLOW_FILE}.` };
+    default:
+      return { go: false, code: 1, line: `::error title=not published — integration had no verdict on ${short} after ${timeoutMin} min::${why ? `Last read: ${why}. ` : ''}Re-run this workflow once integration finishes, or let the next merge publish.${url}` };
+  }
+}
+
+function argValue(argv, flag) {
+  const i = argv.indexOf(flag);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null;
+}
+
+async function main(argv = process.argv.slice(2), env = process.env) {
+  const sha = String(argValue(argv, '--sha') || '').toLowerCase();
+  const repo = String(argValue(argv, '--repo') || env.GITHUB_REPOSITORY || '');
+  const token = env.GH_TOKEN || env.GITHUB_TOKEN || '';
+  const timeoutMin = Number(argValue(argv, '--timeout-min') || DEFAULT_TIMEOUT_MIN);
+  const intervalS = Number(argValue(argv, '--interval-s') || DEFAULT_INTERVAL_S);
+  if (!SHA_RE.test(sha) || !REPO_RE.test(repo) || !token || !(timeoutMin > 0) || !(intervalS > 0)) {
+    console.error('usage: publish-integration-gate.js --sha <40-hex> --repo <owner/name> [--timeout-min N] [--interval-s N]  (token: GH_TOKEN or GITHUB_TOKEN)');
+    return 2;
+  }
+  const result = await waitForIntegration({ sha, repo, token, timeoutMs: timeoutMin * 60000, intervalMs: intervalS * 1000 });
+  const out = reportLines(result.verdict, { sha, run: result.run, why: result.why, timeoutMin });
+  console.log(out.line);
+  if (env.GITHUB_OUTPUT) fs.appendFileSync(env.GITHUB_OUTPUT, `go=${out.go}\n`);
+  return out.code;
+}
+
+if (require.main === module) {
+  main().then((code) => { process.exitCode = code; }, (e) => { console.error(e); process.exitCode = 1; });
+}
+
+module.exports = { decideIntegrationGate, waitForIntegration, reportLines, main, WORKFLOW_FILE, runsUrl };

package/scripts/gds/ship-land.js

@@ -291,7 +291,17 @@ function strandNextStep(taskId, via) {
 // task 1003764: `red` — the PR was RED on the poll's last read. "NOT a failure" is then
 // false: a required check that failed does not pass by waiting, so the banner says the
 // land is stuck on it and defers to the red lines above for the remedy.
-function landPendingLines(taskId, { merged, red } = {}) {
+function landPendingLines(taskId, { merged, red, notStarted } = {}) {
+  // task 1004289: CI never RAN (the account cannot run Actions). Not a failure of the
+  // work, and not something waiting fixes either: the checks have to be started again.
+  if (notStarted) {
+    return [
+      '  ci-land: Published, but CI never started on the PR (GitHub ran none of its checks), so it has NOT merged',
+      '  and cannot until they run. The task stays at \'confirmed\'. Nothing in the work needs to change: once the',
+      `  owner restores GitHub Actions, re-run the failed jobs (lines above), then re-run \`node scripts/gds/ship.js ${taskId}\``,
+      '  to watch the land — it resumes from here (task 941).',
+    ];
+  }
   if (red) {
     return [
       '  ci-land: Published, but the PR is RED (the check named above), so it has NOT merged and will not',
@@ -314,8 +324,9 @@ function printLandPending(taskId, opts = {}) {
   console.log('');
   for (const line of landPendingLines(taskId, opts)) console.log(line);
   // The land_pending card says there is nothing to do, which a red PR makes untrue; the
-  // red line already printed the failing_check card (task 1003764).
-  if (!opts.red) for (const line of plainCardLines('land_pending')) console.log(line);
+  // red line already printed the failing_check card (task 1003764), or the
+  // ci_not_started one (task 1004289).
+  if (!opts.red && !opts.notStarted) for (const line of plainCardLines('land_pending')) console.log(line);
 }
 
 // task 1002645 — the honest close-out when the PR MERGED but the server refused the
@@ -351,6 +362,11 @@ function prAssigneeLine(login) {
 // exported so the wording is pinned by tests/unit_report_status.mjs.
 function redPrLine(md) {
   const reason = (md && md.reason) || '';
+  if (md && md.not_started) {
+    const job = (/^ci_not_started:(.+)$/.exec(reason) || [])[1];
+    return `  ci-land: CI NEVER RAN on this PR — GitHub did not start ${job ? `the \`${job}\` job` : 'its checks'} ("The job was not started because …", `
+      + 'an Actions budget or billing stop on the account). Nothing in the work was tested, so there is nothing in it to fix.';
+  }
   const fix = 'fix it, commit, and re-run the ship — re-pushing unchanged work cannot turn it green.';
   if (md && md.failing_tests) {
     return `  ci-land: the PR is RED — ${md.failing_tests}. Reproduce with \`node tests/<name>.mjs\`, ${fix}`;
@@ -369,9 +385,21 @@ function redPrLine(md) {
 // task 1003764: the merge trap sits between them. `opts` = { taskId, via } for its wording.
 function redPrLines(md, opts = {}) {
   const red = redPrLine(md);
+  if (red && md.not_started) return [red, ...notStartedLines(md), ...plainCardLines('ci_not_started')];
   return red ? [red, ...mergeTrapLines(md, opts), ...plainCardLines((md && md.reason) || 'failing_check')] : [];
 }
 
+// notStartedLines — task 1004289. What to do when CI never ran, instead of the merge trap
+// (there is no failure to reproduce). Re-running is the remedy, not re-pushing: the same
+// commit is fine, it simply was never tested. Pure + exported.
+function notStartedLines(md) {
+  const rerun = md && /^\d+$/.test(String(md.run_id || '')) ? `\`gh run rerun ${md.run_id} --failed\`` : '"Re-run failed jobs" on the PR';
+  return [
+    '  ci-land: this is the repo OWNER\'s to fix, on GitHub: the account\'s Actions budget / spending limit or payment method.',
+    `  ci-land: once Actions can run again, ${rerun} starts the checks on the SAME commit — do not re-push or edit the work.`,
+  ];
+}
+
 // The unit tests that gate GENERATED files — each compares a committed artifact with a
 // fresh build of it. `fitness` holds the combined gate (fitness.js "generated artifacts
 // fresh": copy registry, API docs, file map, nested CLAUDE.md blocks, the §13 snippet).
@@ -439,16 +467,42 @@ const RED_CONCLUSIONS = new Set(['FAILURE', 'ERROR', 'TIMED_OUT', 'CANCELLED', '
 // poll paths hand redPrLines the same thing. `failingTestsFor(sha)` reads the unit-report
 // status (gh pr view omits a status's description) and is asked only once that status is
 // itself red, i.e. posted. Null when nothing is red. Pure + exported.
-function localMergeDriver(pr, failingTestsFor = () => null) {
+// task 1004289 — `neverStarted(rawCheck)` answers "did this red job never run at all?"
+// (jobNeverStarted below). When EVERY red check is one, nothing was tested, and the
+// answer is { reason: 'ci_not_started:<name>', not_started: true, run_id } rather than
+// a failing check the builder is told to fix.
+function localMergeDriver(pr, failingTestsFor = () => null, neverStarted = () => false) {
   if (!pr || pr.state !== 'OPEN' || !Array.isArray(pr.statusCheckRollup)) return null;
   const { checks } = readCheckRollup({ contexts: { nodes: pr.statusCheckRollup } });
   const red = checks.filter((c) => RED_CONCLUSIONS.has(String(c.conclusion || '').toUpperCase()));
   if (!red.length) return null;
+  const redRaw = pr.statusCheckRollup.filter((c) => c && RED_CONCLUSIONS.has(String(c.conclusion || c.state || '').toUpperCase()));
+  if (redRaw.length && redRaw.every((c) => neverStarted(c))) {
+    const run = /\/runs\/(\d+)\//.exec(String(redRaw[0].detailsUrl || ''));
+    return { reason: `ci_not_started:${red[0].name}`, not_started: true, failing_tests: null, run_id: run ? run[1] : null };
+  }
   const kind = pr.mergeStateStatus === 'UNSTABLE' ? 'non_required_check_failing' : 'failing_check';
   const reported = red.some((c) => c.name === UNIT_REPORT_CONTEXT);
   return { reason: `${kind}:${red[0].name}`, failing_tests: (reported && failingTestsFor(pr.headRefOid)) || null };
 }
 
+// jobNeverStarted — task 1004289. When the account cannot run Actions (its budget is
+// spent, or a payment failed), GitHub still marks every job FAILED seconds after it was
+// queued, with no steps and no runner, and one annotation saying why: "The job was not
+// started because an Actions budget is preventing further use." (PR 1211, 2026-09-25).
+// Read as an ordinary red check, that told the builder to fix their code — advice that
+// cannot help, where each retry is another failed run. An Actions job's id (the tail of
+// its detailsUrl) is its check-run id, so its annotations are one read away. FAIL-OPEN:
+// anything unreadable is "no", which keeps the ordinary red wording. `gh` is injectable.
+const NOT_STARTED_RE = /^\s*The job was not started because\b/i;
+function jobNeverStarted(check, gh = ghJson) {
+  if (!check || (check.__typename && check.__typename !== 'CheckRun')) return false;
+  const m = /\/job\/(\d+)(?:[/?#]|$)/.exec(String(check.detailsUrl || ''));
+  if (!m) return false;
+  const notes = gh(['api', `repos/{owner}/{repo}/check-runs/${m[1]}/annotations`]);
+  return Array.isArray(notes) && notes.some((a) => a && NOT_STARTED_RE.test(String(a.message || '')));
+}
+
 // unitReportFor — the failing-test line the `unit` workflow posted on `sha`, read with this
 // machine's gh through the same parser the server uses. Null when unreadable; the red line
 // then names the check instead, as it did before the report existed. `gh` is injectable.
@@ -921,6 +975,14 @@ function pollCiDeploy(taskId, branch, headSha, deps = {}) {
     if (sha !== report.sha) report = { sha, text: unitReportFor(sha, readJson) };
     return report.text;
   };
+  // task 1004289: a finished job's annotations never change, so each is read once.
+  let notStarted = false;
+  const startMemo = new Map();
+  const neverStarted = (c) => {
+    const key = String((c && c.detailsUrl) || '');
+    if (!startMemo.has(key)) startMemo.set(key, jobNeverStarted(c, readJson));
+    return startMemo.get(key);
+  };
   for (let i = 0; i < MERGE_TRIES; i++) {
     // task 1003499: mergeable + mergeStateStatus ride the same read, so a conflict is
     // named on the poll it appears; the two-field read is the fallback for a gh that
@@ -937,13 +999,14 @@ function pollCiDeploy(taskId, branch, headSha, deps = {}) {
       return landBailed('the PR was closed without merging (a check failed, or it was closed manually)', `node scripts/gds/ship.js ${taskId}`);
     }
     if (pr) {
-      const md = localMergeDriver(pr, failingTestsFor);
+      const md = localMergeDriver(pr, failingTestsFor, neverStarted);
       const red = redPrLine(md);
       if (red && red !== redLine) {
         redLine = red;
         for (const line of redPrLines(md, { taskId, via: 'local' })) console.log(line);
       }
       stuckRed = !!red && redBlocksMerge(md);
+      notStarted = !!(md && md.not_started);
     }
     conflicting = noteConflict(taskId, pr, conflicting);
     pause();
@@ -954,7 +1017,7 @@ function pollCiDeploy(taskId, branch, headSha, deps = {}) {
     // CONFLICTING (task 1003499): then nothing is still in CI, and it never merges.
     // Or RED (task 1003764): then the banner says the land is stuck on that check.
     if (conflicting) return landConflicted(taskId);
-    printLandPending(taskId, { red: stuckRed });
+    printLandPending(taskId, { red: stuckRed, notStarted });
     return landPending();
   }
   console.log(`  ci-land: merged to main (${mergeSha.slice(0, 8)}). Waiting for the prod deploy...`);
@@ -1036,6 +1099,9 @@ module.exports = {
   redBlocksMerge,
   localMergeDriver,
   unitReportFor,
+  // task 1004289: CI that never ran is said as such, not as a failure to fix.
+  jobNeverStarted,
+  notStartedLines,
   reconciledCardStatus,
   strandCommand,
   strandNextStep,

package/src/module-api.js

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

package/tests/government_protected_surfaces.mjs

@@ -305,6 +305,20 @@ const ADDED_SINCE_R101 = [
        + 'deterministic veto, so an edit here can switch off the protected-path gate '
        + 'for every grade at once.',
   },
+  // task 1002840 (ADR 0089 §3): the ModelProvider port and its neutral config.
+  {
+    after: 'modules/grading/grade-engine.js',
+    glob: 'modules/grading/model-provider.js',
+    why: 'the ModelProvider port every grader model call goes through. It decides which '
+       + 'vendor receives the diff under review and with which key, so an edit here can '
+       + 're-route or blind the whole panel.',
+  },
+  {
+    after: 'modules/grading/model-provider.js',
+    glob: 'modules/grading/grader-providers.neutral.json',
+    why: 'the core neutral provider set, which declares none. An entry added here would '
+       + 'send every instance\'s diffs to a vendor by default.',
+  },
 ];
 
 // Surfaces RENAMED since R101 — still protected, under a new path. Distinct from