@kal-elsam/kairo-runtime 0.21.0 → 0.22.1

package/CHANGELOG.md

@@ -5,6 +5,49 @@ Historical entries below may reference the legacy `@kal-elsam/harness` package n
 
 ## Unreleased
 
+## 0.22.1 — 2026-09-18 (Kairo Runtime)
+
+Patch release.
+
+### Fixed
+
+- Execution links no longer hardcode `provider: "claude"` on every
+  write regardless of which real adapter (Codex, Cursor, OpenCode Go,
+  Claude) actually executed the task. `provider` now mirrors the
+  link's own real `agentId`, matching what `service.js`'s
+  `executionFor` already treated as ground truth at read time. The
+  cockpit reads this field directly for its provider display, so every
+  task's shown execution provider had always silently said "claude"
+  regardless of what actually ran it.
+
+## 0.22.0 — 2026-09-18 (Kairo Runtime)
+
+Minor release. Promotes OpenCode Go to a real automatic execution
+provider.
+
+### Changed
+
+- OpenCode Go's accessMode flips from "manual" to "automatic" — its own
+  dedicated `/zen/go/*` gateway is a real, separate endpoint from Zen's,
+  resolving the earlier billing-attribution concern for Go specifically.
+  OpenCode Zen keeps its own real, unresolved Go/Zen billing-attribution
+  gap and stays manual.
+- Adds an adapter-declared idle timeout (60s for OpenCode, reset on
+  every real output chunk — never an absolute one, so a real
+  long-running task is never killed just for taking a while) as the
+  safety net for a live-reproduced CLI hang: a genuine hang now becomes
+  a bounded, detectable failure instead of an indefinite one.
+
+### Fixed
+
+- Three previously-latent bugs, never exercised since Go was never
+  launchable before: `resolveExecutionAdapter` threw for
+  "opencode-go"/"opencode-zen"; real task execution launched with the
+  catalog's bare model id instead of the real "opencode-go/<id>"
+  form the CLI needs to route deterministically; the usage/quota
+  tracking store rejected "opencode-go"/"opencode-zen" as valid
+  providers despite their genuinely separate budgets.
+
 ## 0.21.0 — 2026-09-18 (Kairo Runtime)
 
 Patch-level polish. When a role resolves to a manual-only provider

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Pi, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",

package/src/global/architect/architect-store.js

@@ -307,23 +307,41 @@ export async function readExecutionLink(projectRoot, taskId) {
   const stat = await statOrNull(paths.executionPath);
   if (!stat) return null;
   const link = JSON.parse(await readFile(paths.executionPath, "utf8"));
+  // `provider` is real, structural validation only (a non-empty real
+  // string) — never a single hardcoded value. PROJECT TEAM can route a
+  // real task to any real adapter (Codex, Claude, Cursor, OpenCode Go),
+  // and a legacy artifact from before that existed still carries "claude"
+  // for real, so this must accept every real one honestly, never lie
+  // by forcing them all to read back as "claude".
   if (link?.schema !== EXECUTION_SCHEMA || link?.taskId !== taskId
-    || !/^run_[a-z0-9_]+$/.test(link?.runId ?? "") || link?.provider !== "claude") {
+    || !/^run_[a-z0-9_]+$/.test(link?.runId ?? "") || typeof link?.provider !== "string" || link.provider.length === 0) {
     throw new Error(`Invalid execution artifact: ${taskId}`);
   }
   return link;
 }
 
+/**
+ * `provider` always mirrors the link's own real `agentId` — the field a
+ * real caller (executePlan) actually sets, and the one PROJECT TEAM's own
+ * routing decision already named. Never a fabricated or hardcoded value;
+ * a legacy caller that never set agentId falls back to "claude" only
+ * because that's genuinely what every execution WAS before PROJECT TEAM's
+ * multi-provider routing existed — never a guess for real, current data.
+ */
+function resolveExecutionProvider(link) {
+  return link?.agentId ?? link?.provider ?? "claude";
+}
+
 export async function writeExecutionLink(projectRoot, taskId, link) {
   const paths = await prepareTaskDirectory(projectRoot, taskId);
-  const value = { ...link, schema: EXECUTION_SCHEMA, taskId, provider: "claude" };
+  const value = { ...link, schema: EXECUTION_SCHEMA, taskId, provider: resolveExecutionProvider(link) };
   await writeAtomicJson(paths.executionPath, value, { createExclusive: true });
   return value;
 }
 
 export async function updateExecutionLink(projectRoot, taskId, link) {
   const paths = await prepareTaskDirectory(projectRoot, taskId);
-  const value = { ...link, schema: EXECUTION_SCHEMA, taskId, provider: "claude" };
+  const value = { ...link, schema: EXECUTION_SCHEMA, taskId, provider: resolveExecutionProvider(link) };
   await writeAtomicJson(paths.executionPath, value);
   return value;
 }

