infraweaver 0.1.0

package/src/utils/buildInfraweaverFooter.ts

@@ -0,0 +1,104 @@
+import { PRODUCT_NAME } from "#app/brand";
+import { chromeStrings } from "#app/i18n/scaffolding";
+import {
+  getModelProvider,
+  modelAliases,
+  providers,
+  resolveDisplayAlias,
+} from "#app/models";
+import type { UserFacingLanguage } from "#app/utils/payload";
+
+export const INFRAWEAVER_DIVIDER =
+  "<!-- INFRAWEAVER_DIVIDER_DO_NOT_REMOVE_PLZ -->";
+
+export interface BuildInfraweaverFooterParams {
+  /** add "via Infraweaver" link */
+  triggeredBy?: boolean;
+  /** arbitrary custom parts (e.g., action links) */
+  customParts?: string[] | undefined;
+  /** model slug from payload (e.g., "anthropic/claude-opus"). shown in footer as "Using `Model Name`" */
+  model?: string | undefined;
+  /**
+   * When the action engaged the BYOK fallback, this is the slug the user
+   * had configured (e.g. "anthropic/claude-opus") — the footer renders
+   * `Using <free model> (credentials for <configured> not configured)`
+   * so the substitution is visible in PR comments + reviews.
+   */
+  fallbackFrom?: string | undefined;
+  /** user-facing language for the fixed "Using" verb (default English); the
+   * model name + product attribution stay verbatim regardless. */
+  language?: UserFacingLanguage | undefined;
+}
+
+/** Provider display name (e.g. "Anthropic") for the slug, or the raw provider segment as a fallback. */
+function providerDisplayName(slug: string): string {
+  try {
+    const key = getModelProvider(slug);
+    const meta = providers[key as keyof typeof providers];
+    return meta?.displayName ?? key;
+  } catch {
+    // raw IDs without a `/` (Bedrock model IDs) — never reach this function
+    // in practice because the BYOK fallback skips Bedrock, but defensively
+    // return the slug itself rather than throw if it ever does.
+    return slug;
+  }
+}
+
+function formatModelLabel(params: {
+  model: string;
+  fallbackFrom?: string | undefined;
+}): string {
+  const alias =
+    resolveDisplayAlias(params.model) ??
+    // reverse-lookup: when the caller passes an effective model (proxy or
+    // resolved target like "openrouter/anthropic/claude-opus-4.7") instead of
+    // a stored alias slug, find the alias whose resolve target matches so we
+    // still render a friendly display name.
+    modelAliases.find(
+      (a) => a.resolve === params.model || a.openRouterResolve === params.model,
+    );
+  const displayName = alias?.displayName ?? params.model;
+  const base = alias?.isFree
+    ? `\`${displayName}\` (free)`
+    : `\`${displayName}\``;
+  if (!params.fallbackFrom) return base;
+  return `${base} (credentials for ${providerDisplayName(params.fallbackFrom)} not configured)`;
+}
+
+/**
+ * build a infraweaver footer with configurable parts
+ * order: action links (customParts) > model > attribution
+ */
+export function buildInfraweaverFooter(
+  params: BuildInfraweaverFooterParams,
+): string {
+  const parts: string[] = [];
+
+  if (params.customParts) {
+    parts.push(...params.customParts);
+  }
+
+  if (params.triggeredBy) {
+    parts.push(`via ${PRODUCT_NAME}`);
+  }
+
+  if (params.model) {
+    const using = chromeStrings(params.language).using;
+    parts.push(
+      `${using} ${formatModelLabel({ model: params.model, fallbackFrom: params.fallbackFrom })}`,
+    );
+  }
+
+  return `\n\n${INFRAWEAVER_DIVIDER}\n<sup>${parts.join(" ｜ ")}</sup>`;
+}
+
+/**
+ * strip any existing infraweaver footer from a comment body
+ */
+export function stripExistingFooter(body: string): string {
+  const dividerIndex = body.indexOf(INFRAWEAVER_DIVIDER);
+  if (dividerIndex === -1) {
+    return body;
+  }
+  return body.substring(0, dividerIndex).trimEnd();
+}

