@kal-elsam/kairo-runtime 0.26.1 → 0.27.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ Historical entries below may reference the legacy `@kal-elsam/harness` package n
 
 ## Unreleased
 
+## 0.27.0 — 2026-09-19 (Kairo Runtime)
+
+Minor release. Claude model entitlement now gates PROJECT TEAM pools and routes.
+
+### Changed
+
+- Denied Claude models (e.g. Fable 5.1 on Pro with `credits_required`) are
+  excluded from both the recommendation and automatic execution pools —
+  orthogonal to `accessMode`, so a denied model is never mislabeled "manual".
+- Unverified Claude models stay recommendable but are never auto-launchable.
+- Live entitlement also blocks a persisted project-team assignment whose
+  account access is denied or unverified; `snapshot()` still only reads the
+  disk cache (never probes).
+
 ## 0.26.1 — 2026-09-19 (Kairo Runtime)
 
 Patch release. Claude model entitlement probe + cache (no routing change yet).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "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/conversation/bootstrap-analyzer-adapters.js

@@ -39,6 +39,7 @@ import {
 } from "./codex-sandbox.js";
 import { verifyClaudeSubscriptionAuth as defaultVerifyClaudeSubscriptionAuth } from "../runtime/execution-adapters/claude.js";
 import { readClaudeModels as defaultReadClaudeModels } from "../observability/claude-models.js";
+import { ENTITLEMENT } from "../observability/claude-model-entitlement.js";
 import { readCursorModels as defaultReadCursorModels } from "../observability/cursor-models.js";
 import { probeCursorAuth as defaultProbeCursorAuth } from "../observability/cursor-auth.js";
 import {
@@ -114,6 +115,18 @@ export function createClaudeBootstrapAnalyzerAdapter({ modelId, deps = {} } = {}
         if (!known) {
           return { eligible: false, reason: `"${modelId}" is not in Claude's documented model catalog.`, isolation: "unverified", canaryTested: false };
         }
+        // Live per-model entitlement (when the caller supplies it) — denied
+        // siblings fail with the real CLI reason, never a silent pass after
+        // the documented-catalog check. Missing map/key does not invent denial.
+        const entitlement = deps.modelEntitlement?.[modelId];
+        if (entitlement?.status === ENTITLEMENT.DENIED) {
+          return {
+            eligible: false,
+            reason: entitlement.reason ?? `"${modelId}" is denied by Claude account entitlement.`,
+            isolation: "unverified",
+            canaryTested: false
+          };
+        }
       }
       return { eligible: true, isolation: "restricted", canaryTested: true };
     },

package/src/global/conversation/project-router.js

@@ -19,6 +19,8 @@
 // persisted, not recomputed) — this module only checks whether that
 // persisted candidate is STILL real-eligible right now.
 