package/src/global/conversation/service.js

@@ -44,6 +44,7 @@ import {
   buildEfficientTeam, scoreAvailableModels, summarizeCatalogCoverage
 } from "../intelligence/model-intelligence.js";
 import { buildAutomaticExecutionPool, buildCompleteCandidateCatalog, buildRecommendationPool } from "../intelligence/model-candidate-catalog.js";
+import { toRuntimeModelRef } from "../intelligence/transport-registry.js";
 import { createCapabilityRegistry } from "../intelligence/model-capability-registry.js";
 import { ingestArtificialAnalysisEvidence, ingestHuggingFaceLeaderboardEvidence } from "../intelligence/model-capability-registry-sources.js";
 import { ingestOfficialSnapshotEvidence } from "../intelligence/official-benchmark-snapshots.js";
@@ -1024,7 +1025,15 @@ export function createConversationService(deps = {}) {
         throw new Error(`Cannot execute "${taskId}": the real project team state changed since this was confirmed (strategy, eligibility, or override) — request a new preview and confirm again.`);
       }
       const resolvedAgentId = resolvedCandidate.adapterId;
-      const resolvedModel = resolvedCandidate.modelId;
+      // OpenCode Go/Zen's real catalog stores bare model ids (see
+      // opencode-models.js's normalizeModel) — the CLI needs the real,
+      // fully-qualified "opencode-go/<id>" (or "opencode/<id>" for Zen)
+      // ref to deterministically route to the intended product; a bare id
+      // is exactly the ambiguity Kairo must never risk. Every other
+      // adapter's modelId is already launch-ready as-is.
+      const resolvedModel = resolvedAgentId === "opencode-go" || resolvedAgentId === "opencode-zen"
+        ? toRuntimeModelRef(resolvedAgentId === "opencode-go" ? "go" : "zen", resolvedCandidate.modelId)
+        : resolvedCandidate.modelId;
 
       const runId = newRunId();
       const createdAt = new Date().toISOString();

package/src/global/intelligence/execution-router.js

