@kal-elsam/kairo-runtime 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ Historical entries below may reference the legacy `@kal-elsam/harness` package n
 
 ## Unreleased
 
+## 0.29.0 — 2026-09-19 (Kairo Runtime)
+
+Minor release. PROJECT TEAM selections explain themselves.
+
+### Changed
+
+- Every PROJECT TEAM row now has a non-empty explanation — ordinary
+  leaders no longer render blank (`explainTeamDecision` from real
+  `decisionEvidence`, never invented metrics).
+- Compact panel and `/project` overlay show the quality leader and real
+  retention% when the operational (efficient) pick differs; evidence
+  toggle (`e`) reuses `teamEvidenceLines`.
+- Honest subtitle: operational picks are the efficient model among
+  eligible candidates. Orchestrator* footnote: Architect's quality pick
+  — Kairo has no separate orchestrator capability profile yet.
+- Availability warnings for denied/unverified Claude entitlement.
+
+## 0.28.0 — 2026-09-19 (Kairo Runtime)
+
+Minor release. `/models --verify-access` verifies Claude model entitlement on demand.
+
+### Added
+
+- `/models --verify-access [--refresh]` — sequential, human-triggered Claude
+  entitlement probes with a real cost statement before any spawn. Without
+  `--refresh`, only unverified or TTL-expired models are probed; an all-
+  unverified sweep does not persist evidence.
+- One-line Spanish preflight notice when Claude models still have unverified
+  access (recommendable, never auto-launched).
+
 ## 0.27.0 — 2026-09-19 (Kairo Runtime)
 
 Minor release. Claude model entitlement now gates PROJECT TEAM pools and routes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.27.0",
+  "version": "0.29.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/cockpit/app.js

