jules-orchestrator-kit 0.52.8 → 0.53.0

package/scripts/jules-create.mjs

@@ -4,25 +4,14 @@
  * Quick task file creator for .agent/jules-queue/.
  */
 
-import { writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { getQueueDir } from "../src/state.mjs";
+import { runTaskCreateWizard } from "../src/wizard-task.mjs";
 
-const taskTitle = process.argv[2] || "New Task";
-const queueDir = getQueueDir();
-const safeTitle = taskTitle.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
-const filepath = join(queueDir, `TASK-${Date.now()}-${safeTitle}.md`);
-
-const boilerplate = `# ${taskTitle}
-
-## Objective
-[Describe task goal]
-`;
+const prompt = process.argv.slice(2).join(" ").trim();
 
 try {
-  writeFileSync(filepath, boilerplate, "utf-8");
-  console.log(`[Shim] Scaffolded new task: ${filepath}`);
+  const result = await runTaskCreateWizard(process.cwd(), prompt ? { prompt } : {});
+  console.log(`✅ Scaffolded task envelope: ${result.taskFile}`);
 } catch (err) {
-  console.error(`[Shim] Failed to create task: ${err.message}`);
+  console.error(`❌ Failed to create task: ${err.message}`);
   process.exit(1);
 }

package/scripts/jules-patch.mjs

@@ -4,20 +4,28 @@
  * Session patch fetching utility.
  */
 
-export async function fetchSessionPatch(sessionId, _options = {}) {
+import { extractSessionPatch } from "../src/session-ops.mjs";
+
+export async function fetchSessionPatch(sessionId, options = {}) {
   if (!sessionId || typeof sessionId !== "string") {
     throw new Error("Session ID is required.");
   }
-  return {
-    sessionId,
-    state: "COMPLETED",
-    title: "Patch Session",
-    hasPatch: false,
-    diff: "",
-  };
+  return await extractSessionPatch(sessionId, options);
 }
 
 if (process.argv[1] && process.argv[1].endsWith("jules-patch.mjs")) {
-  console.log("Patch fetch completed.");
-  process.exit(0);
+  const sessionId = process.argv[2];
+  if (!sessionId) {
+    console.error("Usage: node scripts/jules-patch.mjs <sessionId>");
+    process.exit(1);
+  }
+  fetchSessionPatch(sessionId)
+    .then((res) => {
+      console.log(`Patch fetch completed for ${sessionId}: ${res.patch ? "Patch found" : "No patch"}`);
+      process.exit(0);
+    })
+    .catch((err) => {
+      console.error(`Patch fetch failed: ${err.message}`);
+      process.exit(1);
+    });
 }

package/scripts/stale-base-check.mjs

@@ -8,7 +8,7 @@ const baseBranch = process.env.BASE_BRANCH || "main";
 
 try {
   const resolvedBase = resolveBase(root, baseBranch);
-  const behindStr = git(["rev-list", "--count", `${resolvedBase}..HEAD`], { cwd: root, ignoreError: true });
+  const behindStr = git(["rev-list", "--count", `HEAD..${resolvedBase}`], { cwd: root, ignoreError: true });
   const behindCount = parseInt(behindStr || "0", 10);
 
   console.log(`[stale-base-check] Branch HEAD is ${behindCount} commits behind ${resolvedBase} (max allowed: ${maxBehind}).`);

package/src/ci-templates.mjs

@@ -0,0 +1,199 @@
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+/**
+ * Generate a CI job that runs the kit's gate, with the toolchain the detected
+ * stack actually needs.
+ *
+ * `init` used to copy this repository's *own* audit workflow into whatever
+ * repository it was scaffolding: a nine-way Node matrix that ran `npm install`,
+ * `npm test` and a script path that only exists here. Dropped into a Rust or
+ * Python repository it was red on the first push, for reasons that had nothing
+ * to do with that repository's code. A generated workflow is the only kind that
+ * can be correct in a repository the kit has never seen.
+ */
+
+export const CI_TARGETS = ["github", "gitlab"];
+
+/**
+ * Toolchain setup per stack, expressed once and rendered per CI target.
+ *
+ * Node is installed unconditionally and is not in this table: `agentctl` is a
+ * Node CLI, so the runner needs it regardless of what the project is written
+ * in. These are the *additional* runtimes.
+ *
+ * Actions are referenced by major version tag rather than by commit SHA. A
+ * generated file is a starting point the repository owns from the moment it is
+ * written, and pinning a SHA the owner did not choose ages into a silent
+ * security debt they never agreed to — the header tells them to pin.
+ */
+const STACK_TOOLCHAINS = {
+  python: { label: "Python 3.x", gh: [{ name: "Set up Python", uses: "actions/setup-python@v5", with: { "python-version": "3.x" } }], gl: "python:3" },
+  django: { label: "Python 3.x", gh: [{ name: "Set up Python", uses: "actions/setup-python@v5", with: { "python-version": "3.x" } }], gl: "python:3" },
+  go: { label: "Go (stable)", gh: [{ name: "Set up Go", uses: "actions/setup-go@v5", with: { "go-version": "stable" } }], gl: "golang:latest" },
+  cargo: { label: "Rust (preinstalled on hosted runners)", gh: [], gl: "rust:latest" },
+  maven: { label: "Temurin JDK 21", gh: [{ name: "Set up Java", uses: "actions/setup-java@v4", with: { distribution: "temurin", "java-version": "21" } }], gl: "maven:3-eclipse-temurin-21" },
+  gradle: { label: "Temurin JDK 21", gh: [{ name: "Set up Java", uses: "actions/setup-java@v4", with: { distribution: "temurin", "java-version": "21" } }], gl: "gradle:jdk21" },
+  dotnet: { label: ".NET 8", gh: [{ name: "Set up .NET", uses: "actions/setup-dotnet@v4", with: { "dotnet-version": "8.0.x" } }], gl: "mcr.microsoft.com/dotnet/sdk:8.0" },
+  php: { label: "PHP (preinstalled on hosted runners)", gh: [], gl: "php:8" },
+  laravel: { label: "PHP (preinstalled on hosted runners)", gh: [], gl: "php:8" },
+  wordpress: { label: "PHP (preinstalled on hosted runners)", gh: [], gl: "php:8" },
+  bundler: { label: "Ruby (preinstalled on hosted runners)", gh: [], gl: "ruby:3" },
+  mix: { label: "Elixir — add your own setup step", gh: [], gl: "elixir:latest" },
+  bun: { label: "Bun", gh: [{ name: "Set up Bun", uses: "oven-sh/setup-bun@v2" }], gl: "oven/bun:latest" },
+  deno: { label: "Deno", gh: [{ name: "Set up Deno", uses: "denoland/setup-deno@v2", with: { "deno-version": "v2.x" } }], gl: "denoland/deno:latest" },
+  flutter: { label: "Flutter — add your own setup step", gh: [], gl: "ghcr.io/cirruslabs/flutter:stable" },
+  dart: { label: "Dart — add your own setup step", gh: [], gl: "dart:stable" },
+  swift: { label: "Swift — add your own setup step", gh: [], gl: "swift:latest" },
+  cmake: { label: "CMake/CTest (preinstalled on hosted runners)", gh: [], gl: "gcc:latest" },
+};
+
+/** Renders one GitHub Actions step block at four-space indentation. */
+function renderGhStep(step) {
+  const lines = [`      - name: ${step.name}`, `        uses: ${step.uses}`];
+  if (step.with) {
+    lines.push(`        with:`);
+    for (const [k, v] of Object.entries(step.with)) lines.push(`          ${k}: "${v}"`);
+  }
+  return lines.join("\n");
+}
+
+const HEADER = (stack, version) =>
+  `# Generated by jules-orchestrator-kit v${version} for a '${stack}' project.
+#
+# This file is yours now — edit it freely. Two things worth doing before you
+# rely on it:
+#   1. Pin each third-party action to a commit SHA (a tag can be moved).
+#   2. Check that the runtime versions below match what the project targets.
+#
+# Regenerate with: agentctl ci init --force
+`;
+
+/**
+ * @param {object} opts
+ * @param {string} opts.target - "github" | "gitlab"
+ * @param {{stack: string}} opts.stack - result of detectStack()
+ * @param {object} [opts.config] - loaded config, for base_branch
+ * @param {string} [opts.version]
+ * @returns {{ file: string, content: string, setupSummary: string }}
+ */
+export function buildCiWorkflow(opts = {}) {
+  const target = CI_TARGETS.includes(opts.target) ? opts.target : "github";
+  const stackId = opts.stack?.stack || "unknown";
+  const base = opts.config?.baseBranch || "main";
+  const version = opts.version || "0";
+  const toolchain = STACK_TOOLCHAINS[stackId] || null;
+  const setupSummary = toolchain ? toolchain.label : "Node only";
+
+  if (target === "gitlab") {
+    const image = toolchain?.gl || "node:20";
+    const needsNode = image !== "node:20" && !image.startsWith("node");
+    const content = `${HEADER(stackId, version)}
+agent-gate:
+  image: ${image}
+  stage: test
+  variables:
+    GIT_DEPTH: "0"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "${base}"
+  script:${
+    needsNode
+      ? `
+    # agentctl is a Node CLI, so the image needs Node even when the project is not.
+    - command -v node >/dev/null 2>&1 || (apt-get update -qq && apt-get install -y -qq nodejs npm)`
+      : ""
+  }
+    - npx --yes jules-orchestrator-kit check --mode committed --base "origin/${base}"
+`;
+    return { file: ".gitlab-ci.agent-gate.yml", content, setupSummary };
+  }
+
+  const extraSteps = (toolchain?.gh || []).map(renderGhStep).join("\n");
+  const content = `${HEADER(stackId, version)}
+name: Agent Safety Gate
+
+on:
+  pull_request:
+    branches: [ ${base} ]
+  push:
+    branches: [ ${base} ]
+
+permissions:
+  contents: read
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # The gate compares the branch against its merge base, which needs
+          # full history rather than the default single-commit fetch.
+          fetch-depth: 0
+          persist-credentials: false
+
+      # agentctl is a Node CLI: the runner needs Node whatever the project is
+      # written in.
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+${extraSteps ? extraSteps + "\n" : ""}
+      - name: Run agent safety gate
+        run: npx --yes jules-orchestrator-kit check --mode committed --base "origin/${base}"
+`;
+  return { file: ".github/workflows/agent-gate.yml", content, setupSummary };
+}
+
+/**
+ * Write the generated workflow, refusing to clobber an existing file unless
+ * asked.
+ *
+ * @param {string} root
+ * @param {object} [opts] - see {@link buildCiWorkflow}, plus `force` and `dryRun`
+ * @returns {{ ok: boolean, file?: string, written?: boolean, stack?: string, setupSummary?: string, content?: string, error?: string }}
+ */
+export function writeCiWorkflow(root, opts = {}) {
+  if (opts.target && !CI_TARGETS.includes(opts.target)) {
+    return { ok: false, error: `Unknown CI target '${opts.target}'. Choose one of: ${CI_TARGETS.join(", ")}` };
+  }
+
+  const built = buildCiWorkflow(opts);
+  const stackId = opts.stack?.stack || "unknown";
+  const abs = join(root, built.file);
+
+  if (opts.dryRun) {
+    return { ok: true, file: built.file, written: false, stack: stackId, setupSummary: built.setupSummary, content: built.content };
+  }
+
+  if (existsSync(abs) && !opts.force) {
+    let identical = false;
+    try {
+      identical = readFileSync(abs, "utf-8") === built.content;
+    } catch (_) {
+      // Unreadable target: treat as different so the caller is told to --force
+      // rather than being told nothing changed.
+    }
+    return {
+      ok: true,
+      file: built.file,
+      written: false,
+      identical,
+      stack: stackId,
+      setupSummary: built.setupSummary,
+      content: built.content,
+    };
+  }
+
+  try {
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, built.content, "utf-8");
+  } catch (err) {
+    return { ok: false, error: `Could not write ${built.file}: ${err.message}` };
+  }
+
+  return { ok: true, file: built.file, written: true, stack: stackId, setupSummary: built.setupSummary, content: built.content };
+}

package/src/config.mjs

@@ -293,6 +293,10 @@ export function detectPackageManager(root = process.cwd(), pkg = {}) {
   return "npm";
 }
 
+import { buildProfileStages, PROFILE_NAMES, PROFILE_DESCRIPTIONS } from "./profiles.mjs";
+
+export { buildProfileStages, PROFILE_NAMES, PROFILE_DESCRIPTIONS };
+
 import {
   detectPolyglotStack,
   resolveWorkspaceBoundary,
@@ -321,6 +325,10 @@ export function detectStack(projectRoot = process.cwd()) {
 export function resolveVerify(root = process.cwd(), userVerify = {}) {
   const s = detectStack(root);
   return {
+    // Carried through so `verify.profile` can gate stack-specific gates (V8
+    // diff coverage only exists where the test command runs on Node) without
+    // every caller re-running stack detection.
+    stack: s.stack || "unknown",
     setup: userVerify.setup ?? s.setupCmd ?? "",
     lint: userVerify.lint ?? s.fmtCmd ?? "",
     test: userVerify.test ?? s.testCmd ?? "",
@@ -501,22 +509,42 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
     if (normalizedLimits[k] === undefined) delete normalizedLimits[k];
   }
 
+  // The verification commands, resolved once, so a profile can be expanded
+  // against the same values the gate will actually run.
+  const mergedVerify = {
+    setup: rawSetup ?? autoVerify.setup ?? "",
+    lint: rawLint ?? autoVerify.lint ?? "",
+    test: rawTest ?? autoVerify.test,
+    unit: rawUnit ?? rawTest ?? autoVerify.unit ?? autoVerify.test,
+    fuzz: rawFuzz ?? autoVerify.fuzz ?? "",
+    invariant: rawInvariant ?? autoVerify.invariant ?? "",
+    e2e: rawE2e ?? autoVerify.e2e ?? "",
+    teardown: rawTeardown ?? autoVerify.teardown ?? "",
+    build: rawBuild ?? autoVerify.build,
+    policy: parsed.verify?.policy ?? autoVerify.policy,
+  };
+
+  // A hand-written `verify.stages:` is the operator being explicit and always
+  // wins; `verify.profile:` is the shorthand, expanded here rather than frozen
+  // into the scaffolded YAML so it stays correct when the stack changes.
+  const rawProfile = parsed.verify?.profile ?? parsed.profile ?? null;
+  const explicitStages = parsed.verify?.stages ?? autoVerify.stages ?? null;
+  const profilePlan =
+    !explicitStages && rawProfile
+      ? buildProfileStages(rawProfile, { stack: autoVerify.stack, verify: mergedVerify })
+      : null;
+
   const config = {
     version: parsed.version || DEFAULTS.version,
     provider: parsed.provider || DEFAULTS.provider,
     tier: activeTier,
     verify: {
-      setup: rawSetup ?? autoVerify.setup ?? "",
-      lint: rawLint ?? autoVerify.lint ?? "",
-      test: rawTest ?? autoVerify.test,
-      unit: rawUnit ?? rawTest ?? autoVerify.unit ?? autoVerify.test,
-      fuzz: rawFuzz ?? autoVerify.fuzz ?? "",
-      invariant: rawInvariant ?? autoVerify.invariant ?? "",
-      e2e: rawE2e ?? autoVerify.e2e ?? "",
-      teardown: rawTeardown ?? autoVerify.teardown ?? "",
-      build: rawBuild ?? autoVerify.build,
-      stages: parsed.verify?.stages ?? autoVerify.stages ?? null,
-      policy: parsed.verify?.policy ?? autoVerify.policy,
+      ...mergedVerify,
+      stages: explicitStages ?? profilePlan?.stages ?? null,
+      profile: profilePlan?.profile ?? (rawProfile ? String(rawProfile).toLowerCase() : null),
+      // Named so `doctor` can tell an operator that the gate they enabled is
+      // running one fewer check than they think, and why.
+      profileSkipped: profilePlan?.skipped ?? [],
       timeoutMs: Number.isFinite(Number(verifyTimeoutMs)) ? Number(verifyTimeoutMs) : 60000,
     },
     evidence: {

package/src/engine.mjs

@@ -19,6 +19,7 @@ import { hydratePrompt, harvestFailure } from "./memory.mjs";
 import { resolveRolePrompt } from "./role-resolver.mjs";
 
 import { runAssertion } from "./assertions.mjs";
+import { buildDefaultStages } from "./profiles.mjs";
 import {
   computeDirectoryHash,
   generateEvidenceManifest,
@@ -283,27 +284,7 @@ export async function gate(opts = {}) {
   if (Array.isArray(trustedVerify.stages) && trustedVerify.stages.length > 0) {
     stagesToRun.push(...trustedVerify.stages);
   } else {
-    if (trustedVerify.setup) {
-      stagesToRun.push({ id: "setup", kind: "setup", cmd: trustedVerify.setup, required: true, networkAccess: "allow" });
-    }
-    if (trustedVerify.lint) {
-      stagesToRun.push({ id: "lint", kind: "lint", cmd: trustedVerify.lint, required: true, networkAccess: trustedVerify.policy?.networkAccess || "allow" });
-    }
-    if (trustedVerify.test || trustedVerify.unit) {
-      stagesToRun.push({ id: "unit", kind: "test", cmd: trustedVerify.test || trustedVerify.unit, required: true, networkAccess: trustedVerify.policy?.networkAccess || "allow" });
-    }
-    if (trustedVerify.fuzz) {
-      stagesToRun.push({ id: "fuzz", kind: "fuzz", cmd: trustedVerify.fuzz, required: true, networkAccess: trustedVerify.policy?.networkAccess || "allow" });
-    }
-    if (trustedVerify.invariant) {
-      stagesToRun.push({ id: "invariant", kind: "invariant", cmd: trustedVerify.invariant, required: true, networkAccess: trustedVerify.policy?.networkAccess || "allow" });
-    }
-    if (trustedVerify.e2e) {
-      stagesToRun.push({ id: "e2e", kind: "e2e", cmd: trustedVerify.e2e, required: true, networkAccess: "allow" });
-    }
-    if (trustedVerify.build) {
-      stagesToRun.push({ id: "build", kind: "build", cmd: trustedVerify.build, required: true, networkAccess: trustedVerify.policy?.networkAccess || "allow" });
-    }
+    stagesToRun.push(...buildDefaultStages(trustedVerify));
   }
 
   try {

package/src/env-aliases.mjs

@@ -0,0 +1,80 @@
+/**
+ * Vendor-neutral spellings for every environment variable the kit reads.
+ *
+ * Every knob in this codebase is spelled `JULES_*`, which is accurate for the
+ * provider it was written against and wrong for every other one: a repository
+ * driving `claude-code` or `codex` still had to export `JULES_SWARM_CONCURRENCY`
+ * to set worker slots, and `JULES_API_KEY` to set a key that never goes to
+ * Jules. Renaming the variables outright would break every existing checkout
+ * and CI job, so both spellings are supported and this table is the only place
+ * that has to know they are the same knob.
+ *
+ * Direction is deliberate: `AGENT_*` is the name to document, `JULES_*` is the
+ * name the code reads, and the alias fills the second from the first. A
+ * `JULES_*` value already in the environment always wins, so adding an
+ * `AGENT_*` export can never change the behaviour of a working setup.
+ *
+ * @type {Record<string, string>}
+ */
+export const ENV_ALIASES = {
+  AGENT_API_KEY: "JULES_API_KEY",
+  AGENT_API_KEYS: "JULES_API_KEYS",
+  AGENT_API_KEY_SECONDARY: "JULES_API_KEY_SECONDARY",
+  AGENT_API_URL: "JULES_API_URL",
+  AGENT_REPO: "JULES_REPO",
+  AGENT_PROJECT_ID: "JULES_PROJECT_ID",
+  AGENT_PROJECT_ROOT: "JULES_PROJECT_ROOT",
+  AGENT_TIER: "JULES_TIER",
+  AGENT_DAILY_BUDGET: "JULES_DAILY_BUDGET",
+  AGENT_MAX_DIFF_KB: "JULES_MAX_DIFF_KB",
+  AGENT_DRY_RUN: "JULES_DRY_RUN",
+  AGENT_REPOLESS: "JULES_REPOLESS",
+  AGENT_SWARM_CONCURRENCY: "JULES_SWARM_CONCURRENCY",
+  AGENT_SWARM_STAGGER_MS: "JULES_SWARM_STAGGER_MS",
+  AGENT_PACE_MS: "JULES_PACE_MS",
+  AGENT_SLOT_INDEX: "JULES_SLOT_INDEX",
+  AGENT_SLOT_TOTAL: "JULES_SLOT_TOTAL",
+  AGENT_USE_WORKTREES: "JULES_USE_WORKTREES",
+  AGENT_ALLOW_COMMAND_FILE_CHANGES: "JULES_ALLOW_COMMAND_FILE_CHANGES",
+  AGENT_ALLOW_AGENT_RULE_CHANGES: "JULES_ALLOW_AGENT_RULE_CHANGES",
+};
+
+/**
+ * Fill the legacy `JULES_*` variables from their `AGENT_*` equivalents.
+ *
+ * Mutates the passed environment object in place — that is the point: every
+ * downstream module reads `process.env` directly, and rewriting hundreds of
+ * call sites to consult an alias table would be a far larger change with far
+ * more places to get it wrong. Called once at process entry.
+ *
+ * An empty-string alias is treated as unset, matching how the rest of the kit
+ * reads keys (`(process.env.X || "").trim()`), so `AGENT_API_KEY=` in a .env
+ * file does not shadow a real `JULES_API_KEY`.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {string[]} canonical names that were populated from an alias
+ */
+export function applyEnvAliases(env = process.env) {
+  const applied = [];
+  for (const [alias, canonical] of Object.entries(ENV_ALIASES)) {
+    const aliasValue = env[alias];
+    if (aliasValue === undefined || String(aliasValue).trim() === "") continue;
+    const existing = env[canonical];
+    if (existing !== undefined && String(existing).trim() !== "") continue;
+    env[canonical] = aliasValue;
+    applied.push(canonical);
+  }
+  return applied;
+}
+
+/**
+ * Both spellings of one knob, for help text and diagnostics that should name
+ * the vendor-neutral variable first.
+ *
+ * @param {string} canonical - a `JULES_*` name
+ * @returns {{ canonical: string, alias: string|null }}
+ */
+export function describeEnvVar(canonical) {
+  const alias = Object.entries(ENV_ALIASES).find(([, c]) => c === canonical)?.[0] || null;
+  return { canonical, alias };
+}

package/src/mcp.mjs

@@ -143,7 +143,7 @@ export const MCP_TOOLS = [
   },
   {
     name: "get_jules_status",
-    description: "Retrieve orchestrator status including daily task budget, active locks, and stack diagnostics.",
+    description: "Retrieve orchestrator status: daily task budget, active locks, stack diagnostics, the configured provider and whether it is reachable, and the verification stages the gate will run.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -439,6 +439,10 @@ export async function handleMcpRequest(request, opts = {}) {
         const stackInfo = detectStack(root);
         const budget = budgetStatus(config, root);
         const locks = lockStatus(root);
+        const { probeProvider } = await import("./provider-readiness.mjs");
+        const { buildDefaultStages } = await import("./profiles.mjs");
+        const providerProbe = probeProvider(config.provider || "jules");
+        const profileStages = config.verify.stages || buildDefaultStages(config.verify);
         const status = {
           version: MCP_SERVER_INFO.version,
           root,
@@ -455,6 +459,20 @@ export async function handleMcpRequest(request, opts = {}) {
           },
           activeLocksCount: locks.length,
           locks,
+          // An IDE agent orienting itself needs to know which agent this repo
+          // dispatches to and how hard its work will be verified before it
+          // starts, not after the gate rejects it.
+          provider: {
+            name: providerProbe.name,
+            kind: providerProbe.kind,
+            ready: providerProbe.ready,
+            reason: providerProbe.reason,
+          },
+          verification: {
+            profile: config.verify.profile,
+            stages: profileStages.map((st) => st.id),
+            skipped: (config.verify.profileSkipped || []).map((sk) => sk.id),
+          },
         };
         return {
           jsonrpc: "2.0",

package/src/ops/doctor-registry.mjs

@@ -3,6 +3,7 @@ import { join, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { execFileSync, spawnSync } from "node:child_process";
 import { loadConfig } from "../config.mjs";
+import { probeProvider, detectAvailableProviders } from "../provider-readiness.mjs";
 import { resolveConcurrency } from "../budget.mjs";
 
 /**
@@ -429,40 +430,60 @@ export async function runDoctorChecks(options = {}) {
     });
   }
 
-  // 7. Jules Provider Key Check
-  const keyVar = process.env.JULES_API_KEY ? "JULES_API_KEY" : process.env.GEMINI_API_KEY ? "GEMINI_API_KEY" : "";
-  if (keyVar) {
+  // 7. Provider readiness — for the provider this repository actually selected.
+  //
+  // This used to ask one question ("is JULES_API_KEY set?") and report it as a
+  // high-severity warning regardless of the configured provider, so a
+  // repository driving the Claude Code or Codex CLI was permanently told it was
+  // misconfigured over a key it neither needs nor should have.
+  let configuredProvider = "jules";
+  try {
+    configuredProvider = loadConfig(root).provider || "jules";
+  } catch (_) {
+    // Fall back to the default; config.present already reports a broken config.
+  }
+  const providerProbe = probeProvider(configuredProvider);
+  addResult({
+    id: "provider.key",
+    category: "Provider",
+    title: `Provider Readiness (${providerProbe.name})`,
+    status: providerProbe.ready ? "pass" : "warn",
+    severity: providerProbe.ready ? "info" : "high",
+    // Naming the variable, not the value: an operator who wonders which key a
+    // dispatch will use should not have to echo a secret to find out.
+    summary: `${providerProbe.label} — ${providerProbe.reason}`,
+    remediation: providerProbe.ready
+      ? []
+      : [
+          {
+            summary: providerProbe.remedy,
+            risk: "low",
+            automatic: false,
+            requiresProbe: false,
+          },
+        ],
+    evidence: [
+      { label: "provider", value: providerProbe.name, sensitive: false },
+      { label: "providerKind", value: providerProbe.kind, sensitive: false },
+      { label: "ready", value: providerProbe.ready, sensitive: false },
+      { label: "keySource", value: providerProbe.keySource || "", sensitive: false },
+      { label: "binaryFound", value: Boolean(providerProbe.binPath), sensitive: false },
+    ],
+  });
+
+  // 7a. What else this machine could dispatch to. Purely informational: an
+  // operator blocked on one provider should not have to discover by reading
+  // source that three others are installed and ready.
+  const alternatives = detectAvailableProviders().filter((p) => p.ready && p.name !== providerProbe.name);
+  if (alternatives.length > 0) {
     addResult({
-      id: "provider.key",
-      category: "Jules",
-      title: "Jules Provider API Key",
+      id: "provider.alternatives",
+      category: "Provider",
+      title: "Other Providers Available",
       status: "pass",
       severity: "info",
-      // Naming the variable, not the value: an operator who wonders which key a
-      // dispatch will use should not have to echo a secret to find out.
-      summary: `API key supplied via ${keyVar} (environment only — never written to config or sent anywhere but the provider)`,
-      evidence: [
-        { label: "keyConfigured", value: true, sensitive: false },
-        { label: "keySource", value: keyVar, sensitive: false },
-      ],
-    });
-  } else {
-    addResult({
-      id: "provider.key",
-      category: "Jules",
-      title: "Jules Provider API Key",
-      status: "warn",
-      severity: "high",
-      summary: "Neither JULES_API_KEY nor GEMINI_API_KEY environment variable is set",
-      remediation: [
-        {
-          summary: "Export JULES_API_KEY in your shell profile, or place it in a git-ignored .env",
-          risk: "low",
-          automatic: false,
-          requiresProbe: false,
-        },
-      ],
-      evidence: [{ label: "keyConfigured", value: false, sensitive: false }],
+      summary: `Also ready on this machine: ${alternatives.map((p) => p.name).join(", ")} — switch with provider: in .agent/config.yml`,
+      evidence: alternatives.map((p) => ({ label: p.name, value: p.reason, sensitive: false })),
     });
   }
 
@@ -477,7 +498,7 @@ export async function runDoctorChecks(options = {}) {
 
     addResult({
       id: "provider.key.dotenv",
-      category: "Jules",
+      category: "Provider",
       title: "Local .env secrecy",
       status: tracked ? "fail" : "pass",
       severity: tracked ? "critical" : "info",