omp-conductor 0.18.1 → 0.19.0

package/src/config-schema.ts

@@ -31,6 +31,7 @@ import {
   DEFAULT_AUTHORITY,
   DEFAULT_CAPS,
   DEFAULT_PROJECT_POLICY,
+  DEFAULT_REVIEW_ADJUDICATOR_ROLE,
   DEFAULT_REVIEW_MAX_ROUNDS,
   DEFAULT_REVIEW_STRICTNESS,
   DRAFT_POLICIES,
@@ -41,6 +42,7 @@ import {
   RELEASE_REQUIREMENTS,
   RELEASE_SHAPES,
   REPORT_SCOPES,
+  REVIEW_ADJUDICATOR_RE,
   REVIEW_MAX_ROUNDS_MAX,
   REVIEW_MAX_ROUNDS_MIN,
   REVIEW_STRICTNESS,
@@ -123,6 +125,14 @@ const capsSchema = z
       .min(0)
       .nullable()
       .describe(`Rolling-day spend ceiling; null means no spend gate (default ${DEFAULT_CAPS.dailySpendUsd})`),
+    maxRunSpendUsd: z
+      .number()
+      .positive()
+      .nullable()
+      .describe(
+        "Ceiling on one run, reserved from the daily budget before it launches; " +
+          "null derives it from dailySpendUsd. Must not exceed dailySpendUsd",
+      ),
     planUsage: z.union([planUsageCap, z.null()]).describe(`Plan-allowance guard, or null for unmetered`),
     workerMaxTurns: z.number().min(0).describe(`Turn ceiling for one worker (default ${DEFAULT_CAPS.workerMaxTurns})`),
     workerMaxTurnsCeiling: z.number().min(0).describe(`Maximum turn budget assignable to one issue's next attempt`),
@@ -265,11 +275,15 @@ const armSchema = z
 
 /**
  * The per-project review policy (#678): how strictly green PRs are reviewed
- * and returned, and the hard ceiling on review rounds per PR lifecycle. Absent
- * or a legacy config without the key loads as `medium` with
- * {@link DEFAULT_REVIEW_MAX_ROUNDS} rounds — the recommended default for a new
- * project, materialised deterministically for every existing one, with the
- * schema bounds and the runtime defaults read from the same constants.
+ * and returned, the hard ceiling on review rounds per PR lifecycle, and which
+ * OMP model role carries the terminal review-ceiling adjudication (#875).
+ * Absent or a legacy config without the keys loads as `medium` with
+ * {@link DEFAULT_REVIEW_MAX_ROUNDS} rounds and
+ * {@link DEFAULT_REVIEW_ADJUDICATOR_ROLE} as adjudicator — the recommended
+ * defaults for a new project, materialised deterministically for every
+ * existing one, with the schema bounds and the runtime defaults read from the
+ * same constants. The adjudicator names a role only; a provider/model is
+ * refused here, because OMP owns exact provider selection.
  */
 const reviewSchema = z
   .object({
@@ -280,9 +294,16 @@ const reviewSchema = z
       .min(REVIEW_MAX_ROUNDS_MIN)
       .max(REVIEW_MAX_ROUNDS_MAX)
       .default(DEFAULT_REVIEW_MAX_ROUNDS),
+    adjudicator: z
+      .string()
+      .regex(
+        REVIEW_ADJUDICATOR_RE,
+        "must name one OMP model role — a single role token like \"task\" (never a provider/model, which omp owns)",
+      )
+      .default(DEFAULT_REVIEW_ADJUDICATOR_ROLE),
   })
   .strict()
-  .describe("Review strictness and round ceiling for green PRs");
+  .describe("Review strictness, round ceiling and adjudicator role for green PRs");
 
 const releasePolicySchema = z.union([
   releasePolicyLegacyEnum,
@@ -386,6 +407,17 @@ const projectSchema = z
     // usable, exactly like `workerModel`.
     modelFallbacks: z.unknown().optional(),
     modelFallbackThreshold: z.unknown().optional(),
+    // One stronger opaque omp selector the first spinning cap in a chain
+    // retries on (#807). Normalised (trimmed, blank dropped) by the loader
+    // like `workerModel`, and deliberately separate from `modelFallbacks`:
+    // that chain answers provider faults only.
+    workerEscalationModel: z.unknown().optional(),
+    // Providers that must bill to a subscription credential (#852). Normalised
+    // by the loader (trimmed, blanks and non-strings dropped) like
+    // `modelFallbacks`, so a malformed entry weakens the fence's *scope* rather
+    // than failing the whole config load — and an entry that survives is one the
+    // fence will actually enforce.
+    requireOauthProviders: z.unknown().optional(),
     // The fleet-owned omp settings overlay (#537): an opaque map omp's own
     // schema owns. Conductor validates YAML shape only — the loader keeps it
     // when it is a mapping and drops anything else, like `modelFallbacks`.

package/src/config.ts

@@ -28,6 +28,7 @@ import {
   DEFAULT_PROJECT_POLICY,
   DEFAULT_REPORT_POLICY,
   DEFAULT_REPORT_SCOPE,
+  DEFAULT_REVIEW_ADJUDICATOR_ROLE,
   DEFAULT_REVIEW_MAX_ROUNDS,
   DEFAULT_REVIEW_POLICY,
   DEFAULT_REVIEW_STRICTNESS,
@@ -281,6 +282,10 @@ export function resolveCaps(p: ProjectConfig, defaults: Caps): Caps {
     maxConcurrentWorkers: o.maxConcurrentWorkers ?? defaults.maxConcurrentWorkers,
     maxConcurrentWorkersPerRepo: o.maxConcurrentWorkersPerRepo ?? defaults.maxConcurrentWorkersPerRepo,
     dailySpendUsd: o.dailySpendUsd !== undefined ? o.dailySpendUsd : defaults.dailySpendUsd,
+    // Same `!== undefined` reading as `dailySpendUsd`: an explicit `null` is a
+    // deliberate "derive the per-run allowance from the daily cap" (#851), not
+    // an omission that should inherit a global override.
+    maxRunSpendUsd: o.maxRunSpendUsd !== undefined ? o.maxRunSpendUsd : defaults.maxRunSpendUsd,
     planUsage: o.planUsage !== undefined ? o.planUsage : defaults.planUsage,
     workerMaxTurns,
     workerMaxTurnsCeiling:
@@ -349,12 +354,20 @@ export function resolveArmProof(p: ProjectConfig): ArmProof {
  * The loader always materialises `review` (finalizeProject), so this is only
  * ever the fallback for a `ProjectConfig` that never went through it — a
  * hand-built one in a test, or a config written before the key existed.
- * Absent resolves to {@link DEFAULT_REVIEW_POLICY}, the documented migration
- * default every existing install deterministically upgrades to. A fresh object
- * each call, so mutating the result cannot reach the config it came from.
+ * Absent (or a legacy config that stopped at strictness and maxRounds)
+ * resolves to {@link DEFAULT_REVIEW_POLICY}, the documented migration default
+ * every existing install deterministically upgrades to — the adjudicator role
+ * included, so no consumer ever reads a policy without one (#875). A fresh
+ * object each call, so mutating the result cannot reach the config it came
+ * from.
  */
 export function resolveReview(p: ProjectConfig): ReviewPolicy {
-  return { ...(p.review ?? DEFAULT_REVIEW_POLICY) };
+  const base = p.review ?? DEFAULT_REVIEW_POLICY;
+  return {
+    strictness: base.strictness ?? DEFAULT_REVIEW_STRICTNESS,
+    maxRounds: base.maxRounds ?? DEFAULT_REVIEW_MAX_ROUNDS,
+    adjudicator: base.adjudicator ?? DEFAULT_REVIEW_ADJUDICATOR_ROLE,
+  };
 }
 
 /**
@@ -889,11 +902,14 @@ function clauseFor(rel: readonly PropertyKey[], issue: {
       return `policy must be an object with "merge" and "release" sections`;
     }
     if (rel.length === 1 && relStr === "review") {
-      return `review must be an object with "strictness" and "maxRounds"`;
+      return `review must be an object with "strictness", "maxRounds" and "adjudicator"`;
     }
     if (rel.length === 2 && rel[0] === "review" && rel[1] === "maxRounds") {
       return `review.maxRounds must be an integer between ${REVIEW_MAX_ROUNDS_MIN} and ${REVIEW_MAX_ROUNDS_MAX}, found ${found()}`;
     }
+    if (rel.length === 2 && rel[0] === "review" && rel[1] === "adjudicator") {
+      return `review.adjudicator must be a string naming one OMP model role, found ${found()}`;
+    }
     if (rel.length === 2 && relStr === "policy") return `${pathStr} must be an object`;
     if (rel.length === 1 && relStr === "caps") return `caps must be an object`;
     if (rel.length === 2 && relStr === "caps" && rel[1] === "planUsage") {
@@ -944,7 +960,7 @@ function clauseFor(rel: readonly PropertyKey[], issue: {
   if (issue.code === "unrecognized_keys") {
     const keys = (issue.keys ?? []).join(", ");
     if (pathStr === "policy") return `policy has unknown key(s): ${keys} — expected "merge" or "release"`;
-    if (pathStr === "review") return `review has unknown key(s): ${keys} — expected "strictness" and "maxRounds"`;
+    if (pathStr === "review") return `review has unknown key(s): ${keys} — expected "strictness", "maxRounds" and "adjudicator"`;
     if (pathStr === "policy.merge") return `${pathStr} has unknown key(s): ${keys} — expected ${POLICY_MERGE_KEYS}`;
     if (pathStr === "policy.release") return `${pathStr} has unknown key(s): ${keys} — expected ${POLICY_RELEASE_KEYS}`;
     if (pathStr === "caps.planUsage") {
@@ -1046,6 +1062,12 @@ function gatesCmdPath(rel: readonly PropertyKey[]): boolean {
   return rel.some((s, i) => s === "gates" && typeof rel[i + 1] === "number" && rel[rel.length - 1] === "cmd");
 }
 function capProblem(key: string, found: string): string {
+  if (key === "maxRunSpendUsd") {
+    return (
+      "caps.maxRunSpendUsd must be a positive finite number or null " +
+      `(derive it from dailySpendUsd), found ${found}`
+    );
+  }
   return key === "dailySpendUsd"
     ? `caps.dailySpendUsd must be a non-negative finite number or null (no cap), found ${found}`
     : `caps.${key} must be a non-negative finite number, found ${found}`;
@@ -1093,6 +1115,27 @@ function finalize(data: unknown, path: string): ConductorConfig {
     });
   }
 
+  // Cross-field, and checked on the EFFECTIVE caps each project will run
+  // under (#851): a per-run reservation larger than the day's budget can never
+  // be satisfied, so every candidate would be held forever by a gate the
+  // operator believed was a ceiling. Checked after resolution because the two
+  // values may come from different layers — a global `dailySpendUsd` and a
+  // per-project `maxRunSpendUsd`.
+  for (const project of projects) {
+    const effective = resolveCaps(project, defaults);
+    if (
+      effective.maxRunSpendUsd !== null &&
+      effective.dailySpendUsd !== null &&
+      effective.maxRunSpendUsd > effective.dailySpendUsd
+    ) {
+      problems.push(
+        `project "${project.name}": caps.maxRunSpendUsd ($${String(effective.maxRunSpendUsd)}) must not exceed ` +
+          `caps.dailySpendUsd ($${String(effective.dailySpendUsd)}) — a per-run reservation larger than the day's ` +
+          "budget can never be admitted",
+      );
+    }
+  }
+
   const rawHost = root["host"] as Raw | undefined;
   const host = finalizeHost(rawHost);
   const rawDbBackupDir = root["dbBackupDir"];
@@ -1216,6 +1259,34 @@ function finalizeProject(
       ? rawThreshold
       : undefined;
 
+  // The one-shot cap escalation target (#807): a hint like `workerModel`, and
+  // trimmed here because it is handed to the harness verbatim as a selector.
+  // Blank or the wrong type is dropped rather than failing the load, which is
+  // exactly the "no escalation target configured" state settlement reports.
+  const rawEscalationModel = p["workerEscalationModel"];
+  const workerEscalationModel =
+    typeof rawEscalationModel === "string" && rawEscalationModel.trim() !== ""
+      ? rawEscalationModel.trim()
+      : undefined;
+
+  // Providers whose routes must bill to a subscription credential (#852).
+  // Trimmed and de-duplicated here because each entry is compared against the
+  // provider id the harness itself reports, and a stray blank or a repeat would
+  // spend a probe subprocess proving the same thing twice. A non-array, or an
+  // entry of the wrong type, is dropped like an unusable `modelFallbacks` entry:
+  // absent means today's dispatch, byte for byte.
+  const rawRequireOauth = p["requireOauthProviders"];
+  const requireOauthProviders = Array.isArray(rawRequireOauth)
+    ? [
+        ...new Set(
+          rawRequireOauth
+            .filter((entry): entry is string => typeof entry === "string")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry !== ""),
+        ),
+      ]
+    : [];
+
   // The fleet-owned omp settings overlay (#537): an opaque map omp's own schema
   // owns, so the loader validates YAML shape only — a non-mapping is dropped
   // like an unusable `modelFallbacks` entry rather than failing the load, and
@@ -1287,6 +1358,8 @@ function finalizeProject(
     ...(workerModel === undefined ? {} : { workerModel }),
     ...(modelFallbacks.length === 0 ? {} : { modelFallbacks }),
     ...(modelFallbackThreshold === undefined ? {} : { modelFallbackThreshold }),
+    ...(workerEscalationModel === undefined ? {} : { workerEscalationModel }),
+    ...(requireOauthProviders.length === 0 ? {} : { requireOauthProviders }),
     ...(effectiveOmpSettings === undefined ? {} : { ompSettings: effectiveOmpSettings }),
     escalation,
     arm,
@@ -1320,14 +1393,17 @@ function finalizeArm(parsed: Raw | undefined): ProjectConfig["arm"] {
  * {@link DEFAULT_REVIEW_POLICY}, the documented migration default, so an
  * upgrade changes no existing project's behaviour beyond what its operators
  * then choose in setup. zod has already rejected anything outside the
- * strictness vocabulary or the validated round range, so this only fills the
- * absent-case default.
+ * strictness vocabulary, the validated round range or the adjudicator role
+ * token grammar, so this only fills the absent-case defaults — the
+ * adjudicator included (#875), deterministically the same role a new
+ * project's setup starts from.
  */
 function finalizeReview(parsed: Raw | undefined): ProjectConfig["review"] {
   if (parsed === undefined) return { ...DEFAULT_REVIEW_POLICY };
   return {
     strictness: (parsed["strictness"] as ReviewStrictness | undefined) ?? DEFAULT_REVIEW_STRICTNESS,
     maxRounds: (parsed["maxRounds"] as number | undefined) ?? DEFAULT_REVIEW_MAX_ROUNDS,
+    adjudicator: (parsed["adjudicator"] as string | undefined) ?? DEFAULT_REVIEW_ADJUDICATOR_ROLE,
   };
 }
 
@@ -1579,6 +1655,25 @@ function reconcileCaps(
       if (cap !== undefined) out.planUsage = cap;
       continue;
     }
+    if (key === "maxRunSpendUsd") {
+      // Positive or null, never 0 (#851): `dailySpendUsd: 0` is a meaningful
+      // hard stop, but a per-run allowance of 0 reserves nothing and admits
+      // nothing — it is a misconfiguration wearing a cap's clothes, so it is
+      // named rather than obeyed.
+      if (v === null) {
+        out.maxRunSpendUsd = null;
+        continue;
+      }
+      if (typeof v === "number" && Number.isFinite(v) && v > 0) {
+        out.maxRunSpendUsd = v;
+        continue;
+      }
+      problems.push(
+        `${label}.maxRunSpendUsd must be a positive finite number or null (derive it from dailySpendUsd), ` +
+          `found ${JSON.stringify(v)}`,
+      );
+      continue;
+    }
     if (typeof v === "number" && Number.isFinite(v) && v >= 0) {
       (out as Record<string, unknown>)[key as string] = v;
       continue;

package/src/credential-class.ts

@@ -0,0 +1,366 @@
+/**
+ * The credential-class fence (#852).
+ *
+ * On 2026-08-21 an Anthropic OAuth credential's refresh failed with
+ * `invalid_grant`. The exact selector `anthropic/claude-opus-5` still resolved —
+ * correct provider, correct model — but through the *other* Anthropic
+ * credential, an API key. One run then spent an estimated $25.16 against
+ * API-key billing while the operator expected subscription billing.
+ *
+ * ## Why conductor has to own this
+ *
+ * The harness cannot express it. `AuthStorage.getApiKey`
+ * (`pi-ai/src/auth-storage.ts:5290-5356`, installed 17.2.10) resolves
+ * first-match-wins across runtime override → config override → stored OAuth →
+ * login-sourced API key → provider env var → other stored API key → fallback
+ * resolver, and **an exact `provider/model` selector does not stop that
+ * cascade**. A definitive OAuth refresh failure disables that row
+ * (`auth-storage.ts:5162-5232`) and the same call descends into the API-key
+ * legs. Three surfaces that look like levers are not:
+ *
+ *  - `models.yml` `auth: "oauth"` forces OAuth-style request *shaping* and sets
+ *    `isOAuth` metadata (`model-registry.ts:636-690`); it selects nothing, and a
+ *    custom model still requires an `apiKey` unless `auth: none`.
+ *  - A provider-id variant is not a class pin: `xai-oauth` is a real distinct
+ *    provider whose own descriptor also accepts `XAI_API_KEY`
+ *    (`pi-catalog/src/provider-models/descriptors.ts:485-493`), and
+ *    `anthropic-oauth` does not exist — Anthropic's id is `anthropic`, whose env
+ *    resolver accepts both sources (`pi-ai/src/registry/anthropic.ts:7-26`).
+ *  - No setting, env var, selector suffix or request option expresses it:
+ *    `AuthApiKeyOptions` is `{ baseUrl, modelId, signal, forceRefresh }`
+ *    (`auth-storage.ts:796-813`).
+ *
+ * ## Why this is a pre-launch fence and not an audit
+ *
+ * There is no after-the-fact answer to "which class served that request".
+ * `getApiKey` returns `string | undefined` and never names the class it chose
+ * (`auth-storage.ts:5302`); `AssistantMessage` carries no credential field
+ * (`pi-ai/src/types.ts:858-912`); and session `credential_pin` entries are
+ * OAuth-only *and* change-only (`session-entries.ts:185-202`), so steady OAuth
+ * writes nothing, API-key use writes nothing, and neither a stale pin nor a
+ * missing one proves anything. A transcript audit of billing class would be a
+ * fabrication, so this module does not attempt one.
+ *
+ * What the harness *does* expose, token-free, is its current state — and that is
+ * enough to refuse before spending anything.
+ *
+ * ## The residue, stated rather than papered over
+ *
+ * This is a state check, not an atomic guarantee. If OAuth becomes invalid
+ * *during* a request, the installed resolver may still disable it and fall
+ * through to a same-provider API key, and nothing conductor can pass prevents
+ * that. The only hard lever is omp's own `disabledProviders`, which removes the
+ * provider before credential checks — and also removes the subscription route,
+ * which is why it stays an operator action rather than conductor's automatic
+ * response. The honest fix is upstream: an `AuthApiKeyOptions` that can require a
+ * credential class and refuse rather than descend.
+ *
+ * ## Why the requirement is per provider, never per run
+ *
+ * A credential belongs to a provider, not to a model — a model has none of its
+ * own. And a run's provider is not knowable in advance: `workerModel` is an
+ * opaque omp selector (it may be a role alias), and the provider-fault fallback
+ * chain (#286) can move a live run onto another provider mid-flight. So a
+ * per-run provider inference would be a guess dressed as a fact. The declared
+ * unit is therefore "this provider must bill to its subscription", and the
+ * verdict is the same for every candidate while that is untrue.
+ */
+
+import { join } from "node:path";
+
+/**
+ * The harness's own answer about one provider, as read through its exported
+ * API. Deliberately narrow: an origin kind and disabled-credential *causes*, and
+ * nothing that could carry credential material.
+ */
+export interface CredentialClassProbe {
+  provider: string;
+  /**
+   * `getCredentialOrigin(provider)` — the currently winning source
+   * (`auth-storage.ts:2689-2714`). Absent means the provider resolves to nothing
+   * at all, which is a different refusal from "resolves to the wrong class".
+   */
+  origin?: { kind: string; envVar?: string };
+  /**
+   * `listDisabledCredentials(provider)` (`auth-storage.ts:6235-6247`), reduced to
+   * class and cause. The cause is what makes a refusal actionable — an operator
+   * reading `invalid_grant` knows to re-authenticate — and it is not secret.
+   */
+  disabled: readonly { type: string; cause: string }[];
+}
+
+/** Why a fence refused, or that it did not. */
+export type CredentialClassVerdict =
+  | { ok: true }
+  | { ok: false; reason: string };
+
+/** The runnable probe's own output: one provider per request, or the failure. */
+export type CredentialClassProbeResult =
+  | { ok: true; probe: CredentialClassProbe }
+  | { ok: false; reason: string };
+
+/**
+ * Does `provider` currently bill to its subscription?
+ *
+ * Pure, so the whole decision is testable without a credential store, a
+ * subprocess or a harness — which matters because this is the function whose
+ * wrong answer costs either a fleet stall or a surprise invoice.
+ *
+ * The gate is `origin.kind === "oauth"` and nothing looser. In particular
+ * `env` is refused even when the environment variable is an OAuth *token*
+ * (`ANTHROPIC_OAUTH_TOKEN` is one): conductor cannot see whether that value is a
+ * subscription token or a key, and a fence that guesses is not a fence.
+ */
+export function oauthRequirementVerdict(probe: CredentialClassProbe): CredentialClassVerdict {
+  const { provider, origin } = probe;
+  // The disabled row is not the verdict — it is the remediation. Reported for
+  // any refusal, because "OAuth is disabled because the refresh returned
+  // invalid_grant" is the difference between an operator re-authenticating in a
+  // minute and an operator reading source for an hour.
+  const disabledOauth = probe.disabled.filter((row) => row.type === "oauth");
+  const because =
+    disabledOauth.length === 0
+      ? ""
+      : ` The ${provider} OAuth credential is disabled: ${disabledOauth
+          .map((row) => row.cause)
+          .join("; ")}.`;
+  const remedy =
+    ` Re-authenticate ${provider} (\`omp auth login ${provider}\`), or take the whole provider out of` +
+    ` play with omp's own disabledProviders — conductor will not dispatch onto an API key it was told` +
+    " not to use.";
+
+  if (origin === undefined) {
+    return {
+      ok: false,
+      reason:
+        `${provider} requires subscription (OAuth) credentials, and no ${provider} credential resolves at` +
+        ` all.${because}${remedy}`,
+    };
+  }
+  if (origin.kind === "oauth") return { ok: true };
+  const named =
+    origin.kind === "env" && origin.envVar !== undefined
+      ? `an environment variable (${origin.envVar})`
+      : `a ${origin.kind} credential`;
+  return {
+    ok: false,
+    reason:
+      `${provider} requires subscription (OAuth) credentials, but it currently resolves to ${named}, so a` +
+      ` dispatch would bill to that instead.${because}${remedy}`,
+  };
+}
+
+/**
+ * Every declared provider's verdict, in declaration order, refusing on the first
+ * that fails.
+ *
+ * One refusal at a time on purpose: a hold names the one thing to fix, and a
+ * concatenation of provider problems reads as a configuration essay rather than
+ * an action.
+ */
+export async function oauthFenceVerdict(
+  providers: readonly string[],
+  probe: (provider: string) => Promise<CredentialClassProbeResult>,
+): Promise<CredentialClassVerdict> {
+  for (const provider of providers) {
+    const result = await probe(provider);
+    if (!result.ok) {
+      // A probe that cannot answer is a refusal, not a pass. The whole point of
+      // the fence is that the expensive outcome is dispatching blind, and
+      // "we could not check" is indistinguishable from "it is wrong" in cost.
+      return {
+        ok: false,
+        reason:
+          `${provider} requires subscription (OAuth) credentials and that could not be verified: ` +
+          `${result.reason}. Refusing rather than dispatching unverified.`,
+      };
+    }
+    const verdict = oauthRequirementVerdict(result.probe);
+    if (!verdict.ok) return verdict;
+  }
+  return { ok: true };
+}
+
+/** How the probe subprocess is run, injected so tests need no harness. */
+export interface CredentialProbeDeps {
+  run?: (args: readonly string[]) => Promise<{ code: number; stdout: string; stderr: string }>;
+  /** This module's own path, so the child runs the same file it was built with. */
+  modulePath?: string;
+}
+
+const REAL_RUN = async (
+  args: readonly string[],
+): Promise<{ code: number; stdout: string; stderr: string }> => {
+  const child = Bun.spawn([...args], {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+    env: process.env,
+  });
+  const stdout = new Response(child.stdout).text();
+  const stderr = new Response(child.stderr).text();
+  const code = await child.exited;
+  return { code, stdout: await stdout, stderr: await stderr };
+};
+
+/**
+ * Ask the harness about one provider, out of process.
+ *
+ * Out of process for two reasons, and the second is the load-bearing one. It
+ * keeps the harness's module graph and its credential database out of the
+ * long-lived daemon; and it means every read is taken *now*, against whatever
+ * the harness currently believes, rather than against a pool this process
+ * loaded once and cached. A fence reading a stale in-memory pool would pass a
+ * credential that was disabled an hour ago.
+ *
+ * This mirrors `harness-loader.ts` exactly — a runnable module, spawned with
+ * `--no-install`, whose stdout is one JSON line — because that is already how
+ * this package asks the installed harness a question it must not answer itself.
+ */
+export async function probeCredentialClass(
+  provider: string,
+  deps: CredentialProbeDeps = {},
+): Promise<CredentialClassProbeResult> {
+  const run = deps.run ?? REAL_RUN;
+  const modulePath = deps.modulePath ?? join(import.meta.dir, "credential-class.ts");
+  let result: { code: number; stdout: string; stderr: string };
+  try {
+    result = await run(["bun", "--no-install", modulePath, provider]);
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+  }
+  if (result.code !== 0) {
+    const detail = (result.stderr.trim() || result.stdout.trim()).split("\n")[0] ?? `exit ${result.code}`;
+    return { ok: false, reason: detail };
+  }
+  return parseProbeOutput(provider, result.stdout);
+}
+
+/**
+ * The child's stdout, validated rather than trusted.
+ *
+ * Exported because the parse is where a malformed answer either becomes a clean
+ * refusal or becomes a fence that silently passes. Anything unexpected — not
+ * JSON, wrong provider, missing `disabled` array — is a refusal.
+ */
+export function parseProbeOutput(provider: string, stdout: string): CredentialClassProbeResult {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout.trim());
+  } catch {
+    return { ok: false, reason: "the credential probe did not answer with JSON" };
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    return { ok: false, reason: "the credential probe answered with no object" };
+  }
+  const answeredFor = Reflect.get(parsed, "provider");
+  if (answeredFor !== provider) {
+    // Never accept an answer about a provider nobody asked about: that is how a
+    // fence comes to approve the wrong route.
+    return {
+      ok: false,
+      reason: `the credential probe answered for ${String(answeredFor)}, not ${provider}`,
+    };
+  }
+  const rawDisabled = Reflect.get(parsed, "disabled");
+  if (!Array.isArray(rawDisabled)) {
+    return { ok: false, reason: "the credential probe reported no disabled-credential list" };
+  }
+  const disabled: { type: string; cause: string }[] = [];
+  for (const row of rawDisabled) {
+    if (row === null || typeof row !== "object") continue;
+    const type = Reflect.get(row, "type");
+    const cause = Reflect.get(row, "cause");
+    if (typeof type !== "string") continue;
+    disabled.push({ type, cause: typeof cause === "string" ? cause : "no cause recorded" });
+  }
+  const rawOrigin = Reflect.get(parsed, "origin");
+  let origin: { kind: string; envVar?: string } | undefined;
+  if (rawOrigin !== null && typeof rawOrigin === "object") {
+    const kind = Reflect.get(rawOrigin, "kind");
+    const envVar = Reflect.get(rawOrigin, "envVar");
+    if (typeof kind === "string") {
+      origin = { kind, ...(typeof envVar === "string" ? { envVar } : {}) };
+    }
+  }
+  return { ok: true, probe: { provider, ...(origin === undefined ? {} : { origin }), disabled } };
+}
+
+/**
+ * The two harness shapes this module needs, declared here rather than inlined.
+ *
+ * The harness is a *peer* dependency: it is absent from this package's own
+ * install and resolves from wherever the operator installed omp. Its types are
+ * therefore not available to `tsc` here, so the surface conductor relies on is
+ * written down — which is better documentation than an inferred type anyway,
+ * because it is exactly the contract that would break on a harness upgrade.
+ */
+interface HarnessAuthStorage {
+  reload?: () => Promise<void>;
+  getCredentialOrigin: (provider: string) => { kind: string; envVar?: string } | undefined;
+  listDisabledCredentials: (provider?: string) => Promise<readonly { type: string; cause: string }[]>;
+}
+
+interface HarnessAuthModule {
+  AuthStorage: new (store: unknown) => HarnessAuthStorage;
+  SqliteAuthCredentialStore: new (db: unknown) => { close: () => void };
+}
+
+interface HarnessPathsModule {
+  getAgentDbPath: (agentDir?: string) => string;
+}
+
+/**
+ * The child half: read the harness's state for one provider and print it.
+ *
+ * Everything here is the harness's own exported API — never a query against
+ * `agent.db`, whose schema is not conductor's to know. Nothing printed can carry
+ * credential material: an origin kind, an optional environment-variable *name*,
+ * and disabled classes with their causes.
+ *
+ * The imports are dynamic and their specifiers resolved at runtime because they
+ * genuinely cannot be static: the harness is an absent peer at build time (a
+ * literal specifier would fail `tsc`), it must resolve from *this package's*
+ * install root rather than Bun's ambient cache — the same anchoring
+ * `harness-loader.ts` exists to guarantee — and loading it at module scope would
+ * pull the whole harness and its credential database into the daemon, which is
+ * the thing running the probe out of process avoids.
+ */
+if (import.meta.main) {
+  const provider = process.argv[2] ?? "";
+  try {
+    if (provider === "") throw new Error("usage: credential-class.ts <provider>");
+    const { Database } = await import("bun:sqlite");
+    const auth = (await import(
+      Bun.resolveSync("@oh-my-pi/pi-coding-agent/session/auth-storage", import.meta.dir)
+    )) as HarnessAuthModule;
+    // The agent database's location is the harness's convention, taken from the
+    // harness — hardcoding `~/.omp/agent/agent.db` here would be a second
+    // opinion about where credentials live.
+    const paths = (await import(
+      Bun.resolveSync("@oh-my-pi/pi-utils", import.meta.dir)
+    )) as HarnessPathsModule;
+    const store = new auth.SqliteAuthCredentialStore(new Database(paths.getAgentDbPath()));
+    try {
+      const storage = new auth.AuthStorage(store);
+      // `reload` is what makes this read current rather than constructor-fresh:
+      // it rebuilds the active pool from the store, so a credential disabled
+      // since the row was written is absent here exactly as it is for the
+      // resolver that would have used it.
+      await storage.reload?.();
+      const origin = storage.getCredentialOrigin(provider);
+      const disabled = (await storage.listDisabledCredentials(provider)).map((row) => ({
+        type: row.type,
+        cause: row.cause,
+      }));
+      process.stdout.write(
+        `${JSON.stringify({ provider, ...(origin === undefined ? {} : { origin }), disabled })}\n`,
+      );
+    } finally {
+      store.close();
+    }
+  } catch (cause) {
+    process.stderr.write(`${cause instanceof Error ? cause.message : String(cause)}\n`);
+    process.exitCode = 1;
+  }
+}