@kal-elsam/kairo-runtime 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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).
+
+### Added
+
+- Live Claude per-model entitlement probe (`claude -p hi --model … --output-format
+  json`) with fail-closed classification (allowed / denied / unverified) and a
+  `~/.harness/claude-entitlement.json` cache invalidated by subscription type
+  change or a 7-day per-entry TTL. Pure additive — recommendation and automatic
+  pools are unchanged until the next increment wires entitlement into the catalog.
+
 ## 0.26.0 — 2026-09-19 (Kairo Runtime)
 
 Minor release. ASK is now ready for every real automatic adapter.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.26.0",
+  "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-entitlement-store.js

@@ -0,0 +1,167 @@
+// Disk cache for Claude per-model entitlement probes. Mirrors the
+// artificial-analysis-models.js pattern (read→null on any failure, mkdir +
+// writeAtomicJson, fetchedAt / ageLabel) — not usage-store.js, whose
+// whitelist is for real billing providers.
+
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { harnessHomePaths } from "../paths.js";
+import { writeAtomicJson } from "../runtime/write-atomic-json.js";
+import { ENTITLEMENT } from "./claude-model-entitlement.js";
+
+export const DEFAULT_ENTITLEMENT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+function ageLabel(fetchedAtIso, nowMs = Date.now()) {
+  const fetchedAt = new Date(fetchedAtIso ?? "").getTime();
+  if (!Number.isFinite(fetchedAt)) return null;
+  const hours = (nowMs - fetchedAt) / 3_600_000;
+  if (hours < 1) return "<1h";
+  if (hours < 48) return `${Math.round(hours)}h`;
+  return `${Math.round(hours / 24)}d`;
+}
+
+function isPersistableStatus(status) {
+  return status === ENTITLEMENT.ALLOWED || status === ENTITLEMENT.DENIED;
+}
+
+function emptyDoc(subscriptionType, fetchedAt = new Date().toISOString()) {
+  return {
+    subscriptionType: subscriptionType ?? null,
+    fetchedAt,
+    models: Object.create(null)
+  };
+}
+
+/**
+ * @param {string} homeDir
+ * @param {object} [deps]
+ * @returns {Promise<object|null>}
+ */
+export async function readClaudeEntitlementCache(homeDir, deps = {}) {
+  const read = deps.readFile ?? readFile;
+  try {
+    const raw = await read(harnessHomePaths(homeDir).claudeEntitlementPath, "utf8");
+    const doc = JSON.parse(raw);
+    if (!doc || typeof doc !== "object") return null;
+    if (typeof doc.fetchedAt !== "string") return null;
+    if (!doc.models || typeof doc.models !== "object" || Array.isArray(doc.models)) return null;
+    return doc;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} homeDir
+ * @param {object} doc
+ * @param {object} [deps]
+ */
+export async function writeClaudeEntitlementCache(homeDir, doc, deps = {}) {
+  const mkdirImpl = deps.mkdir ?? mkdir;
+  const writeJson = deps.writeAtomicJson ?? writeAtomicJson;
+  const path = harnessHomePaths(homeDir).claudeEntitlementPath;
+  await mkdirImpl(dirname(path), { recursive: true });
+  await writeJson(path, doc);
+}
+
+/**
+ * Pure resolver: map catalog ids → live entitlement view from cache.
+ * Invalidates the entire cache when subscriptionType differs.
+ *
+ * @param {{
+ *   cache: object|null,
+ *   subscriptionType: string|null,
+ *   catalogIds: string[],
+ *   now?: number,
+ *   ttlMs?: number
+ * }} options
+ * @returns {Record<string, { status: string, reason: string|null, age: string|null, probedAt: string|null }>}
+ */
+export function resolveClaudeEntitlements({
+  cache,
+  subscriptionType,
+  catalogIds = [],
+  now = Date.now(),
+  ttlMs = DEFAULT_ENTITLEMENT_TTL_MS
+} = {}) {
+  const usable = cache
+    && typeof cache === "object"
+    && cache.subscriptionType === subscriptionType
+    && cache.models
+    && typeof cache.models === "object"
+    ? cache
+    : null;
+
+  const resolved = Object.create(null);
+  for (const modelId of catalogIds) {
+    const entry = usable?.models?.[modelId] ?? null;
+    if (!entry || !isPersistableStatus(entry.status)) {
+      resolved[modelId] = {
+        status: ENTITLEMENT.UNVERIFIED,
+        reason: null,
+        age: null,
+        probedAt: null
+      };
+      continue;
+    }
+
+    const probedAtMs = new Date(entry.probedAt ?? "").getTime();
+    if (!Number.isFinite(probedAtMs) || now - probedAtMs > ttlMs) {
+      resolved[modelId] = {
+        status: ENTITLEMENT.UNVERIFIED,
+        reason: null,
+        age: ageLabel(entry.probedAt, now),
+        probedAt: entry.probedAt ?? null
+      };
+      continue;
+    }
+
+    resolved[modelId] = {
+      status: entry.status,
+      reason: entry.reason ?? null,
+      age: ageLabel(entry.probedAt, now),
+      probedAt: entry.probedAt
+    };
+  }
+  return resolved;
+}
+
+/**
+ * Merge fresh probe results into a cache doc. Discards status "unknown"
+ * (and unverified) — only allowed/denied evidence is persisted.
+ *
+ * @param {object|null} cache
+ * @param {{ subscriptionType: string|null, catalogIds?: string[], results: Array<{ modelId: string, status: string, reason?: string|null, probedAt?: string }> }} payload
+ */
+export function mergeEntitlementResults(cache, { subscriptionType, results = [] } = {}) {
+  const base = cache
+    && typeof cache === "object"
+    && cache.subscriptionType === subscriptionType
+    && cache.models
+    && typeof cache.models === "object"
+    ? {
+      subscriptionType: cache.subscriptionType,
+      fetchedAt: cache.fetchedAt,
+      models: { ...cache.models }
+    }
+    : emptyDoc(subscriptionType);
+
+  let newestProbedAt = base.fetchedAt;
+  for (const result of results) {
+    if (!result || typeof result.modelId !== "string") continue;
+    if (result.status === "unknown" || !isPersistableStatus(result.status)) continue;
+    const probedAt = typeof result.probedAt === "string"
+      ? result.probedAt
+      : new Date().toISOString();
+    base.models[result.modelId] = {
+      status: result.status,
+      reason: result.reason ?? null,
+      probedAt
+    };
+    if (!newestProbedAt || probedAt > newestProbedAt) newestProbedAt = probedAt;
+  }
+
+  base.fetchedAt = newestProbedAt ?? new Date().toISOString();
+  base.subscriptionType = subscriptionType ?? null;
+  return base;
+}

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

@@ -0,0 +1,187 @@
+// Live per-model Claude entitlement probe. Kept separate from
+// claude-models.js on purpose: that module is sync, free, and pure, and
+// three of its four callers sit on hot paths. This module is the only
+// place that interprets the real `claude -p … --output-format json`
+// response for account access — fail-closed, never inventing allowed.
+
+import { spawn as defaultSpawn } from "node:child_process";
+import { buildClaudeExecutionEnv } from "../runtime/execution-adapters/claude.js";
+
+export const ENTITLEMENT = Object.freeze({
+  ALLOWED: "allowed",
+  DENIED: "denied",
+  UNVERIFIED: "unverified",
+  // Non-Claude providers: their live/documented catalog IS access proof.
+  NOT_APPLICABLE: "not_applicable"
+});
+
+const DENIED_ERROR_CODES = new Set(["credits_required"]);
+const DENIED_HTTP_STATUSES = new Set([402, 403, 429]);
+const DEFAULT_TIMEOUT_MS = 30_000;
+const PROBE_ARGS_PREFIX = Object.freeze(["-p", "hi", "--model"]);
+const PROBE_ARGS_SUFFIX = Object.freeze(["--output-format", "json"]);
+
+/**
+ * Pure classifier for a parsed Claude CLI `--output-format json` result.
+ * The only place that interprets the real JSON shape for entitlement.
+ *
+ * @param {object|null|undefined} parsed
+ * @returns {{ status: string, reason: string|null }}
+ */
+export function classifyClaudeEntitlementResponse(parsed) {
+  if (!parsed || typeof parsed !== "object") {
+    return { status: ENTITLEMENT.UNVERIFIED, reason: null };
+  }
+
+  const isError = parsed.is_error === true;
+  const status = parsed.api_error_status;
+  const code = parsed.api_error_code;
+  const message = typeof parsed.result === "string" && parsed.result.trim()
+    ? parsed.result
+    : null;
+
+  if (
+    isError
+    && (DENIED_ERROR_CODES.has(code) || DENIED_HTTP_STATUSES.has(status))
+  ) {
+    return { status: ENTITLEMENT.DENIED, reason: message };
+  }
+
+  if (parsed.is_error === false && (status === null || status === undefined)) {
+    return { status: ENTITLEMENT.ALLOWED, reason: null };
+  }
+
+  return { status: ENTITLEMENT.UNVERIFIED, reason: message };
+}
+
+function probeArgv(modelId) {
+  return [...PROBE_ARGS_PREFIX, modelId, ...PROBE_ARGS_SUFFIX];
+}
+
+function unverifiedResult(modelId, reason = null) {
+  return {
+    modelId,
+    status: ENTITLEMENT.UNVERIFIED,
+    reason: reason == null ? null : String(reason),
+    probedAt: new Date().toISOString()
+  };
+}
+
+/**
+ * Probe a single Claude model id via the measured CLI shape.
+ * @param {{ modelId: string, spawn?: typeof defaultSpawn, cwd?: string, env?: NodeJS.ProcessEnv, timeoutMs?: number }} options
+ */
+export async function probeClaudeModelEntitlement({
+  modelId,
+  spawn = defaultSpawn,
+  cwd = process.cwd(),
+  env = process.env,
+  timeoutMs = DEFAULT_TIMEOUT_MS
+} = {}) {
+  if (typeof modelId !== "string" || !modelId) {
+    return unverifiedResult(modelId ?? "", "modelId is required");
+  }
+
+  let child;
+  try {
+    child = spawn("claude", probeArgv(modelId), {
+      cwd,
+      env: buildClaudeExecutionEnv(env),
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch (error) {
+    return unverifiedResult(modelId, error?.message ?? error);
+  }
+
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let finished = false;
+    const timer = setTimeout(
+      () => finish(unverifiedResult(modelId, `claude entitlement probe timed out after ${timeoutMs}ms`)),
+      timeoutMs
+    );
+
+    function finish(result) {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      try { child.kill?.(); } catch { /* best effort */ }
+      resolve(result);
+    }
+
+    child.stdout?.on("data", (chunk) => { stdout += chunk; });
+    child.stderr?.on("data", (chunk) => { stderr += chunk; });
+    child.once?.("error", (error) => finish(unverifiedResult(modelId, error?.message ?? error)));
+    child.once?.("close", (code, signal) => {
+      if (signal) {
+        return finish(unverifiedResult(
+          modelId,
+          `claude entitlement probe was killed by signal ${signal}${stderr ? `: ${stderr.trim()}` : ""}`
+        ));
+      }
+
+      let parsed = null;
+      try {
+        const trimmed = String(stdout ?? "").trim();
+        parsed = trimmed ? JSON.parse(trimmed) : null;
+      } catch {
+        return finish(unverifiedResult(
+          modelId,
+          `claude entitlement probe returned invalid JSON${stderr ? `: ${stderr.trim()}` : ""}`
+        ));
+      }
+
+      const classified = classifyClaudeEntitlementResponse(parsed);
+      // A non-zero exit with a classifiable JSON body still trusts the body —
+      // the measured denied probe exits 0, but broken/unknown shapes stay
+      // unverified regardless of exit code. Never promote a failed spawn to
+      // allowed just because exit was 0 with empty stdout (parsed null →
+      // unverified above).
+      if (classified.status === ENTITLEMENT.ALLOWED && code !== 0) {
+        return finish(unverifiedResult(
+          modelId,
+          `claude entitlement probe exited with code ${code}${stderr ? `: ${stderr.trim()}` : ""}`
+        ));
+      }
+
+      finish({
+        modelId,
+        status: classified.status,
+        reason: classified.reason,
+        probedAt: new Date().toISOString()
+      });
+    });
+  });
+}
+
+/**
+ * Probe many model ids sequentially (never Promise.all). Caps at maxProbes.
+ * @param {{
+ *   modelIds: string[],
+ *   maxProbes?: number,
+ *   onProgress?: (event: { modelId: string, index: number, total: number, result: object }) => void,
+ *   spawn?: typeof defaultSpawn,
+ *   cwd?: string,
+ *   env?: NodeJS.ProcessEnv,
+ *   timeoutMs?: number
+ * }} options
+ */
+export async function probeClaudeModelEntitlements({
+  modelIds = [],
+  maxProbes = 12,
+  onProgress = null,
+  ...probeOpts
+} = {}) {
+  const ids = Array.isArray(modelIds) ? modelIds.slice(0, Math.max(0, maxProbes)) : [];
+  const results = [];
+  for (let index = 0; index < ids.length; index += 1) {
+    const modelId = ids[index];
+    const result = await probeClaudeModelEntitlement({ modelId, ...probeOpts });
+    results.push(result);
+    if (typeof onProgress === "function") {
+      onProgress({ modelId, index, total: ids.length, result });
+    }
+  }
+  return results;
+}

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

package/src/global/paths.js

@@ -28,6 +28,7 @@ export function harnessHomePaths(homeDir) {
     worktreesDir: join(root, "worktrees"),
     usageDir: join(root, "usage"),
     modelIntelligencePath: join(root, "model-intelligence.json"),
+    claudeEntitlementPath: join(root, "claude-entitlement.json"),
     huggingfaceLeaderboardPath: join(root, "huggingface-leaderboard.json")
   };
 }