@@ -174,15 +174,11 @@ export function checkCandidate(adapterId, { adapters, codexUsage, claudeUsage, o
   const adapter = findAdapter(adapterId, adapters);
   if (!adapter) return { ok: false, reason: `${adapterId}: no adapter found` };
   if (!adapter.available) return { ok: false, reason: adapter.reason ?? `${adapterId}: not available` };
-  // "launchable" means safe for Kairo to invoke programmatically — not the
-  // bar a manual recommendation needs. OpenCode Go alone keeps the
-  // exemption: real availability is enough to recommend it, even though
-  // Kairo can't safely auto-execute through it yet (unresolved Go/Zen
-  // billing-attribution gap — see opencode.js). Cursor no longer needs
-  // this exemption — its real launchability is judged the same way for
-  // both recommendation and execution now.
-  const launchableRequired = requireLaunchable || adapterId !== "opencode-go";
-  if (launchableRequired && !adapter.launchable) return { ok: false, reason: adapter.reason ?? `${adapterId}: not launchable yet` };
+  // "launchable" means safe for Kairo to invoke programmatically — every
+  // real adapter is now judged the same way for both recommendation and
+  // execution; no adapter keeps a special exemption anymore (Cursor and
+  // OpenCode Go both dropped theirs once their real adapters proved out).
+  if (!adapter.launchable) return { ok: false, reason: adapter.reason ?? `${adapterId}: not launchable yet` };
 
   if (adapterId === "codex") {
     const left = remainingPercent(codexUsage);

package/src/global/intelligence/model-candidate-catalog.js

@@ -39,7 +39,7 @@ import { matchArtificialAnalysisScore } from "./model-intelligence.js";
  * @property {string} modelName - human-readable clean name, with real effort/context/privacy variant tokens stripped (see stripDisplayVariant). Never invented — always derived from the provider's own real displayName.
  * @property {string} rawDisplayName - the provider's own displayName, completely unmodified — the real evidence modelName was derived from. Whatever stripDisplayVariant peeled off (effort/context/privacy tokens) to produce modelName is still visible here, never a separate field: /models --evidence's own "technical detail" is just this string.
  * @property {string} adapterId - "codex" | "claude" | "cursor" | "opencode-go".
- * @property {"automatic"|"manual"} accessMode - whether Kairo can actually launch this candidate itself right now, or whether it's a real, recommendable option the human runs manually (Cursor's own "auto" router model always; OpenCode Go until its own empirical automatic-execution proof lands — see this module's own doc). Named Cursor models are automatic.
+ * @property {"automatic"|"manual"} accessMode - whether Kairo can actually launch this candidate itself right now, or whether it's a real, recommendable option the human runs manually (Cursor's own "auto" router model always; OpenCode Zen always, pending its own Go/Zen billing-attribution proof — see this module's own doc). Named Cursor and OpenCode Go models are automatic.
  * @property {"scored"|"partial"|"unscored"} evidenceStatus - "scored": AA matched this exact model AND reports at least one of intelligenceIndex/codingIndex. "partial": AA matched it but both composite indices are null (real match, thin evidence). "unscored": no confident AA match at all. Never role-specific — see this module's own doc for why.
  * @property {string|null} lineageKey - real, recognized model family/lineage (see LINEAGE_PARSERS) — null when the modelId doesn't match any recognized, conservative pattern. Never guessed.
  * @property {number|null} generation - a real, comparable version number within that lineage — null whenever lineageKey is null.
@@ -281,20 +281,27 @@ function applyLifecycle(catalog) {
 // Whether Kairo can actually launch a candidate itself right now, per
 // adapter — real, current state (execution-adapters/index.js's own
 // `launchable` flags, intelligence/execution-router.js's checkCandidate),
-// not a guess. OpenCode Go stays "manual" until the real empirical
-// automatic-execution proof this session's plan calls for
-// (`opencode run -m opencode-go/<model>`, verifying real provider
-// attribution and Go-only consumption) actually runs and passes — see
-// this module's own doc. Cursor is "automatic": its own execution
-// adapter (execution-adapters/cursor.js) already builds a real,
-// auditable non-interactive launch (`cursor-agent -p --output-format
-// stream-json`) and parses its structured event stream, the exact same
-// shape as Codex/Claude — Cursor's own docs explicitly support this
-// (headless/CI use is an intended, documented capability, not a hack).
-// The earlier "permanent manual" policy predated this adapter being
-// finished and had no technical or billing reason behind it (unlike
-// OpenCode Go's real, confirmed Go/Zen billing-attribution gap above).
-const ACCESS_MODE_BY_ADAPTER = { codex: "automatic", claude: "automatic", cursor: "automatic", "opencode-go": "manual" };
+// not a guess. Cursor is "automatic": its own execution adapter
+// (execution-adapters/cursor.js) already builds a real, auditable
+// non-interactive launch (`cursor-agent -p --output-format stream-json`)
+// and parses its structured event stream, the exact same shape as
+// Codex/Claude — Cursor's own docs explicitly support this (headless/CI
+// use is an intended, documented capability, not a hack).
+//
+// OpenCode Go is "automatic" too now, but with a real, confirmed caveat:
+// a live reproduction (2026-09-18, against a real account) found the
+// `opencode` CLI genuinely hangs with zero output for some real Go
+// models — not a stale finding. What makes this safe to flip anyway is
+// the real idle timeout the execution adapter itself now declares
+// (execution-adapters/opencode.js's OPENCODE_IDLE_TIMEOUT_MS,
+// run-supervisor.js resets it on every real chunk) — a genuine hang gets
+// converted into a real FAILED run within a bounded, known time instead
+// of hanging forever, which is exactly what the human's own explicit
+// decision requires: try Go, and if it's not OK, automatically move to
+// the next real available model. OpenCode Zen stays "manual" — the
+// real, confirmed Go/Zen billing-attribution gap (see this module's own
+// doc above) is unrelated to this and still unresolved.
+const ACCESS_MODE_BY_ADAPTER = { codex: "automatic", claude: "automatic", cursor: "automatic", "opencode-go": "automatic" };
 
 function resolveAccessMode(adapterId, modelId) {
   // Cursor's own "auto" router picks whichever underlying model it wants
@@ -447,7 +454,7 @@ export function buildRecommendationPool(scoredAll, completeCatalog) {
  * The Automatic Execution Pool: the subset of the Recommendation Pool
  * Kairo can actually launch itself, right now — real routing's own
  * candidate source, never QUALITY/EFFICIENT TEAM's. Requires BOTH a real
- * accessMode of "automatic" (OpenCode Go is currently manual, and
+ * accessMode of "automatic" (OpenCode Zen is currently manual, and
  * Cursor's own "auto" router model stays manual — see
  * ModelCandidateIdentity's own doc) AND real,
  * current eligibility (adapter availability, quota, launchability — the

package/src/global/observability/codex-models.js

@@ -89,7 +89,7 @@ export async function readCodexModels({
     child.once?.("close", () => { if (!finished) finish(unknown("codex app-server closed before model list")); });
 
     writeRequest(child, 1, "initialize", {
-      clientInfo: { name: "kairo", title: "Kairo", version: "0.21.0" },
+      clientInfo: { name: "kairo", title: "Kairo", version: "0.22.1" },
       capabilities: {}
     });
   });

package/src/global/observability/codex-usage.js

@@ -151,7 +151,7 @@ export async function readCodexUsage({
     child.once?.("close", () => { if (!finished) finish(unknown("codex app-server closed before rate limits")); });
 
     writeRequest(child, 1, "initialize", {
-      clientInfo: { name: "kairo", title: "Kairo", version: "0.21.0" },
+      clientInfo: { name: "kairo", title: "Kairo", version: "0.22.1" },
       capabilities: {}
     });
   });

package/src/global/runtime/execution-adapters/create-execution-adapter.js

@@ -12,12 +12,20 @@ export function createExecutionAdapter({
   parseEventLine = null,
   checkAvailability = null,
   launchable = null,
-  preflight = null
+  preflight = null,
+  idleTimeoutMs = null
 }) {
   return {
     id,
     label,
     executable,
+    // The real, adapter-declared "no output for this long means genuinely
+    // hung, not just working" threshold (run-supervisor.js resets this on
+    // every stdout/stderr chunk, so a real long-running task is never
+    // killed just for taking a while — only real silence trips it). null
+    // (the default) means this adapter is trusted not to hang; only an
+    // adapter with a real, observed hanging failure mode declares one.
+    idleTimeoutMs,
     capabilities: {
       structuredEvents: false,
       tokens: false,

package/src/global/runtime/execution-adapters/index.js

@@ -12,8 +12,19 @@ export function listExecutionAdapters() {
   return [...EXECUTION_ADAPTERS];
 }
 
+/**
+ * Resolves the real adapter object for an id — "opencode-go"/"opencode-zen"
+ * both share the single real "opencode" adapter object (one executable,
+ * one launch/parse contract; the Go/Zen split is a routing/eligibility
+ * distinction, decided by execution-router.js's checkCandidate, never a
+ * separate adapter object), the same prefix rule execution-router.js's own
+ * findAdapter already uses. Never silently falls through for an unrelated
+ * unknown id — only an id that is exactly "opencode" or starts with
+ * "opencode-" maps this way.
+ */
 export function resolveExecutionAdapter(id) {
-  const adapter = EXECUTION_ADAPTERS.find((candidate) => candidate.id === id);
+  const baseId = id === "opencode" || id.startsWith("opencode-") ? "opencode" : id;
+  const adapter = EXECUTION_ADAPTERS.find((candidate) => candidate.id === baseId);
   if (!adapter) {
     throw new Error(`Unknown execution adapter "${id}". Use ${EXECUTION_ADAPTER_IDS.join(", ")}.`);
   }

package/src/global/runtime/execution-adapters/opencode.js

@@ -3,6 +3,17 @@ import { isExecutableAvailable } from "../../cli-probe.js";
 
 const EXECUTABLE = "opencode";
 
+// Real, reproduced failure mode (2026-09-18): `opencode run -m
+// opencode-go/<model>` genuinely hangs with ZERO stdout/stderr output for
+// several real models, confirmed live against a real account — not a
+// stale finding. Some other real models fail fast and cleanly instead
+// (e.g. a real 403 region-lock error came back instantly). Since a real,
+// legitimate task can genuinely run for minutes while still producing
+// real output, this is an IDLE timeout (reset on every real chunk, see
+// run-supervisor.js), never an absolute one — only genuine silence this
+// long trips it.
+export const OPENCODE_IDLE_TIMEOUT_MS = 60_000;
+
 // Verified live (`opencode run --format json`) against a real account: the
 // CLI genuinely emits parseable NDJSON events — step_start/step_finish,
 // tool_use (with real tool name + status), text, and error — including
@@ -10,19 +21,18 @@ const EXECUTABLE = "opencode";
 // step_finish. That earlier "does not emit auditable structured events"
 // claim was wrong; structuredEvents below is now an accurate capability.
 //
-// It stays `launchable: false` anyway, for a different, harder reason:
-// this adapter is shared by both OpenCode Go (subscription, $10/mo) and
-// OpenCode Zen (PAYG) — same `opencode` executable, same event shapes,
-// no field in any event that names which product tier actually served
-// the request. A live invocation with `-m opencode/<id>` for a model that
-// exists on BOTH tiers was confirmed to be ambiguous — no way to prove
-// after the fact whether it ran on Go or silently billed against Zen. A
-// second invocation with the Go-specific `opencode-go/<id>` prefix simply
-// hung. Per explicit decision: Kairo must not route real tasks through
-// this adapter until it can prove, from the run's own evidence, both (1)
-// the effective provider actually used was opencode-go, and (2) Zen was
-// not touched. Until that receipt-level proof exists, this stays blocked
-// — no more paid trial invocations to "just check" this again.
+// `launchable: true` now — for Go specifically. This adapter is shared by
+// both OpenCode Go (subscription, $10/mo) and OpenCode Zen (PAYG); the
+// real, unresolved billing-attribution gap between them (no per-event way
+// to prove which tier served a request) is still real, but
+// execution-router.js's checkCandidate refuses "opencode-zen" outright
+// regardless of this flag, so this flag only ever matters for
+// "opencode-go" in practice — and for Go, that gap doesn't apply (its
+// own dedicated `/zen/go/*` endpoint is a real, separate gateway, see
+// model-candidate-catalog.js's own doc). The real remaining risk was a
+// live-confirmed hang for some Go models, not billing — mitigated by this
+// adapter's own idleTimeoutMs (see above) converting a genuine hang into
+// a bounded real failure instead of an indefinite one.
 function checkOpencodeAvailability(context = {}) {
   const available = isExecutableAvailable(EXECUTABLE, { env: context.env ?? process.env });
   if (!available) {
@@ -32,8 +42,8 @@ function checkOpencodeAvailability(context = {}) {
     };
   }
   return {
-    available: true, compatible: true, launchable: false,
-    reason: "OpenCode Go/Zen share one executable with no per-event way to prove which product tier actually served a run — blocked until that provider-isolation evidence exists."
+    available: true, compatible: true, launchable: true,
+    reason: null
   };
 }
 
@@ -100,5 +110,6 @@ export default createExecutionAdapter({
   },
   checkAvailability: checkOpencodeAvailability,
   buildLaunch: buildOpencodeLaunch,
-  parseEventLine: parseOpencodeEventLine
+  parseEventLine: parseOpencodeEventLine,
+  idleTimeoutMs: OPENCODE_IDLE_TIMEOUT_MS
 });

package/src/global/runtime/run-supervisor.js

@@ -78,6 +78,13 @@ export async function supervisePreparedRun({
 }) {
   const handoff = await consumeRunHandoff(homeDir, runId);
   const adapter = resolveAdapterImpl(handoff.agentId);
+  // A caller-supplied timeoutMs always wins; otherwise the adapter's own
+  // declared idleTimeoutMs applies automatically — this is the ONLY path
+  // real detached runs (the production `wait: false` case) ever take,
+  // since the handoff itself never carries a caller timeoutMs (see
+  // run-manager.js's writeRunHandoff), so an adapter-level default is the
+  // only way a real detached opencode-go run ever gets one at all.
+  const effectiveTimeoutMs = timeoutMs ?? adapter.idleTimeoutMs ?? null;
   let metadata = await readRunState(homeDir, runId);
 
   if (!metadata) {
@@ -310,9 +317,12 @@ export async function supervisePreparedRun({
 
           const failed = exitCode !== 0;
           const nextState = failed ? RUN_STATES.FAILED : RUN_STATES.COMPLETED;
+          const failureReason = timedOutByIdle
+            ? `No real output for ${effectiveTimeoutMs}ms (idle timeout) — likely hung, not a normal completion`
+            : `Process exited with code ${exitCode}`;
           metadata = transitionRunState(metadata, nextState, {
             exitCode,
-            error: failed ? `Process exited with code ${exitCode}` : null
+            error: failed ? failureReason : null
           });
           await writeRunState(homeDir, metadata);
           await appendRunEvent(homeDir, createRunEvent({
@@ -341,7 +351,23 @@ export async function supervisePreparedRun({
     });
   });
 
+  // An IDLE timeout, never an absolute one: a real, legitimate task can run
+  // for many minutes while still producing real output, so the timer is
+  // rearmed on every real stdout/stderr chunk (see opencode.js's own
+  // idleTimeoutMs doc — this only ever exists to catch genuine silence,
+  // like the real hang confirmed there, not to cap a working run's length).
+  let timedOutByIdle = false;
+  const armIdleTimeout = () => {
+    if (effectiveTimeoutMs == null || effectiveTimeoutMs <= 0) return;
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+    timeoutHandle = setTimeout(() => {
+      timedOutByIdle = true;
+      child.kill("SIGTERM");
+    }, effectiveTimeoutMs);
+  };
+
   child.stdout.on("data", (chunk) => {
+    armIdleTimeout();
     enqueue(async () => {
       stdoutBuffer += chunk.toString();
       stdoutBuffer = await flushBuffer(stdoutBuffer, "stdout");
@@ -349,17 +375,14 @@ export async function supervisePreparedRun({
   });
 
   child.stderr.on("data", (chunk) => {
+    armIdleTimeout();
     enqueue(async () => {
       stderrBuffer += chunk.toString();
       stderrBuffer = await flushBuffer(stderrBuffer, "stderr");
     });
   });
 
-  if (timeoutMs != null && timeoutMs > 0) {
-    timeoutHandle = setTimeout(() => {
-      child.kill("SIGTERM");
-    }, timeoutMs);
-  }
+  armIdleTimeout();
 
   void serializeStateWrite(async () => {
     metadata = {

package/src/global/runtime/usage-store.js

@@ -7,6 +7,17 @@ import { writeAtomicJson } from "./write-atomic-json.js";
 
 const writeLocks = new Map();
 
+// OpenCode Go and Zen share a single real execution adapter object (one
+// executable, one launch/parse contract — see
+// execution-adapters/index.js's own resolveExecutionAdapter doc), but
+// they are NOT the same thing for usage/budget tracking: Go is a flat
+// $10/mo subscription with its own weekly/monthly quota, Zen is pay-per-
+// token with its own real balance — genuinely separate budgets that must
+// never share one usage record. So this whitelist is deliberately wider
+// than EXECUTION_ADAPTER_IDS, not a mirror of it.
+const EXTRA_USAGE_PROVIDER_IDS = ["opencode-go", "opencode-zen"];
+const VALID_USAGE_PROVIDER_IDS = [...EXECUTION_ADAPTER_IDS, ...EXTRA_USAGE_PROVIDER_IDS];
+
 export function getUsageDir(homeDir) {
   return harnessHomePaths(homeDir).usageDir;
 }
@@ -15,13 +26,12 @@ export function getUsageDir(homeDir) {
  * The one real boundary a provider id gets validated at before it's ever
  * used to build a path — the same defense-in-depth role
  * assertWorktreeId/assertTaskId already play elsewhere. Provider ids are a
- * real, closed list (the same one execution-adapters/index.js resolves
- * against), never a free-form string, so an unknown one is always a bug
- * to surface loudly rather than a path to silently sanitize.
+ * real, closed list, never a free-form string, so an unknown one is
+ * always a bug to surface loudly rather than a path to silently sanitize.
  */
 function usagePath(homeDir, provider) {
-  if (!EXECUTION_ADAPTER_IDS.includes(provider)) {
-    throw new Error(`Unknown provider "${provider}" for usage tracking. Use ${EXECUTION_ADAPTER_IDS.join(", ")}.`);
+  if (!VALID_USAGE_PROVIDER_IDS.includes(provider)) {
+    throw new Error(`Unknown provider "${provider}" for usage tracking. Use ${VALID_USAGE_PROVIDER_IDS.join(", ")}.`);
   }
   return join(getUsageDir(homeDir), `${provider}.json`);
 }
@@ -60,7 +70,7 @@ export async function listProviderUsage(homeDir) {
   for (const entry of entries) {
     if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
     const provider = entry.name.slice(0, -".json".length);
-    if (!EXECUTION_ADAPTER_IDS.includes(provider)) continue;
+    if (!VALID_USAGE_PROVIDER_IDS.includes(provider)) continue;
     const record = await readProviderUsage(homeDir, provider);
     if (record) records.push(record);
   }