@@ -258,7 +258,7 @@ export async function runCockpitApp({
       // blocks with no indication of which command produced which one.
       pushTranscript("user", task);
       if (command === "/help") {
-        pushTranscript("kairo", "Shift+Tab cycles ASK/PLAN/AGENT · /project interactive overlay (or analyze/analyst/approve/refresh/status/cursor exhausted|available subcommands for scripted use) · /plan <task> force a plan · /usage automatic-provider status (Codex/Claude/Go) · /providers all connections incl. Zen/Cursor (manual) · /models CAPABILITY + EFFICIENT picks (--evidence for raw metrics) · /why eligibility detail · /clear · /quit");
+        pushTranscript("kairo", "Shift+Tab cycles ASK/PLAN/AGENT · /project interactive overlay (or analyze/analyst/approve/refresh/status/cursor exhausted|available subcommands for scripted use) · /plan <task> force a plan · /usage automatic-provider status (Codex/Claude/Go) · /providers all connections incl. Zen/Cursor (manual) · /models CAPABILITY + EFFICIENT picks (--evidence for raw metrics; --verify-access [--refresh] for Claude entitlement) · /why eligibility detail · /clear · /quit");
       } else if (command === "/usage") {
         for (const line of view.usageLines()) pushTranscript("kairo", line);
       } else if (command === "/providers") {
@@ -271,8 +271,38 @@ export async function runCockpitApp({
         // the plain-language why (capability, efficient alternative,
         // fallback), never raw metrics/percentages/ids/sources. Those
         // stay behind the explicit --evidence flag for technical audit.
-        const flag = task.slice(command.length).trim();
-        const explainLines = flag === "--evidence" ? view.aiTeamDetailLines() : view.modelsExplainLines();
+        // --verify-access [--refresh] is the only path that spawns Claude
+        // entitlement probes (never on snapshot / first poll).
+        const flags = new Set(task.slice(command.length).trim().split(/\s+/).filter(Boolean));
+        if (flags.has("--verify-access")) {
+          const refresh = flags.has("--refresh");
+          editor.disableSubmit = true;
+          editor.setText("");
+          return runAction("Verifying Claude model access", async () => {
+            const summary = await service.verifyClaudeEntitlements({
+              cwd,
+              refresh,
+              beforeProbe: ({ costStatement }) => {
+                pushTranscript("kairo", costStatement);
+              },
+              onProgress: ({ modelId, index, total }) => {
+                view.beginAction(`Verifying Claude access (${index + 1}/${total}): ${modelId}`);
+              }
+            });
+            const allowed = summary.results.filter((r) => r.status === "allowed").length;
+            const denied = summary.results.filter((r) => r.status === "denied").length;
+            const unverified = summary.results.filter((r) => r.status === "unverified").length;
+            if (summary.probed.length === 0) {
+              pushTranscript("kairo", "Claude access already verified for the current catalog (use --refresh to re-probe).");
+            } else {
+              pushTranscript(
+                "kairo",
+                `Claude access check: ${summary.probed.length} probed · ${allowed} allowed · ${denied} denied · ${unverified} unverified${summary.persisted ? " · cache updated" : " · cache unchanged"}.`
+              );
+            }
+          }).finally(() => { editor.disableSubmit = false; });
+        }
+        const explainLines = flags.has("--evidence") ? view.aiTeamDetailLines() : view.modelsExplainLines();
         for (const line of explainLines) pushTranscript("kairo", line);
       } else if (command === "/why") {
         // Drill-down for FIT: which providers were excluded and the exact
@@ -318,6 +348,9 @@ export async function runCockpitApp({
           return runAction("Analyzing project locally (read-only)", async () => {
             const preflight = await service.preflightProject({ cwd });
             view.pendingProjectAnalysis = preflight;
+            if (preflight.unverifiedClaudeNotice) {
+              pushTranscript("kairo", preflight.unverifiedClaudeNotice);
+            }
             if (!preflight.alternatives.length) {
               pushTranscript("kairo", "No real Project Analyst candidate is available right now (ASK only supports Codex/Claude today).");
               return;

package/src/global/cockpit/project-overlay.js

@@ -1,6 +1,7 @@
 import { Box, SelectList, Text, Input, Key, matchesKey, fuzzyFilter } from "@earendil-works/pi-tui";
 import { editorTheme, theme } from "./theme.js";
 import { CARD_TONE, cardInnerWidth, renderPanel } from "./card.js";
+import { explainTeamDecision } from "./view.js";
 
 // /project's interactive overlay — the real preflight -> select analyst ->
 // confirm -> analyze -> result -> approve loop, reusing the exact same
@@ -109,6 +110,7 @@ export class ProjectOverlay {
     this.editInput = null;
     this.editSelectList = null;
     this.pendingEditCandidate = null;
+    this.showTeamEvidence = false;
 
     const existing = view.snapshot?.projectStrategy ?? null;
     if (existing?.status === "active") {
@@ -160,6 +162,9 @@ export class ProjectOverlay {
     this.view.beginAction("Reading project evidence locally");
     try {
       this.preflight = await this.service.preflightProject({ cwd: this.cwd });
+      if (this.preflight.unverifiedClaudeNotice) {
+        this.onNarrate?.(this.preflight.unverifiedClaudeNotice);
+      }
       const models = this.preflight.analystCatalog?.models ?? [];
       if (!models.length) {
         this.state = S.NO_ANALYST;
@@ -293,16 +298,9 @@ export class ProjectOverlay {
       const overrideNote = entry.assignmentSource === "override" ? theme.fg("accent", " (override)") : "";
       // Role + model are the real primary information here — explicit
       // `text` color, never left to default/muted.
-      // WHY this model was picked — the real, human-readable evidence
-      // buildProjectStrategy already carries (entry.reason, sourced from
-      // efficientTeam's own describeEfficiencyDecision), never a
-      // fabricated justification. An override has no ranking reason of
-      // its own (see applyProjectTeamOverride) — honestly say so instead
-      // of silently reusing the old recommendation's reason for a
-      // different model.
-      const description = entry.assignmentSource === "override"
-        ? "Manual override — not the automatic ranking's own pick."
-        : (entry.reason ?? "");
+      // WHY this model was picked — explainTeamDecision (real reason,
+      // leader formulation, or override text), never an empty row.
+      const description = explainTeamDecision(entry);
       return { value: entry.role, label: theme.fg("text", `${entry.role.padEnd(10)} ${modelText}`) + overrideNote, description };
     });
     this.resultSelectList = new SelectList(items, 6, editorTheme.selectList);
@@ -481,6 +479,13 @@ export class ProjectOverlay {
       // scratch) — distinct from editing one role's model (Enter) or
       // approving the current suggestion (a) — see reanalyze()'s own doc.
       if (data === "r" || data === "R") return void this.reanalyze();
+      // "e" toggles the technical evidence section (kept off by default
+      // so the modal stays short).
+      if (data === "e" || data === "E") {
+        this.showTeamEvidence = !this.showTeamEvidence;
+        this.requestRender();
+        return;
+      }
       this.resultSelectList.handleInput(data);
       this.requestRender();
       return;
@@ -613,16 +618,25 @@ export class ProjectOverlay {
       case S.RESULT: {
         const strategy = this.suggestedStrategy;
         push(theme.bold("Suggested Project Team"));
+        push(theme.fg("muted", "Operational picks: the efficient model among eligible candidates for each role (quality leader shown when it differs)."));
         const choiceNote = strategy.bootstrapAnalystChoice ?? (strategy.bootstrapAnalystSelectionSource === "manual" ? "manual pick" : "recommended");
         push(theme.fg("muted", `Project Analyst: ${choiceNote} — ${this.view.aiTeamLabelWithProvider(strategy.bootstrapAnalyst)}`));
         push(theme.bold("PROJECT TEAM"));
         box.addChild(this.resultSelectList);
+        if (this.showTeamEvidence && typeof this.view.projectTeamEvidenceLines === "function") {
+          const eligibility = this.view.snapshot?.modelIntelligence?.eligibility ?? {};
+          const claudeEntitlement = this.view.snapshot?.modelIntelligence?.claudeEntitlement ?? {};
+          push(theme.fg("muted", "Evidence"));
+          for (const line of this.view.projectTeamEvidenceLines(strategy, { eligibility, claudeEntitlement })) {
+            push(line);
+          }
+        }
         // Quality/Efficient stay real, comparative REFERENCE — muted, and
         // rendered strictly below the real operational PROJECT TEAM list
         // above, never replacing it visually.
         for (const line of teamLines("Quality (reference)", strategy.qualityTeam, this.view, "muted")) push(line);
         for (const line of teamLines("Efficient (reference)", strategy.efficientTeam, this.view, "muted")) push(line);
-        push(theme.fg("muted", "Enter edit role · a approve & activate · r re-analyze from scratch · Esc close without approving"));
+        push(theme.fg("muted", "Enter edit role · a approve & activate · e evidence · r re-analyze from scratch · Esc close without approving"));
         break;
       }
       case S.EDIT_LOADING:

package/src/global/cockpit/view.js

@@ -3,6 +3,85 @@ import { buildTaskRows, clampSelection, isActionAvailable } from "./rows.js";
 import { CARD_TONE, cardBottom, cardInnerWidth, cardLine, cardTop, renderPanel as renderPanelWithTheme } from "./card.js";
 import { theme } from "./theme.js";
 import { LOW_QUOTA_WARN_PERCENT } from "../intelligence/execution-router.js";
+import { ENTITLEMENT } from "../observability/claude-model-entitlement.js";
+
+/** Plain-language description of what each role optimizes for — mirrors
+ * buildAiTeamRoleDefinitions()'s real compute functions in
+ * model-intelligence.js, never a per-model claim, so it never needs
+ * updating when the underlying models change. */
+export const ROLE_CAPABILITY_BLURB = {
+  Explorer: "general reasoning capability",
+  Architect: "general reasoning capability",
+  Builder: "coding capability",
+  Debugger: "reasoning and terminal-debugging capability",
+  Tester: "coding and terminal-execution capability",
+  Reviewer: "independent reasoning and coding review"
+};
+
+const OVERRIDE_DECISION_TEXT = "Manual override — not the automatic ranking's own pick.";
+
+/**
+ * Pure, human-readable why for one team assignment — from real
+ * `reason` / `decisionEvidence` only, never invented metrics.
+ * Existing `entry.reason` always wins; overrides use a single formulation.
+ * @param {{role?: string, reason?: string|null, assignmentSource?: string|null, decisionEvidence?: object|null}} entry
+ * @returns {string}
+ */
+export function explainTeamDecision(entry) {
+  if (!entry) return `Selected for ${ROLE_CAPABILITY_BLURB.Explorer ?? "this role's capability requirement"}.`;
+  if (entry.assignmentSource === "override") return OVERRIDE_DECISION_TEXT;
+  if (entry.reason) return entry.reason;
+
+  const blurb = ROLE_CAPABILITY_BLURB[entry.role] ?? "this role's capability requirement";
+  const decisionType = entry.decisionEvidence?.decisionType ?? null;
+  if (decisionType === "leader") {
+    const floor = entry.decisionEvidence?.requiredFloor;
+    const risk = entry.decisionEvidence?.riskLevel;
+    if (floor != null && risk != null) {
+      const floorPct = Math.round(floor * 100);
+      return `Ranked first for ${blurb} among eligible candidates — nothing cheaper or faster displaced it at the ${floorPct}% capability floor (${risk}-risk role).`;
+    }
+    return `Ranked first for ${blurb} among eligible candidates.`;
+  }
+  return `Selected for ${blurb}.`;
+}
+
+/**
+ * Live availability for a projectTeam model ref (which has no
+ * `available` flag). Entitlement beats adapter quota/eligibility.
+ * @param {object|null|undefined} model
+ * @param {{eligibility?: Record<string, {ok: boolean, reason?: string}>, claudeEntitlement?: Record<string, {status: string, reason?: string|null}>}} [opts]
+ * @returns {{available: boolean, warning: string|null}}
+ */
+export function resolveAssignmentAvailability(model, { eligibility = {}, claudeEntitlement = {} } = {}) {
+  if (!model) return { available: false, warning: null };
+
+  if (model.adapterId === "claude") {
+    const entitlement = claudeEntitlement[model.modelId];
+    if (entitlement?.status === ENTITLEMENT.DENIED) {
+      const reason = entitlement.reason ?? "denied";
+      return {
+        available: false,
+        warning: `Unavailable — your Claude plan denies this model (${reason})`
+      };
+    }
+    if (entitlement?.status === ENTITLEMENT.UNVERIFIED) {
+      return {
+        available: false,
+        warning: "Unavailable — model entitlement not verified (run /models --verify-access)"
+      };
+    }
+  }
+
+  const check = eligibility[model.adapterId];
+  if (check && check.ok === false) {
+    return {
+      available: false,
+      warning: `Unavailable — ${check.reason ?? "not eligible"}`
+    };
+  }
+  return { available: true, warning: null };
+}
 
 /**
  * A real, early heads-up — never fabricated, never re-deriving its own
@@ -580,8 +659,12 @@ export class CockpitView {
     const modelColumnWidth = this.teamModelColumnWidth([
       strategy.bootstrapAnalyst, strategy.orchestrator, ...projectTeam.map((entry) => entry.model)
     ]);
+    lines.push(theme.fg("muted", "Operational picks: the efficient model among eligible candidates for each role (quality leader shown when it differs)."));
     if (strategy.bootstrapAnalyst) lines.push(`${"Project Analyst".padEnd(18)} ${this.teamRoleLabel(strategy.bootstrapAnalyst, modelColumnWidth)}`);
-    if (strategy.orchestrator) lines.push(`${"Orchestrator".padEnd(18)} ${this.teamRoleLabel(strategy.orchestrator, modelColumnWidth)}`);
+    if (strategy.orchestrator) {
+      lines.push(`${"Orchestrator*".padEnd(18)} ${this.teamRoleLabel(strategy.orchestrator, modelColumnWidth)}`);
+      lines.push(theme.fg("muted", "  * Architect's quality pick — Kairo has no separate orchestrator capability profile yet."));
+    }
     // The real OPERATIONAL team (see buildProjectStrategy's own doc) —
     // never qualityTeam, which is comparative reference only. The overlay
     // (project-overlay.js) already shows projectTeam under this exact
@@ -589,14 +672,42 @@ export class CockpitView {
     // same label was the real, reported mismatch. qualityTeam only
     // remains as a fallback for a strategy persisted before projectTeam
     // existed (see applyProjectTeamOverride's own legacy-entry comment).
+    const eligibility = this.snapshot?.modelIntelligence?.eligibility ?? {};
+    const claudeEntitlement = this.snapshot?.modelIntelligence?.claudeEntitlement ?? {};
     for (const entry of projectTeam) {
       lines.push(`${entry.role.padEnd(18)} ${entry.model ? this.teamRoleLabel(entry.model, modelColumnWidth) : theme.fg("warning", "no eligible option")}`);
+      const extra = this.projectTeamCompactExtraLine(entry, strategy, { eligibility, claudeEntitlement });
+      if (extra) lines.push(theme.fg("muted", `  ${extra}`));
     }
     if (strategy.status === "suggested") lines.push(theme.fg("muted", "Suggested from real project analysis. Use /project approve to activate."));
     if (strategy.status === "stale") lines.push(theme.fg("warning", "Real evidence changed since approval — use /project refresh."));
     return { title: `PROJECT TEAM · ${project} · ${strategy.status.toUpperCase()}`, lines };
   }
 
+  /**
+   * At most one muted extra line for the compact PROJECT TEAM panel —
+   * only when it adds something the role row itself doesn't already say
+   * (quality leader differs, or a real availability warning). Same pick
+   * + available → null.
+   */
+  projectTeamCompactExtraLine(entry, strategy, { eligibility = {}, claudeEntitlement = {} } = {}) {
+    const availability = resolveAssignmentAvailability(entry?.model, { eligibility, claudeEntitlement });
+    if (availability.warning) return availability.warning;
+    if (!strategy?.qualityTeam || !entry?.model) return null;
+    const qualityEntry = strategy.qualityTeam.find((row) => row.role === entry.role);
+    if (!qualityEntry?.model) return null;
+    const samePick = qualityEntry.model.adapterId === entry.model.adapterId
+      && qualityEntry.model.modelId === entry.model.modelId;
+    if (samePick) return null;
+    const retention = entry.decisionEvidence?.retention;
+    const retentionPct = retention != null ? Math.round(retention * 100) : null;
+    const leaderLabel = this.aiTeamLabel(qualityEntry.model);
+    if (retentionPct != null) {
+      return `Quality leader: ${leaderLabel} — operational pick retains ${retentionPct}%`;
+    }
+    return `Quality leader: ${leaderLabel}`;
+  }
+
   /** Contextual key hints — shown in the dashboard's fixed zone, not the scrollable conversation. */
   renderFooterLines() {
     const row = this.selectedRow();
@@ -899,27 +1010,15 @@ export class CockpitView {
     return lines;
   }
 
-/** Plain-language description of what each role optimizes for — mirrors
-   * buildAiTeamRoleDefinitions()'s real compute functions in
-   * model-intelligence.js, never a per-model claim, so it never needs
-   * updating when the underlying models change. */
-  static ROLE_CAPABILITY_BLURB = {
-    Explorer: "general reasoning capability",
-    Architect: "general reasoning capability",
-    Builder: "coding capability",
-    Debugger: "reasoning and terminal-debugging capability",
-    Tester: "coding and terminal-execution capability",
-    Reviewer: "independent reasoning and coding review"
-  };
+  static ROLE_CAPABILITY_BLURB = ROLE_CAPABILITY_BLURB;
 
   /**
    * The default, human-readable `/models` output: per role, the selected
-   * model, why (the real distribution-policy reason when there is one,
-   * else the role's plain-language capability requirement), the
-   * EFFICIENT TEAM alternative when it actually differs, and the real
-   * fallback used if the selection becomes unavailable. Deliberately no
-   * raw metrics, percentages, internal ids, or source names — that detail
-   * moves to /models --evidence (aiTeamDetailLines()) instead.
+   * model, why (via explainTeamDecision — real reason or leader/blurb
+   * formulation), the EFFICIENT TEAM alternative when it actually differs,
+   * and the real fallback used if the selection becomes unavailable.
+   * Deliberately no raw metrics, percentages, internal ids, or source
+   * names — that detail moves to /models --evidence (aiTeamDetailLines()).
    */
   modelsExplainLines() {
     const intel = this.snapshot?.modelIntelligence;
@@ -930,7 +1029,8 @@ export class CockpitView {
     const leaderByRole = Object.fromEntries((intel.globalGuide?.capability ?? []).map((entry) => [entry.role, entry]));
     const freshness = intel.status === "live" ? "live" : `cached ${intel.age ?? "?"}`;
     const lines = [theme.fg("muted", `Evidence: ${freshness}`)];
-    aiTeam.forEach(({ role, primary, fallback, reason }, index) => {
+    aiTeam.forEach((entry, index) => {
+      const { role, primary, fallback } = entry;
       // A blank string here would get silently dropped once routed through
       // the persisted chat transcript (addTranscript trims and discards
       // empty text) — a visible divider is the only separator that
@@ -938,8 +1038,7 @@ export class CockpitView {
       if (index > 0) lines.push(theme.fg("muted", "·"));
       const availabilityNote = primary.available ? "" : " (currently unavailable)";
       lines.push(`${role.padEnd(10)} ${this.aiTeamLabel(primary)}${availabilityNote}`);
-      const why = reason ?? `Selected for ${CockpitView.ROLE_CAPABILITY_BLURB[role] ?? "this role's capability requirement"}.`;
-      lines.push(theme.fg("muted", `  ${why}`));
+      lines.push(theme.fg("muted", `  ${explainTeamDecision(entry)}`));
 
       // The uncoordinated individual leader (globalGuide) — evidence for
       // "what's honestly best with nothing else in play?", never the
@@ -984,15 +1083,18 @@ export class CockpitView {
    * evidence the Model Intelligence Foundation registry has for that exact
    * model. Never recalculates anything — every number here was already
    * computed during real selection. Shared by AI TEAM and EFFICIENT TEAM
-   * inside aiTeamDetailLines(); never called on its own.
+   * inside aiTeamDetailLines(); also reused by projectTeamEvidenceLines
+   * via the optional `extraLinesFor` hook (never forked).
    * @param {Array<object>} team
+   * @param {{extraLinesFor?: (entry: object) => string[]|null|undefined}} [options]
    */
-  teamEvidenceLines(team) {
+  teamEvidenceLines(team, { extraLinesFor } = {}) {
     const lines = [];
     const corroborationLine = (model) => (model.corroboration ?? [])
       .map((entry) => `${entry.metric}=${entry.value} (${entry.source})`)
       .join(" · ");
-    team.forEach(({ role, primary, fallback, reason, coverage, confidence, decisionEvidence }, index) => {
+    team.forEach((entry, index) => {
+      const { role, primary, fallback, reason, coverage, confidence, decisionEvidence } = entry;
       // A blank string here would get silently dropped once this line is
       // routed through the persisted chat transcript (addTranscript trims
       // and discards empty text) — a visible divider is the only separator
@@ -1067,10 +1169,76 @@ export class CockpitView {
       if (fallback) lines.push(theme.fg("muted", `  fallback ${this.aiTeamLabelWithProvider(fallback)}`));
       else if (!primary.available) lines.push(theme.fg("warning", "  no eligible fallback right now"));
       if (reason) lines.push(theme.fg("muted", `  ${reason}`));
+      if (extraLinesFor) {
+        for (const line of extraLinesFor(entry) ?? []) lines.push(line);
+      }
     });
     return lines;
   }
 
+  /**
+   * Thin adapter: maps strategy.projectTeam entries onto teamEvidenceLines'
+   * primary/fallback shape, resolving availability explicitly (projectModelRef
+   * has no `available`), and injecting quality-leader + entitlement warnings
+   * via extraLinesFor — never a forked evidence renderer.
+   * @param {object} strategy
+   * @param {{eligibility?: object, claudeEntitlement?: object}} [opts]
+   */
+  projectTeamEvidenceLines(strategy, { eligibility = {}, claudeEntitlement = {} } = {}) {
+    const projectTeam = strategy?.projectTeam ?? [];
+    const hasQualityTeam = Array.isArray(strategy?.qualityTeam);
+    const qualityByRole = new Map((strategy?.qualityTeam ?? []).map((row) => [row.role, row]));
+
+    const team = projectTeam.map((entry) => {
+      const primaryAvailability = resolveAssignmentAvailability(entry.model, { eligibility, claudeEntitlement });
+      const fallbackAvailability = entry.fallback
+        ? resolveAssignmentAvailability(entry.fallback, { eligibility, claudeEntitlement })
+        : null;
+      return {
+        role: entry.role,
+        primary: entry.model
+          ? { ...entry.model, available: primaryAvailability.available }
+          : { adapterId: "?", modelId: "?", displayName: "no eligible option", available: false },
+        fallback: entry.fallback
+          ? { ...entry.fallback, available: fallbackAvailability.available }
+          : null,
+        reason: entry.reason ?? null,
+        decisionEvidence: entry.decisionEvidence ?? null,
+        coverage: entry.coverage,
+        confidence: entry.confidence,
+        _availabilityWarning: primaryAvailability.warning,
+        _qualityEntry: qualityByRole.get(entry.role) ?? null
+      };
+    });
+
+    return this.teamEvidenceLines(team, {
+      extraLinesFor: (mapped) => {
+        const extra = [];
+        if (mapped._availabilityWarning) {
+          extra.push(theme.fg("warning", `  ${mapped._availabilityWarning}`));
+        }
+        if (!hasQualityTeam) return extra;
+        const qualityEntry = mapped._qualityEntry;
+        if (!qualityEntry?.model || !mapped.primary?.modelId) return extra;
+        const samePick = qualityEntry.model.adapterId === mapped.primary.adapterId
+          && qualityEntry.model.modelId === mapped.primary.modelId;
+        if (samePick) {
+          extra.push(theme.fg("muted", "  Also the quality leader for this role."));
+          return extra;
+        }
+        const retention = mapped.decisionEvidence?.retention;
+        const retentionPct = retention != null ? Math.round(retention * 100) : null;
+        const leaderLabel = this.aiTeamLabel(qualityEntry.model);
+        if (retentionPct != null) {
+          extra.push(theme.fg("muted", `  Quality leader: ${leaderLabel} — operational pick retains ${retentionPct}%`));
+        } else {
+          extra.push(theme.fg("muted", `  Quality leader: ${leaderLabel}`));
+        }
+        return extra;
+      }
+    });
+  }
+
   /**
    * `/models --evidence`: the full breakdown behind both AI TEAM and
    * EFFICIENT TEAM picks — real provider, primary, availability, fallback,

package/src/global/conversation/service.js

@@ -41,9 +41,15 @@ import { readArtificialAnalysisModels } from "../observability/artificial-analys
 import { readHuggingFaceLeaderboard } from "../observability/huggingface-leaderboard.js";
 import {
   DEFAULT_ENTITLEMENT_TTL_MS,
+  mergeEntitlementResults,
   readClaudeEntitlementCache,
-  resolveClaudeEntitlements
+  resolveClaudeEntitlements,
+  writeClaudeEntitlementCache
 } from "../observability/claude-entitlement-store.js";
+import {
+  ENTITLEMENT,
+  probeClaudeModelEntitlements
+} from "../observability/claude-model-entitlement.js";
 import {
   annotateWithRegistryEvidence, bestEfficientModelPerRoleGlobal, bestModelPerRole, bestModelPerRoleGlobal, buildAiTeam,
   buildEfficientTeam, scoreAvailableModels, summarizeCatalogCoverage
@@ -64,6 +70,35 @@ export const CONVERSATION_SCHEMA = "kairo.conversation/v1";
 // 30s default.
 const BOOTSTRAP_ANALYST_TIMEOUT_MS = 180_000;
 
+/** Max Claude entitlement probes per `/models --verify-access` sweep. */
+const CLAUDE_ENTITLEMENT_MAX_PROBES = 12;
+
+/**
+ * Cost statement printed before any Claude entitlement spawn. Economy is
+ * measured: denied probes cost $0; allowed ones about one cent each.
+ * @param {{ pendingCount?: number }} [options]
+ */
+export function buildClaudeEntitlementVerifyCostStatement({ pendingCount = 0 } = {}) {
+  const n = Math.max(0, Number(pendingCount) || 0);
+  if (n <= 0) {
+    return "No Claude models need access verification right now (denied probes cost $0; allowed ones about one cent each).";
+  }
+  return `About to verify ${n} Claude model${n === 1 ? "" : "s"}: models your plan denies cost $0; allowed ones cost about one cent each.`;
+}
+
+/**
+ * One-line preflight notice when unverified Claude models exist.
+ * @param {number} count
+ */
+export function buildUnverifiedClaudePreflightNotice(count) {
+  const n = Math.max(0, Number(count) || 0);
+  return `${n} modelos de Claude tienen acceso sin verificar — se pueden recomendar pero nunca lanzar automáticamente. Corré /models --verify-access para verificar (los que tu plan deniega cuestan $0; los permitidos, alrededor de un centavo cada uno).`;
+}
+
+function isPersistableEntitlementStatus(status) {
+  return status === ENTITLEMENT.ALLOWED || status === ENTITLEMENT.DENIED;
+}
+
 function publicPlan(record, execution = null) {
   const status = record.status ?? record;
   return {
@@ -352,6 +387,9 @@ export function createConversationService(deps = {}) {
   const readOpenCodeGoCached = createCachedProbe(readOpenCodeGoImpl, opencodeGoUsageTtlMs);
   const readOpenCodeStatsCached = createCachedProbe(readOpenCodeStatsImpl, opencodeUsageTtlMs);
   const readClaudeEntitlementCacheImpl = deps.readClaudeEntitlementCache ?? readClaudeEntitlementCache;
+  const writeClaudeEntitlementCacheImpl = deps.writeClaudeEntitlementCache ?? writeClaudeEntitlementCache;
+  const mergeEntitlementResultsImpl = deps.mergeEntitlementResults ?? mergeEntitlementResults;
+  const probeClaudeModelEntitlementsImpl = deps.probeClaudeModelEntitlements ?? probeClaudeModelEntitlements;
   const readClaudeEntitlementCacheCached = createCachedProbe(
     () => readClaudeEntitlementCacheImpl(homeDir), claudeEntitlementCacheTtlMs
   );
@@ -821,7 +859,92 @@ export function createConversationService(deps = {}) {
       const candidates = { scoredAll, eligibility, registry, providerCapacity, claudeEntitlement };
       const alternatives = computeBootstrapAnalystAlternatives(candidates);
       const analystCatalog = computeBootstrapAnalystCatalog({ ...candidates, unscoredModels });
-      return { profile, alternatives, candidates, analystCatalog, projectRoot };
+      const unverifiedCount = Object.values(claudeEntitlement).filter(
+        (entry) => entry?.status === ENTITLEMENT.UNVERIFIED
+      ).length;
+      const unverifiedClaudeNotice = unverifiedCount > 0
+        ? buildUnverifiedClaudePreflightNotice(unverifiedCount)
+        : null;
+      return { profile, alternatives, candidates, analystCatalog, projectRoot, unverifiedClaudeNotice };
+    },
+    /**
+     * `/models --verify-access [--refresh]`: the only service path that
+     * spawns `probeClaudeModelEntitlements`. Without refresh, only
+     * unverified / TTL-expired catalog ids are probed; with refresh, every
+     * catalog id is probed (still capped at maxProbes=12). Persist only when
+     * at least one allowed/denied result exists — an all-unverified sweep
+     * never invents evidence on disk.
+     *
+     * @param {object} args
+     * @param {string} args.cwd
+     * @param {boolean} [args.refresh]
+     * @param {(info: { pendingCount: number, pendingIds: string[], costStatement: string }) => (void|Promise<void>)} [args.beforeProbe]
+     *   Called after the probe set is known and BEFORE any spawn — app.js
+     *   prints the cost statement here.
+     * @param {(info: { modelId: string, index: number, total: number, result: object }) => void} [args.onProgress]
+     */
+    async verifyClaudeEntitlements({ cwd, refresh = false, beforeProbe = null, onProgress = null } = {}) {
+      const projectRoot = cwd ? await root(cwd) : null;
+      const catalog = readClaudeModelsImpl();
+      const catalogIds = (catalog.models ?? []).map((m) => m.id).filter(Boolean);
+      let auth = null;
+      try {
+        auth = await verifyClaudeSubscriptionAuthImpl({});
+      } catch {
+        auth = null;
+      }
+      const subscriptionType = auth?.subscriptionType ?? null;
+      const cache = await readClaudeEntitlementCacheImpl(homeDir);
+      const nowMs = now();
+      const ttlMs = deps.claudeEntitlementTtlMs ?? DEFAULT_ENTITLEMENT_TTL_MS;
+      const resolved = resolveClaudeEntitlements({
+        cache,
+        subscriptionType,
+        catalogIds,
+        now: nowMs,
+        ttlMs
+      });
+      const pendingIds = (refresh
+        ? catalogIds
+        : catalogIds.filter((id) => resolved[id]?.status === ENTITLEMENT.UNVERIFIED)
+      ).slice(0, CLAUDE_ENTITLEMENT_MAX_PROBES);
+      const costStatement = buildClaudeEntitlementVerifyCostStatement({ pendingCount: pendingIds.length });
+      if (typeof beforeProbe === "function") {
+        await beforeProbe({ pendingCount: pendingIds.length, pendingIds, costStatement });
+      }
+      if (pendingIds.length === 0) {
+        return {
+          probed: [],
+          results: [],
+          costStatement,
+          persisted: false,
+          pendingCount: 0,
+          refresh: Boolean(refresh),
+          subscriptionType
+        };
+      }
+      const results = await probeClaudeModelEntitlementsImpl({
+        modelIds: pendingIds,
+        maxProbes: CLAUDE_ENTITLEMENT_MAX_PROBES,
+        cwd: projectRoot ?? process.cwd(),
+        onProgress
+      });
+      const hasPersistable = results.some((result) => isPersistableEntitlementStatus(result?.status));
+      let persisted = false;
+      if (hasPersistable) {
+        const merged = mergeEntitlementResultsImpl(cache, { subscriptionType, results });
+        await writeClaudeEntitlementCacheImpl(homeDir, merged);
+        persisted = true;
+      }
+      return {
+        probed: pendingIds,
+        results,
+        costStatement,
+        persisted,
+        pendingCount: pendingIds.length,
+        refresh: Boolean(refresh),
+        subscriptionType
+      };
     },
     /**
      * `/project analyst quality|efficient --confirm` (ANALYZING -> SUGGESTED):

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