+import { ENTITLEMENT } from "../observability/claude-model-entitlement.js";
+
 /**
  * Whether Kairo can launch an automatic run against this real candidate
  * right now — reads model-candidate-catalog.js's own `accessMode`
@@ -39,16 +41,46 @@ export const PROJECT_ROUTE_DECISION = {
   WAIT_FOR_PROJECT_TEAM: "WAIT_FOR_PROJECT_TEAM"
 };
 
+const ROUTABLE_ENTITLEMENTS = new Set([ENTITLEMENT.ALLOWED, ENTITLEMENT.NOT_APPLICABLE]);
+
 function assignmentRef(model, assignmentSource) {
   if (!model) return null;
   return { provider: model.adapterId, model, assignmentSource };
 }
 
-/** A real candidate is only ever offered as `suggestedAlternative` when it's currently automatically-executable — the same bar ROUTED itself requires. Never suggests another manual-only or currently-ineligible provider; honestly null instead. */
-function routableAlternative(model, eligibility) {
+/**
+ * Live entitlement gate: only when `modelEntitlement[modelId]` is PRESENT
+ * and status is denied or unverified. Missing key (empty `{}`) keeps
+ * existing callers/tests green — no gate.
+ * @param {object} model
+ * @param {Record<string, {status?: string, reason?: string|null}>} modelEntitlement
+ * @returns {{status: string, reason: string|null}|null}
+ */
+function blockingEntitlement(model, modelEntitlement) {
+  const entry = modelEntitlement?.[model?.modelId];
+  if (!entry || typeof entry !== "object") return null;
+  if (entry.status === ENTITLEMENT.DENIED || entry.status === ENTITLEMENT.UNVERIFIED) {
+    return {
+      status: entry.status,
+      reason: entry.reason == null ? null : String(entry.reason)
+    };
+  }
+  return null;
+}
+
+/**
+ * Fallback may only be suggested when it is currently automatically
+ * executable AND its entitlement is allowed/not_applicable — or the key
+ * is missing (default ok). Denied/unverified fallbacks stay null.
+ */
+function routableAlternative(model, eligibility, modelEntitlement = {}) {
   if (!model) return null;
   if (!isAutomatic(model)) return null;
   if (eligibility[model.adapterId]?.ok !== true) return null;
+  const entry = modelEntitlement?.[model.modelId];
+  if (entry && typeof entry === "object" && !ROUTABLE_ENTITLEMENTS.has(entry.status)) {
+    return null;
+  }
   return { provider: model.adapterId, model };
 }
 
@@ -80,6 +112,10 @@ function blocked(role, strategyFingerprint, why, { blockedAssignment = null, sug
  *    MANUAL_HANDOFF, still naming the real model/provider so the caller
  *    can show a concrete handoff ("Continue in Cursor with <model>"),
  *    never a bare "not supported".
+ * 3.5 Live model entitlement (when `modelEntitlement[modelId]` is present
+ *    and status is denied or unverified) -> WAIT_FOR_PROJECT_TEAM with
+ *    blockedAssignment naming the real CLI reason when available.
+ *    Empty `{}` skips this gate.
  * 4. The assigned provider isn't currently eligible (quota/availability
  *    changed since the strategy was approved) -> WAIT_FOR_PROJECT_TEAM,
  *    with `blockedAssignment` naming the real unavailable model/reason and
@@ -103,9 +139,12 @@ function blocked(role, strategyFingerprint, why, { blockedAssignment = null, sug
  * @param {Record<string, {ok: boolean, reason?: string}>} [args.eligibility] -
  *   CURRENT provider eligibility — may have changed since the strategy was
  *   built/approved.
+ * @param {Record<string, {status?: string, reason?: string|null}>} [args.modelEntitlement] -
+ *   live per-model Claude entitlement map (modelId → {status, reason}).
+ *   Empty `{}` (default) does not gate — keeps pre-entitlement callers green.
  * @returns {{decision: "ROUTED"|"MANUAL_HANDOFF"|"WAIT_FOR_PROJECT_TEAM", role: string, provider: string|null, model: object|null, assignmentSource: string|null, strategyFingerprint: string|null, blockedAssignment: {provider: string, model: object, assignmentSource: string}|null, suggestedAlternative: {provider: string, model: object}|null, why: string}}
  */
-export function resolveProjectRoute({ role, strategy, eligibility = {} }) {
+export function resolveProjectRoute({ role, strategy, eligibility = {}, modelEntitlement = {} }) {
   const strategyFingerprint = strategy?.profileFingerprint ?? null;
 
   if (!strategy) {
@@ -133,9 +172,25 @@ export function resolveProjectRoute({ role, strategy, eligibility = {} }) {
     };
   }
 
+  const entitlementBlock = blockingEntitlement(model, modelEntitlement);
+  if (entitlementBlock) {
+    const reason = entitlementBlock.reason
+      ?? (entitlementBlock.status === ENTITLEMENT.DENIED
+        ? "account entitlement denied"
+        : "account entitlement unverified");
+    const suggestedAlternative = routableAlternative(fallback, eligibility, modelEntitlement);
+    const why = suggestedAlternative
+      ? `${model.displayName ?? model.modelId} is not currently entitled (${reason}) — no automatic substitution; confirm the suggested alternative for ${role} before proceeding.`
+      : `${model.displayName ?? model.modelId} is not currently entitled (${reason}) — no automatic alternative is available for ${role} right now.`;
+    return blocked(role, strategyFingerprint, why, {
+      blockedAssignment: assignmentRef(model, assignmentSource),
+      suggestedAlternative
+    });
+  }
+
   if (eligibility[model.adapterId]?.ok !== true) {
     const reason = eligibility[model.adapterId]?.reason ?? "unknown reason";
-    const suggestedAlternative = routableAlternative(fallback, eligibility);
+    const suggestedAlternative = routableAlternative(fallback, eligibility, modelEntitlement);
     const why = suggestedAlternative
       ? `${model.adapterId} is not currently eligible (${reason}) — no automatic substitution; confirm the suggested alternative for ${role} before proceeding.`
       : `${model.adapterId} is not currently eligible (${reason}) — no automatic alternative is available for ${role} right now.`;

package/src/global/conversation/service.js

@@ -39,6 +39,11 @@ import { readProviderUsage, writeProviderUsage } from "../runtime/usage-store.js
 import { resolveProjectRoute } from "./project-router.js";
 import { readArtificialAnalysisModels } from "../observability/artificial-analysis-models.js";
 import { readHuggingFaceLeaderboard } from "../observability/huggingface-leaderboard.js";
+import {
+  DEFAULT_ENTITLEMENT_TTL_MS,
+  readClaudeEntitlementCache,
+  resolveClaudeEntitlements
+} from "../observability/claude-entitlement-store.js";
 import {
   annotateWithRegistryEvidence, bestEfficientModelPerRoleGlobal, bestModelPerRole, bestModelPerRoleGlobal, buildAiTeam,
   buildEfficientTeam, scoreAvailableModels, summarizeCatalogCoverage
@@ -299,6 +304,11 @@ export function createConversationService(deps = {}) {
   // disk (no network call) but still shouldn't re-scan on every 2s poll.
   const huggingFaceLeaderboardTtlMs = deps.huggingFaceLeaderboardTtlMs ?? 6 * 60 * 60_000;
   const telemetryTtlMs = deps.telemetryTtlMs ?? 30_000;
+  // Claude entitlement disk cache is stable for days; subscription auth is
+  // a real CLI spawn (~10s) — cache both so snapshot() polls never re-probe
+  // per-model entitlement (that lives behind /models --verify-access).
+  const claudeEntitlementCacheTtlMs = deps.claudeEntitlementCacheTtlMs ?? 600_000;
+  const claudeSubscriptionAuthTtlMs = deps.claudeSubscriptionAuthTtlMs ?? 10_000;
   const now = deps.now ?? (() => Date.now());
 
   // Shared TTL + in-flight-dedupe cache for both provider usage probes:
@@ -341,6 +351,19 @@ export function createConversationService(deps = {}) {
   const readOpenCodeUsageCached = createCachedProbe(readOpenCodeUsageImpl, opencodeUsageTtlMs);
   const readOpenCodeGoCached = createCachedProbe(readOpenCodeGoImpl, opencodeGoUsageTtlMs);
   const readOpenCodeStatsCached = createCachedProbe(readOpenCodeStatsImpl, opencodeUsageTtlMs);
+  const readClaudeEntitlementCacheImpl = deps.readClaudeEntitlementCache ?? readClaudeEntitlementCache;
+  const readClaudeEntitlementCacheCached = createCachedProbe(
+    () => readClaudeEntitlementCacheImpl(homeDir), claudeEntitlementCacheTtlMs
+  );
+  // Auth spawn is slow; never re-run on every poll. Failures cache as null
+  // so resolveClaudeEntitlements treats subscription as mismatched/absent.
+  const verifyClaudeSubscriptionAuthCached = createCachedProbe(async () => {
+    try {
+      return await verifyClaudeSubscriptionAuthImpl({});
+    } catch {
+      return null;
+    }
+  }, claudeSubscriptionAuthTtlMs);
 
   async function executionFor(projectRoot, taskId) {
     const link = await readExecution(projectRoot, taskId);
@@ -459,11 +482,13 @@ export function createConversationService(deps = {}) {
       // explicit /project analyze or /project refresh.
       result.projectStrategy = await readProjectStrategyImpl(homeDir, projectRoot);
       if (enableProviderProbes) {
-        const [codexCatalog, opencodeGoCatalog, cursorCatalog, aa] = await Promise.all([
+        const [codexCatalog, opencodeGoCatalog, cursorCatalog, aa, entitlementCache, claudeAuth] = await Promise.all([
           readCodexModelsCached(projectRoot, { cwd: projectRoot }),
           readOpenCodeGoModelsCached("global", {}),
           readCursorModelsCached(projectRoot, { cwd: projectRoot }),
-          readArtificialAnalysisModelsCached("global", {})
+          readArtificialAnalysisModelsCached("global", {}),
+          readClaudeEntitlementCacheCached("global", {}),
+          verifyClaudeSubscriptionAuthCached("global", {})
         ]);
         // Same eligibility policy the execution/ask router uses, with one
         // deliberate exception: opencode-go is allowed here even without
@@ -489,6 +514,14 @@ export function createConversationService(deps = {}) {
           if (check.ok) candidates.push(adapterId);
         }
         const claudeCatalog = readClaudeModelsImpl();
+        // Cache-only resolve — never probeClaudeModelEntitlement* from snapshot().
+        const claudeEntitlement = resolveClaudeEntitlements({
+          cache: entitlementCache,
+          subscriptionType: claudeAuth?.subscriptionType ?? null,
+          catalogIds: (claudeCatalog.models ?? []).map((m) => m.id),
+          now: now(),
+          ttlMs: deps.claudeEntitlementTtlMs ?? DEFAULT_ENTITLEMENT_TTL_MS
+        });
         const catalogsByAdapter = {
           codex: codexCatalog?.models ?? [],
           claude: claudeCatalog.models,
@@ -515,7 +548,8 @@ export function createConversationService(deps = {}) {
         // exact same real provider catalogs scoredAllRaw itself came from.
         const completeCandidateCatalog = buildCompleteCandidateCatalog(
           Object.keys(catalogsByAdapter).map((adapterId) => ({ adapterId, models: catalogsByAdapter[adapterId] ?? [] })),
-          aa.models
+          aa.models,
+          { modelEntitlement: claudeEntitlement }
         );
         // The Recommendation Pool: scoredAllRaw joined with its real
         // identity, with genuinely superseded generations excluded —
@@ -606,6 +640,8 @@ export function createConversationService(deps = {}) {
           status: aa.status, source: aa.source, age: aa.age,
           models: annotateWithRegistryEvidence(scored, registry), roles: bestModelPerRole(scored),
           eligibility, coverage, unscoredModels,
+          // Resolved Claude per-model entitlement (cache-only; never probed here).
+          claudeEntitlement,
           // BEST FIT GLOBAL / EFFICIENT GLOBAL: the honest, uncoordinated
           // per-role winner — never cedes a role for portfolio diversity,
           // family concentration, or provider distribution (see
@@ -781,8 +817,8 @@ export function createConversationService(deps = {}) {
       const projectRoot = await root(cwd);
       const profile = await computeProjectProfileImpl({ cwd: projectRoot });
       const snap = await this.snapshot({ cwd: projectRoot });
-      const { scoredAll = [], eligibility = {}, registry = null, providerCapacity = null, unscoredModels = [] } = snap.modelIntelligence ?? {};
-      const candidates = { scoredAll, eligibility, registry, providerCapacity };
+      const { scoredAll = [], eligibility = {}, registry = null, providerCapacity = null, unscoredModels = [], claudeEntitlement = {} } = snap.modelIntelligence ?? {};
+      const candidates = { scoredAll, eligibility, registry, providerCapacity, claudeEntitlement };
       const alternatives = computeBootstrapAnalystAlternatives(candidates);
       const analystCatalog = computeBootstrapAnalystCatalog({ ...candidates, unscoredModels });
       return { profile, alternatives, candidates, analystCatalog, projectRoot };
@@ -826,7 +862,8 @@ export function createConversationService(deps = {}) {
           modelId: analyst.model.modelId,
           deps: {
             askProvider: askProviderImpl, runCodexSandboxedBootstrap: runCodexSandboxedBootstrapImpl, isolationDeps: codexIsolationDeps,
-            verifyClaudeSubscriptionAuth: verifyClaudeSubscriptionAuthImpl, readClaudeModels: readClaudeModelsImpl
+            verifyClaudeSubscriptionAuth: verifyClaudeSubscriptionAuthImpl, readClaudeModels: readClaudeModelsImpl,
+            modelEntitlement: candidates?.claudeEntitlement ?? {}
           }
         });
         const eligibility = await adapter.checkEligibility();
@@ -1007,7 +1044,8 @@ export function createConversationService(deps = {}) {
       const strategy = await readProjectStrategyImpl(homeDir, projectRoot);
       const snap = await this.snapshot({ cwd: projectRoot });
       const eligibility = snap.modelIntelligence?.eligibility ?? {};
-      return resolveProjectRoute({ role, strategy, eligibility });
+      const modelEntitlement = snap.modelIntelligence?.claudeEntitlement ?? {};
+      return resolveProjectRoute({ role, strategy, eligibility, modelEntitlement });
     },
     /**
      * Read-only preview of what executePlan would do right now.

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

@@ -31,8 +31,11 @@
 // anything downstream just because its lineage couldn't be determined.
 
 import { matchArtificialAnalysisScore } from "./model-intelligence.js";
+import { ENTITLEMENT } from "../observability/claude-model-entitlement.js";
 
 /**
+ * @typedef {"allowed"|"denied"|"unverified"|"not_applicable"} ModelEntitlementStatus
+ *
  * @typedef {object} ModelCandidateIdentity
  * @property {string} candidateKey - `${adapterId}::${modelId}`, this catalog's stable identity key.
  * @property {string} modelId - the exact provider-reported id — what scoring/execution actually use, never the cleaned name.
@@ -40,6 +43,8 @@ import { matchArtificialAnalysisScore } from "./model-intelligence.js";
  * @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 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 {ModelEntitlementStatus} entitlement - orthogonal to accessMode. Codex/Cursor/OpenCode Go/Zen are `not_applicable` (their catalog IS access proof). Claude comes from the live entitlement map, or `unverified` when that map has no entry.
+ * @property {string|null} entitlementReason - real CLI/reason string when entitlement is denied/unverified with a message; otherwise null.
  * @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.
@@ -47,6 +52,39 @@ import { matchArtificialAnalysisScore } from "./model-intelligence.js";
  * @property {{inputPerMTok: number, outputPerMTok: number}|null} resourceCost - real, provider-reported cost, when the provider actually reports one (OpenCode Go today) — never estimated or carried over from a different model.
  */
 
+const AUTOMATIC_ENTITLEMENTS = new Set([ENTITLEMENT.ALLOWED, ENTITLEMENT.NOT_APPLICABLE]);
+
+/**
+ * Resolves per-model entitlement orthogonal to accessMode.
+ * Non-Claude adapters: not_applicable (catalog presence is access proof).
+ * Claude: from deps.modelEntitlement[modelId], or unverified when missing.
+ * @param {string} adapterId
+ * @param {string} modelId
+ * @param {Record<string, {status?: string, reason?: string|null}>} [modelEntitlement]
+ * @returns {{entitlement: ModelEntitlementStatus, entitlementReason: string|null}}
+ */
+function resolveEntitlement(adapterId, modelId, modelEntitlement = {}) {
+  if (adapterId !== "claude") {
+    return { entitlement: ENTITLEMENT.NOT_APPLICABLE, entitlementReason: null };
+  }
+  const entry = modelEntitlement[modelId];
+  if (!entry || typeof entry !== "object") {
+    return { entitlement: ENTITLEMENT.UNVERIFIED, entitlementReason: null };
+  }
+  const status = entry.status;
+  if (
+    status === ENTITLEMENT.ALLOWED
+    || status === ENTITLEMENT.DENIED
+    || status === ENTITLEMENT.UNVERIFIED
+  ) {
+    return {
+      entitlement: status,
+      entitlementReason: entry.reason == null ? null : String(entry.reason)
+    };
+  }
+  return { entitlement: ENTITLEMENT.UNVERIFIED, entitlementReason: null };
+}
+
 // Real variant tokens observed across the four live provider catalogs
 // this session audited (Cursor's 223-model catalog especially — the only
 // source that embeds these directly into displayName text, with no
@@ -332,16 +370,18 @@ function resolveResourceCost(rawModel) {
  * @param {{id: string, displayName?: string}} rawModel
  * @param {Array<object>} aaModels
  * @param {(modelId: string, aaModels: Array<object>) => object|null} matcher
+ * @param {Record<string, {status?: string, reason?: string|null}>} [modelEntitlement]
  * @returns {ModelCandidateIdentity}
  */
-function buildCandidateIdentity(adapterId, rawModel, aaModels, matcher) {
+function buildCandidateIdentity(adapterId, rawModel, aaModels, matcher, modelEntitlement = {}) {
   const modelId = rawModel.id;
   const rawDisplayName = rawModel.displayName ?? modelId;
+  const { entitlement, entitlementReason } = resolveEntitlement(adapterId, modelId, modelEntitlement);
 
   if (adapterId === "cursor" && modelId === "auto") {
     return {
       candidateKey: `${adapterId}::${modelId}`, modelId, modelName: "Cursor Auto", rawDisplayName,
-      adapterId, accessMode: "manual", evidenceStatus: "unscored",
+      adapterId, accessMode: "manual", entitlement, entitlementReason, evidenceStatus: "unscored",
       lineageKey: null, generation: null, lifecycle: "unknown", resourceCost: null
     };
   }
@@ -351,7 +391,8 @@ function buildCandidateIdentity(adapterId, rawModel, aaModels, matcher) {
   const lineage = resolveLineage(modelId);
   return {
     candidateKey: `${adapterId}::${modelId}`, modelId, modelName, rawDisplayName,
-    adapterId, accessMode: resolveAccessMode(adapterId, modelId), evidenceStatus: resolveEvidenceStatus(matched),
+    adapterId, accessMode: resolveAccessMode(adapterId, modelId), entitlement, entitlementReason,
+    evidenceStatus: resolveEvidenceStatus(matched),
     // lifecycle is resolved in a second pass (applyLifecycle, called from
     // buildCompleteCandidateCatalog) once the WHOLE catalog is known —
     // "superseded" is a statement about this candidate relative to its
@@ -372,16 +413,22 @@ function buildCandidateIdentity(adapterId, rawModel, aaModels, matcher) {
  *   same shape model-intelligence.js's scoreAvailableModels takes, e.g.
  *   `[{ adapterId: "codex", models: readCodexModels().models }, ...]`.
  * @param {Array<object>} aaModels - readArtificialAnalysisModels().models
- * @param {{matchArtificialAnalysisScore?: (modelId: string, aaModels: Array<object>) => object|null}} [deps] -
+ * @param {{
+ *   matchArtificialAnalysisScore?: (modelId: string, aaModels: Array<object>) => object|null,
+ *   modelEntitlement?: Record<string, {status?: string, reason?: string|null}>
+ * }} [deps] -
  *   injectable for tests; defaults to model-intelligence.js's real export.
+ *   `modelEntitlement` is Claude-only live entitlement (allowed/denied/unverified);
+ *   missing keys leave Claude as unverified. Non-Claude adapters ignore it.
  * @returns {Array<ModelCandidateIdentity>}
  */
 export function buildCompleteCandidateCatalog(providerCatalogs, aaModels, deps = {}) {
   const matcher = deps.matchArtificialAnalysisScore ?? matchArtificialAnalysisScore;
+  const modelEntitlement = deps.modelEntitlement ?? {};
   const catalog = [];
   for (const { adapterId, models } of providerCatalogs) {
     for (const rawModel of models ?? []) {
-      catalog.push(buildCandidateIdentity(adapterId, rawModel, aaModels, matcher));
+      catalog.push(buildCandidateIdentity(adapterId, rawModel, aaModels, matcher, modelEntitlement));
     }
   }
   return applyLifecycle(catalog);
@@ -435,11 +482,20 @@ export function buildRecommendationPool(scoredAll, completeCatalog) {
     // never excludes: an un-joined candidate is treated as lineage-
     // unknown, exactly like any other real unrecognized lineage.
     if (identity?.lifecycle === "superseded") continue;
+    // Denied entitlement is the same class as superseded: never recommend.
+    // Unverified Claude stays recommendable (human can still pick it);
+    // only automatic launch excludes it (see buildAutomaticExecutionPool).
+    if (identity?.entitlement === ENTITLEMENT.DENIED) continue;
+    const fallbackEntitlement = scored.adapterId === "claude"
+      ? ENTITLEMENT.UNVERIFIED
+      : ENTITLEMENT.NOT_APPLICABLE;
     pool.push({
       ...scored,
       candidateKey,
       modelName: identity?.modelName ?? scored.displayName ?? scored.modelId,
       accessMode: identity?.accessMode ?? "manual",
+      entitlement: identity?.entitlement ?? fallbackEntitlement,
+      entitlementReason: identity?.entitlementReason ?? null,
       evidenceStatus: identity?.evidenceStatus ?? "scored",
       lineageKey: identity?.lineageKey ?? null,
       generation: identity?.generation ?? null,
@@ -459,16 +515,22 @@ export function buildRecommendationPool(scoredAll, completeCatalog) {
  * ModelCandidateIdentity's own doc) AND real,
  * current eligibility (adapter availability, quota, launchability — the
  * exact same `eligibility` object checkCandidate/execution-router.js
- * already compute, reused here rather than reimplemented). Never
- * mutates or filters the Recommendation Pool itself — a manual-only real
- * recommendation (Cursor, say) stays fully visible there; a caller that
- * wants to actually RUN a task must separately produce a real
- * "Continue in Cursor"-style handoff for it, never a silent fallback to
- * a different, automatically-launchable model the human didn't ask for.
+ * already compute, reused here rather than reimplemented) AND entitlement
+ * in {allowed, not_applicable} — denied and unverified Claude never
+ * auto-launch. Never mutates or filters the Recommendation Pool itself —
+ * a manual-only real recommendation (Cursor, say) stays fully visible
+ * there; a caller that wants to actually RUN a task must separately
+ * produce a real "Continue in Cursor"-style handoff for it, never a
+ * silent fallback to a different, automatically-launchable model the
+ * human didn't ask for.
  * @param {Array<RecommendationPoolCandidate>} recommendationPool
  * @param {Record<string, {ok: boolean, reason?: string}>} eligibility - checkCandidate() results per adapterId.
  * @returns {Array<RecommendationPoolCandidate>}
  */
 export function buildAutomaticExecutionPool(recommendationPool, eligibility) {
-  return recommendationPool.filter((candidate) => candidate.accessMode === "automatic" && eligibility[candidate.adapterId]?.ok === true);
+  return recommendationPool.filter((candidate) => (
+    candidate.accessMode === "automatic"
+    && eligibility[candidate.adapterId]?.ok === true
+    && AUTOMATIC_ENTITLEMENTS.has(candidate.entitlement)
+  ));
 }

package/src/global/observability/claude-model-entitlement.js

@@ -10,7 +10,9 @@ import { buildClaudeExecutionEnv } from "../runtime/execution-adapters/claude.js
 export const ENTITLEMENT = Object.freeze({
   ALLOWED: "allowed",
   DENIED: "denied",
-  UNVERIFIED: "unverified"
+  UNVERIFIED: "unverified",
+  // Non-Claude providers: their live/documented catalog IS access proof.
+  NOT_APPLICABLE: "not_applicable"
 });
 
 const DENIED_ERROR_CODES = new Set(["credits_required"]);

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.26.1" },
+      clientInfo: { name: "kairo", title: "Kairo", version: "0.27.0" },
       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.26.1" },
+      clientInfo: { name: "kairo", title: "Kairo", version: "0.27.0" },
       capabilities: {}
     });
   });