package/src/utils/byokFallback.ts

@@ -0,0 +1,137 @@
+import { PRODUCT_NAME } from "#app/brand";
+import type { AgentId } from "#app/external";
+import { getModelEnvVars, getProviderDisplayName } from "#app/models";
+import { hasEnvVar } from "#app/utils/env";
+import { isOpenAiCompatibleRoute } from "#app/utils/openaiCompatible";
+
+/**
+ * Slug we fall back to when a BYOK-required model is configured but the
+ * runner has no provider key in env. Picked because it's free, stable, and
+ * currently served by OpenCode Zen without a key.
+ *
+ * The slug is intentionally hard-coded and not a config knob — the
+ * fallback is a safety net, not a user-facing preference, and adding a
+ * config surface here would just push the same "what to fall back to"
+ * decision into another setting that goes stale the same way.
+ */
+export const FREE_FALLBACK_SLUG = "opencode/big-pickle";
+
+/**
+ * Outcome of the BYOK model gate.
+ *
+ *   - `use-resolved`: run the configured model as-is.
+ *   - `fallback`: the runner has NO provider key for this model's provider,
+ *     so swap to the free OpenCode slug — a genuine no-key safety net.
+ *   - `unavailable`: a provider key IS present but the configured model is
+ *     not one OpenCode can route with it. This is almost always a wrong or
+ *     mistyped model id (or a key scoped to other models). We must NOT
+ *     silently downgrade to the free model — that hides the misconfiguration
+ *     and produces a free run the user didn't ask for (see PR #2). The caller
+ *     fails loudly with the authorized-model list instead.
+ */
+export type FallbackDecision =
+  | { kind: "use-resolved" }
+  | { kind: "fallback"; from: string; to: string }
+  | { kind: "unavailable"; model: string };
+
+/**
+ * Does the runner have a provider credential for `resolvedModel`'s provider?
+ *
+ * Uses the provider→envVars map in `models.ts` (provider-level, since a
+ * resolved specifier like `google/gemini-3.5-flash-lite` won't match a catalog
+ * model key and correctly falls through to the provider's env vars). A present
+ * key is what distinguishes the two not-authorized situations: key present =
+ * wrong/unavailable model id (fail loudly); no key = genuine BYOK gap (free
+ * fallback).
+ */
+export function hasProviderKeyForModel(resolvedModel: string): boolean {
+  return getModelEnvVars(resolvedModel).some(hasEnvVar);
+}
+
+/**
+ * Decide whether to run the configured model, fall back to the free model, or
+ * fail because the model is unavailable to the present key.
+ *
+ * `authorized` is OpenCode's authoritative "what can I route right now"
+ * snapshot, captured after Codex auth.json is in place.
+ *
+ * Skip cases (always `use-resolved`, without consulting `authorized`):
+ *   - No resolved model: auto-select handles it downstream.
+ *   - Resolved model is the free fallback already.
+ *   - Resolved model is a raw Bedrock / Vertex ID (no `/`): the routing
+ *     validators (`validateBedrockSetup` / `validateVertexSetup`) cover
+ *     auth + region/location/model-id; `opencode models` does not.
+ *   - The selected agent is `claude`: the Claude Code harness brings its own
+ *     auth and `resolveAgent` only returns it when that auth is present.
+ *     `opencode models` can't see `CLAUDE_CODE_OAUTH_TOKEN`, so without this
+ *     an OAuth-subscription run on an Anthropic model would land in
+ *     `unavailable` (the token counts as a present provider key) and fail a
+ *     run the claude harness serves fine. `validateAgentApiKey` still covers
+ *     the claude path with its own Anthropic auth check.
+ */
+export function selectFallbackModelIfNeeded(input: {
+  resolvedModel: string | undefined;
+  authorized: Set<string>;
+  /** whether a provider key for the resolved model's provider is present in env */
+  providerKeyPresent: boolean;
+  /** which agent harness `resolveAgent` picks for the resolved model */
+  agentName: AgentId;
+}): FallbackDecision {
+  if (!input.resolvedModel) return { kind: "use-resolved" };
+  if (input.resolvedModel === FREE_FALLBACK_SLUG)
+    return { kind: "use-resolved" };
+  if (!input.resolvedModel.includes("/")) return { kind: "use-resolved" };
+  // OpenAI-compatible BYOK ids can contain a `/` (e.g. a HuggingFace `org/model`),
+  // so the no-slash skip above misses them. `validateOpenAiCompatibleSetup` covers
+  // base-URL/model-id presence; `opencode models` can't see a custom endpoint.
+  if (isOpenAiCompatibleRoute(input.resolvedModel))
+    return { kind: "use-resolved" };
+  if (input.agentName === "claude") return { kind: "use-resolved" };
+  if (input.authorized.has(input.resolvedModel))
+    return { kind: "use-resolved" };
+
+  // resolved model is NOT in OpenCode's authorized set. split the two cases:
+  if (input.providerKeyPresent) {
+    // a key for this provider is configured — the model id is wrong or not
+    // available to this key. surface it; do not silently serve a free model.
+    return { kind: "unavailable", model: input.resolvedModel };
+  }
+  // no key at all → genuine BYOK gap → free safety net so the run still works.
+  return {
+    kind: "fallback",
+    from: input.resolvedModel,
+    to: FREE_FALLBACK_SLUG,
+  };
+}
+
+/**
+ * Loud, actionable error for the `unavailable` decision: a provider key is
+ * present but the configured model isn't one the key can serve. Lists the
+ * models OpenCode CAN route (same-provider first) so the user can copy a valid
+ * slug instead of getting a silent free downgrade.
+ */
+export function buildUnavailableModelError(input: {
+  model: string;
+  authorized: Set<string>;
+}): string {
+  const provider = input.model.slice(0, input.model.indexOf("/"));
+  const providerLabel = getProviderDisplayName(input.model) ?? provider;
+  const all = [...input.authorized].sort();
+  const sameProvider = all.filter((m) => m.startsWith(`${provider}/`));
+  const shown = sameProvider.length > 0 ? sameProvider : all;
+  const list =
+    shown.length > 0
+      ? shown.map((m) => `  - ${m}`).join("\n")
+      : "  (none — your key does not authorize any model OpenCode can route)";
+
+  return [
+    `model "${input.model}" is not available to your ${providerLabel} key.`,
+    ``,
+    `A provider credential is present, so ${PRODUCT_NAME} did not fall back to the free model —`,
+    `it surfaces this instead so you can pick a valid id. Models your key can serve:`,
+    ``,
+    list,
+    ``,
+    `Set the model (the \`model\` input, or \`INFRAWEAVER_MODEL\`) to one of the slugs above.`,
+  ].join("\n");
+}

