From 15f438cb84620a7f37db23c141d11b22cb14c253 Mon Sep 17 00:00:00 2001
From: Christopher <christso@gmail.com>
Date: Fri, 17 Apr 2026 00:07:48 +0000
Subject: [PATCH 1/2] feat(cli): add version check to studio/serve commands

Enforce `required_version` from `.agentv/config.yaml` before starting
Studio so the dashboard matches `agentv eval` behavior. Interactive
TTY prompts to update; non-interactive warns to stderr and continues.

Closes #1128
---
 apps/cli/src/commands/results/serve.ts | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/apps/cli/src/commands/results/serve.ts b/apps/cli/src/commands/results/serve.ts
index 4851f11b..3a20d2b9 100644
--- a/apps/cli/src/commands/results/serve.ts
+++ b/apps/cli/src/commands/results/serve.ts
@@ -37,14 +37,17 @@ import {
   discoverBenchmarks,
   getBenchmark,
   loadBenchmarkRegistry,
+  loadConfig,
   removeBenchmark,
 } from '@agentv/core';
 import type { Context } from 'hono';
 import { Hono } from 'hono';
 
+import { enforceRequiredVersion } from '../../version-check.js';
 import { parseJsonlResults } from '../eval/artifact-writer.js';
 import { resolveRunManifestPath } from '../eval/result-layout.js';
 import { loadRunCache, resolveRunCacheFile } from '../eval/run-cache.js';
+import { findRepoRoot } from '../eval/shared.js';
 import { listResultFiles } from '../inspect/utils.js';
 import { registerEvalRoutes } from './eval-runner.js';
 import {
@@ -1449,6 +1452,18 @@ export const resultsServeCommand = command({
       return;
     }
 
+    // ── Version check ────────────────────────────────────────────────
+    // Enforce `required_version` from .agentv/config.yaml so Studio/serve
+    // match `agentv eval` behavior. Same prompt in TTY, warn+continue
+    // otherwise. Single-project scope only — multi-project deployments
+    // (one agentv serving repos with differing requirements) are not
+    // covered here (see GitHub #1127 for per-project local installs).
+    const repoRoot = await findRepoRoot(cwd);
+    const yamlConfig = await loadConfig(path.join(cwd, '_'), repoRoot);
+    if (yamlConfig?.required_version) {
+      await enforceRequiredVersion(yamlConfig.required_version);
+    }
+
     // ── Determine multi-project mode ────────────────────────────────
     const registry = loadBenchmarkRegistry();
     const { isMultiProject, showMultiWarning } = resolveDashboardMode(registry.benchmarks.length, {

From f78f824260b0ca9b170916c8b248396d58fecd46 Mon Sep 17 00:00:00 2001
From: Christopher <christso@gmail.com>
Date: Fri, 17 Apr 2026 00:23:19 +0000
Subject: [PATCH 2/2] docs(cli): document version check in studio/serve file
 header

Address review feedback: reflect the new startup-time version
enforcement in the module's header JSDoc, and reword the inline
comment to describe the multi-project limitation without referencing
an external issue number.
---
 apps/cli/src/commands/results/serve.ts | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/apps/cli/src/commands/results/serve.ts b/apps/cli/src/commands/results/serve.ts
index 3a20d2b9..eeb3a4d6 100644
--- a/apps/cli/src/commands/results/serve.ts
+++ b/apps/cli/src/commands/results/serve.ts
@@ -19,6 +19,10 @@
  * variants. They share handler functions via DataContext, differing only in
  * how searchDir is resolved.
  *
+ * Before starting the server, the command enforces `required_version` from
+ * the cwd's `.agentv/config.yaml` (single-project scope) via
+ * `enforceRequiredVersion()`, matching the behavior of `agentv eval`.
+ *
  * Exported functions (for testing):
  *   - resolveSourceFile(source, cwd) — resolves a run manifest path
  *   - loadResults(content) — parses JSONL into EvaluationResult[]
@@ -1455,9 +1459,9 @@ export const resultsServeCommand = command({
     // ── Version check ────────────────────────────────────────────────
     // Enforce `required_version` from .agentv/config.yaml so Studio/serve
     // match `agentv eval` behavior. Same prompt in TTY, warn+continue
-    // otherwise. Single-project scope only — multi-project deployments
-    // (one agentv serving repos with differing requirements) are not
-    // covered here (see GitHub #1127 for per-project local installs).
+    // otherwise. Single-project scope only — when one agentv instance
+    // serves multiple repos with differing version requirements, a
+    // per-project local install is required instead.
     const repoRoot = await findRepoRoot(cwd);
     const yamlConfig = await loadConfig(path.join(cwd, '_'), repoRoot);
     if (yamlConfig?.required_version) {