package/src/utils/changeImpact.ts

@@ -0,0 +1,330 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { log } from "#app/utils/cli";
+import { $ } from "#app/utils/shell";
+
+/**
+ * Deterministic change-impact leads for Terraform review.
+ *
+ * On `checkout_pr` we hand the reviewer a supplemental, EXPLICITLY INCOMPLETE
+ * list of where the PR's changed HCL declarations are referenced elsewhere in
+ * the repo — the blast radius the raw diff alone doesn't show. It is a lead
+ * list, never a coverage source: an empty artifact is not evidence of no wider
+ * impact, and the authoritative diff read still governs the review.
+ *
+ * IaC-specific (vs. pullfrog's generic symbol grep): we extract only unambiguous
+ * HCL declarations from the diff and grep their canonical REFERENCE form, so the
+ * hits are real dependency edges rather than incidental identifier collisions:
+ *   variable "x"        → `var.x`
+ *   output   "x"        → `module.<caller>.x` (regex; same-repo callers only)
+ *   resource "t" "n"    → `t.n`
+ *   data     "t" "n"    → `data.t.n`
+ *   module   "x"        → `module.x`
+ *
+ * All greps are word-bounded (`git grep -w`) so `var.env` doesn't match
+ * `var.environment` and `aws_s3_bucket.this` doesn't match `..._this_backup`.
+ *
+ * The whole thing is best-effort: any failure degrades to "no artifact", never
+ * a failed checkout.
+ */
+
+export type ChangeKind = "added" | "removed";
+
+export interface ChangeLocation {
+  path: string;
+  line: number;
+  kind: ChangeKind;
+}
+
+export interface ChangeImpactAtom {
+  /** the declaration kind, for the artifact heading. */
+  declaration: "variable" | "output" | "resource" | "data" | "module";
+  /** human label, e.g. `var.instance_type` or `aws_s3_bucket.this`. */
+  label: string;
+  /** the pattern grepped (word-bounded) across `*.tf` / `*.tfvars`; also the dedup key. */
+  ref: string;
+  /** when true, `ref` is a POSIX regex (`git grep -E`); otherwise a fixed string (`-F`). */
+  regex?: boolean;
+  /** where in the diff this declaration was touched (first added or removed). */
+  where: ChangeLocation;
+}
+
+export interface GrepHit {
+  path: string;
+  line: number;
+  text: string;
+}
+
+/** a changed file, as returned by the GitHub pulls.listFiles API. */
+export interface ChangedFile {
+  filename: string;
+  patch?: string | undefined;
+  previous_filename?: string | undefined;
+}
+
+// bounds — a supplemental artifact must stay small enough to skim.
+const MAX_ATOMS = 20;
+const MAX_REFS_PER_ATOM = 6;
+const MAX_EXCERPT = 160;
+const MAX_BYTES = 16_000;
+
+const TF_DECL_PATTERNS: Array<{
+  declaration: ChangeImpactAtom["declaration"];
+  re: RegExp;
+  build: (m: RegExpMatchArray) => { label: string; ref: string; regex?: boolean };
+}> = [
+  {
+    declaration: "resource",
+    re: /^resource\s+"([A-Za-z0-9_]+)"\s+"([A-Za-z0-9_-]+)"/,
+    build: (m) => ({ label: `${m[1]}.${m[2]}`, ref: `${m[1]}.${m[2]}` }),
+  },
+  {
+    declaration: "data",
+    re: /^data\s+"([A-Za-z0-9_]+)"\s+"([A-Za-z0-9_-]+)"/,
+    build: (m) => ({ label: `data.${m[1]}.${m[2]}`, ref: `data.${m[1]}.${m[2]}` }),
+  },
+  {
+    declaration: "variable",
+    re: /^variable\s+"([A-Za-z0-9_-]+)"/,
+    build: (m) => ({ label: `var.${m[1]}`, ref: `var.${m[1]}` }),
+  },
+  {
+    declaration: "module",
+    re: /^module\s+"([A-Za-z0-9_-]+)"/,
+    build: (m) => ({ label: `module.${m[1]}`, ref: `module.${m[1]}` }),
+  },
+  {
+    declaration: "output",
+    re: /^output\s+"([A-Za-z0-9_-]+)"/,
+    // an output is consumed as `module.<caller>.<name>`; grep that access form as
+    // a regex rather than the bare `.<name>`, which would match every attribute
+    // access named `<name>` in the tree (for common names like `id`/`arn` that is
+    // pure noise). Precise within a monorepo whose callers live in the same
+    // checkout; cross-repo consumers are invisible to a single-repo grep either way.
+    build: (m) => ({
+      label: `output.${m[1]}`,
+      ref: `module\\.[A-Za-z0-9_-]+\\.${m[1]}`,
+      regex: true,
+    }),
+  },
+];
+
+/** parse one declaration out of a source line, or null. */
+function declarationOf(
+  line: string,
+): { declaration: ChangeImpactAtom["declaration"]; label: string; ref: string; regex?: boolean } | null {
+  const trimmed = line.trimStart();
+  for (const p of TF_DECL_PATTERNS) {
+    const m = trimmed.match(p.re);
+    if (m) return { declaration: p.declaration, ...p.build(m) };
+  }
+  return null;
+}
+
+const locationKey = (path: string, line: number): string => `${path} ${line}`;
+
+/**
+ * Walk each changed file's unified-diff patch, pulling out the HCL declarations
+ * that were added or removed and the set of added-line keys (so grep hits that
+ * land on the PR's own new lines can be excluded — impact means EXISTING code
+ * that references the changed thing).
+ */
+export function extractTerraformAtoms(files: ChangedFile[]): {
+  atoms: ChangeImpactAtom[];
+  addedLines: Set<string>;
+} {
+  const byRef = new Map<string, ChangeImpactAtom>();
+  const addedLines = new Set<string>();
+
+  for (const file of files) {
+    if (!file.patch) continue;
+    // only Terraform declarations matter here.
+    if (!/\.(tf|tfvars)$/.test(file.filename)) continue;
+    let oldLine = 0;
+    let newLine = 0;
+    for (const patchLine of file.patch.split("\n")) {
+      const hunk = patchLine.match(/^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+      if (hunk) {
+        oldLine = Number.parseInt(hunk[1] ?? "0", 10);
+        newLine = Number.parseInt(hunk[2] ?? "0", 10);
+        continue;
+      }
+      if (patchLine.startsWith("+")) {
+        const decl = declarationOf(patchLine.slice(1));
+        const where: ChangeLocation = { path: file.filename, line: newLine, kind: "added" };
+        addedLines.add(locationKey(file.filename, newLine));
+        if (decl && !byRef.has(decl.ref)) byRef.set(decl.ref, { ...decl, where });
+        newLine++;
+      } else if (patchLine.startsWith("-")) {
+        const decl = declarationOf(patchLine.slice(1));
+        const oldPath = file.previous_filename ?? file.filename;
+        if (decl && !byRef.has(decl.ref)) {
+          byRef.set(decl.ref, { ...decl, where: { path: oldPath, line: oldLine, kind: "removed" } });
+        }
+        oldLine++;
+      } else if (!patchLine.startsWith("\\")) {
+        oldLine++;
+        newLine++;
+      }
+    }
+  }
+
+  return { atoms: [...byRef.values()].slice(0, MAX_ATOMS), addedLines };
+}
+
+function excerpt(text: string): string {
+  const t = text.trim();
+  return t.length > MAX_EXCERPT ? `${t.slice(0, MAX_EXCERPT - 1)}…` : t;
+}
+
+/**
+ * Render the artifact from already-collected grep hits. Pure: the caller
+ * supplies the reference hits per atom (via a real `git grep` at runtime, or a
+ * stub in tests). Bounded by MAX_REFS_PER_ATOM and MAX_BYTES.
+ */
+export function renderChangeImpactArtifact(params: {
+  atoms: ChangeImpactAtom[];
+  hitsByRef: Map<string, GrepHit[]>;
+  addedLines: Set<string>;
+  baseSha: string;
+  headSha: string;
+  fileCount: number;
+  lookupError?: string | undefined;
+}): { content: string; atomCount: number; referenceCount: number } {
+  const header = [
+    "# Change impact leads",
+    "",
+    "> Supplemental and explicitly incomplete. Read the authoritative `diffPath` TOC and raw lines first. Absence here is not evidence of no impact.",
+    "",
+    `Scope: base ${params.baseSha.slice(0, 7)}, head ${params.headSha.slice(0, 7)}; ${params.fileCount} changed file(s).`,
+    "Each entry is a Terraform declaration this PR changed, followed by pre-existing references to it elsewhere in the tree (the PR's own new lines are excluded).",
+    "",
+  ];
+  if (params.lookupError) header.push(`Reference lookup unavailable: ${params.lookupError}.`, "");
+
+  let content = `${header.join("\n")}`;
+  let atomCount = 0;
+  let referenceCount = 0;
+
+  for (const atom of params.atoms) {
+    const hits = (params.hitsByRef.get(atom.ref) ?? []).filter(
+      (h) => !params.addedLines.has(locationKey(h.path, h.line)),
+    );
+    if (hits.length === 0) continue;
+    const shown = hits.slice(0, MAX_REFS_PER_ATOM);
+    const note =
+      hits.length > shown.length
+        ? `${hits.length} reference(s); first ${shown.length} shown.`
+        : `${hits.length} reference(s).`;
+    const block = [
+      "",
+      `## \`${atom.label}\` (${atom.declaration})`,
+      "",
+      `Changed at: ${atom.where.kind} \`${atom.where.path}\`:${atom.where.line}`,
+      `References: ${note}`,
+      "",
+      ...shown.map((h) => `- \`${h.path}\`:${h.line} — ${excerpt(h.text)}`),
+      "",
+    ].join("\n");
+    if (Buffer.byteLength(content + block) > MAX_BYTES) break;
+    content += block;
+    atomCount++;
+    referenceCount += hits.length;
+  }
+
+  if (atomCount === 0) {
+    const empty = "\nNo pre-existing references found for the changed declarations. This is not evidence of no wider impact.\n";
+    if (Buffer.byteLength(content + empty) <= MAX_BYTES) content += empty;
+  }
+
+  return { content: content.endsWith("\n") ? content : `${content}\n`, atomCount, referenceCount };
+}
+
+// bound the per-atom grep parse so a heavily-referenced module can't balloon
+// memory; the renderer only shows MAX_REFS_PER_ATOM anyway but reports the count.
+const MAX_HITS_PER_ATOM = 200;
+
+/** parse `git grep -n` porcelain (`path:line:text`) into hits. */
+export function parseGrepHits(output: string): GrepHit[] {
+  const hits: GrepHit[] = [];
+  for (const raw of output.split("\n")) {
+    if (!raw) continue;
+    const m = raw.match(/^(.*?):(\d+):(.*)$/);
+    if (!m) continue;
+    const [, path, lineStr, text] = m;
+    if (path === undefined || lineStr === undefined) continue;
+    hits.push({ path, line: Number.parseInt(lineStr, 10), text: text ?? "" });
+    if (hits.length >= MAX_HITS_PER_ATOM) break;
+  }
+  return hits;
+}
+
+/**
+ * Runtime entry point: extract the changed declarations, grep the checked-out
+ * head for pre-existing references to each, and write the artifact to tmpdir.
+ * Returns null when there's nothing worth writing (no TF declarations changed).
+ * Callers treat a thrown error as "no artifact" — this must never fail checkout.
+ */
+export function createChangeImpactArtifact(params: {
+  files: ChangedFile[];
+  tmpdir: string;
+  pullNumber: number;
+  baseSha: string;
+  headSha: string;
+}): { path: string; atomCount: number; referenceCount: number; bytes: number } | null {
+  const { atoms, addedLines } = extractTerraformAtoms(params.files);
+  if (atoms.length === 0) return null;
+
+  const hitsByRef = new Map<string, GrepHit[]>();
+  let lookupError: string | undefined;
+  for (const atom of atoms) {
+    let status = 0;
+    // word-bounded, tracked-files-only, skip-binary grep of the checked-out head.
+    // `-w` keeps `var.env` from matching `var.environment`; `-E`/`-F` per atom
+    // (outputs grep a `module.<caller>.<name>` regex, the rest fixed strings).
+    // exit 1 = no matches (onError swallows it → ""); exit >1 = a real failure.
+    const out = $(
+      "git",
+      [
+        "grep",
+        "-n",
+        atom.regex ? "-E" : "-F",
+        "-w",
+        "-I",
+        "--no-color",
+        "-e",
+        atom.ref,
+        "--",
+        "*.tf",
+        "*.tfvars",
+      ],
+      { log: false, onError: (r) => (status = r.status) },
+    );
+    if (status > 1) {
+      lookupError = `git grep exit ${status}`;
+      continue;
+    }
+    hitsByRef.set(atom.ref, parseGrepHits(out));
+  }
+
+  const artifact = renderChangeImpactArtifact({
+    atoms,
+    hitsByRef,
+    addedLines,
+    baseSha: params.baseSha,
+    headSha: params.headSha,
+    fileCount: params.files.length,
+    lookupError,
+  });
+  const path = join(params.tmpdir, `pr-${params.pullNumber}-${params.headSha.slice(0, 7)}-impact.md`);
+  writeFileSync(path, artifact.content);
+  log.debug(
+    `» change impact: ${artifact.atomCount} atom(s), ${artifact.referenceCount} reference(s) → ${path}`,
+  );
+  return {
+    path,
+    atomCount: artifact.atomCount,
+    referenceCount: artifact.referenceCount,
+    bytes: Buffer.byteLength(artifact.content),
+  };
+}

package/src/utils/claudeSubscription.ts

@@ -0,0 +1,93 @@
+import { resolveModelSlug } from "#app/models";
+
+/**
+ * identity block Anthropic's OAuth gate validates on `/v1/messages` calls
+ * authenticated with a Claude Code OAuth token. haiku is currently exempt
+ * but sending it costs nothing and survives the exemption being removed.
+ */
+const CLAUDE_CODE_IDENTITY = "You are Claude Code, Anthropic's official CLI for Claude.";
+
+// fallback probe model for runs with no explicit model (claude-code picks its
+// own default there, so per-model accuracy is moot — only whether the
+// subscription answers at all). registry-resolved so a catalog bump keeps
+// the id fresh.
+const fallbackResolve = resolveModelSlug("anthropic/claude-haiku");
+if (!fallbackResolve) {
+  throw new Error("claudeSubscription preflight: anthropic/claude-haiku missing from registry");
+}
+const FALLBACK_PROBE_MODEL = fallbackResolve.slice(fallbackResolve.indexOf("/") + 1);
+
+export type SubscriptionPreflight = { usable: true } | { usable: false; reason: string };
+
+/**
+ * preflight a Claude subscription OAuth token (`CLAUDE_CODE_OAUTH_TOKEN`)
+ * with a 1-token Messages call, so the agent can fall back to
+ * `ANTHROPIC_API_KEY` when the subscription is exhausted or revoked instead
+ * of failing the whole run at its first model call. rides the same de-facto
+ * OAuth surface Claude Code itself uses: Bearer auth + the
+ * `claude-code-20250219,oauth-2025-04-20` betas + the identity system prompt.
+ *
+ * probes the run's own model when known — subscription limits can be
+ * per-model ("You've hit your Opus limit"), so a cheaper stand-in could pass
+ * preflight and still leave the run dead on arrival.
+ *
+ * fail-open by design: only 401 (revoked/expired token) and 429
+ * (session/weekly/per-model limit) mark the token unusable. network errors,
+ * 5xx, and request-shape drift (400) all keep today's subscription-first
+ * behavior, so the preflight can never fail a run that would have worked —
+ * the worst wrong answer is a run that bills the API key instead of the
+ * subscription.
+ */
+export async function preflightClaudeSubscription(params: {
+  token: string;
+  /** bare Anthropic model id the run will use (e.g. "claude-fable-5") */
+  model: string | undefined;
+}): Promise<SubscriptionPreflight> {
+  let res: Response;
+  try {
+    res = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${params.token}`,
+        "anthropic-beta": "claude-code-20250219,oauth-2025-04-20",
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json",
+        "x-app": "cli",
+      },
+      body: JSON.stringify({
+        model: params.model ?? FALLBACK_PROBE_MODEL,
+        max_tokens: 1,
+        system: CLAUDE_CODE_IDENTITY,
+        messages: [{ role: "user", content: "ok" }],
+      }),
+      signal: AbortSignal.timeout(10_000),
+    });
+  } catch {
+    // network failure / timeout says nothing about the credential
+    return { usable: true };
+  }
+  if (res.status !== 401 && res.status !== 429) return { usable: true };
+  const body = await res.text().catch(() => "");
+  return { usable: false, reason: `${res.status}: ${extractApiErrorMessage(body)}` };
+}
+
+/** pull `error.message` out of an Anthropic error payload, else a raw excerpt */
+function extractApiErrorMessage(body: string): string {
+  try {
+    const parsed: unknown = JSON.parse(body);
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      "error" in parsed &&
+      typeof parsed.error === "object" &&
+      parsed.error !== null &&
+      "message" in parsed.error &&
+      typeof parsed.error.message === "string"
+    ) {
+      return parsed.error.message;
+    }
+  } catch {
+    // not json — fall through to the raw excerpt
+  }
+  return body.slice(0, 200);
+}