tirtc-device-builder 0.7.0 → 0.7.2

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Codex workflows for building and validating TiRTC device firmware across supported chip platforms.",
   "author": {
     "name": "TangeAI",

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 This project follows Semantic Versioning.
 
+## 0.7.2
+
+- Require the selected managed ESP32 Device Kit manifest to match the pinned Kit version; ignore stale managed references instead of reporting an older structurally complete Kit as ready.
+- Make Doctor validate an exact `--expected-kit` version and persist the version actually read from the selected Kit rather than the desired version.
+- Ship a verifiable Skill `VERSION` marker, include it in setup readiness and package tests, and remove the inapplicable Plugin-version prerequisite from the portable clean-room prompt.
+
+## 0.7.1
+
+- Split clean-room bootstrap from Skill execution: install or replace the pinned Skill before Codex starts, restart the session, then run read-only version and Doctor checks before generation.
+
 ## 0.7.0
 
 - Separate the platform/Web video contract (MJPEG, H.264, and H.265 on stream 11) from the single codec profile selected by a board; keep the LCKFB ESP32-S3 adapter on MJPEG without narrowing platform capability.

package/README.md

@@ -881,8 +881,8 @@ metadata 中的版本、标签、上游 commit 和期望 SHA-256 必须与本地
 
 ```bash
 npm test
-git tag -a v0.7.0 -m "v0.7.0"
-git push origin v0.7.0
+git tag -a v0.7.2 -m "v0.7.2"
+git push origin v0.7.2
 ```
 
 不要重复发布已经存在的 npm 版本。版本变化同步更新 `package.json`、`.codex-plugin/plugin.json` 和发布说明。

package/bin/setup-esp32.js

@@ -33,6 +33,8 @@ const REQUIRED_SDK_FILES = [
   join("lib", "libTiRTC.a"),
   join("manifest", "build-contract.env"),
 ];
+const DEVICE_KIT_MANIFEST = "manifest.json";
+const SKILL_VERSION_FILE = "VERSION";
 
 function setupRootFrom(environment) {
   return resolve(
@@ -199,14 +201,71 @@ function discoverThingConnectRoot(start) {
   }
 }
 
-function thingConnectReady(root) {
-  if (!root || !existsSync(join(root, GENERATOR_PATH))) {
-    return false;
+function readTrimmedFile(path) {
+  if (!existsSync(path)) {
+    return null;
   }
-  const sdk = join(root, SDK_PATH);
-  return REQUIRED_SDK_FILES.every((relative) =>
-    existsSync(join(sdk, relative)),
+  try {
+    const value = readFileSync(path, "utf8").trim();
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+export function inspectDeviceKit(root) {
+  const manifestPath = root ? join(root, DEVICE_KIT_MANIFEST) : null;
+  let manifestPresent = false;
+  let version = null;
+  let manifestError = null;
+  if (manifestPath && existsSync(manifestPath)) {
+    manifestPresent = true;
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+      if (
+        manifest &&
+        typeof manifest === "object" &&
+        typeof manifest.kit_version === "string" &&
+        manifest.kit_version.trim()
+      ) {
+        version = manifest.kit_version.trim();
+      } else {
+        manifestError = "manifest.json does not declare kit_version";
+      }
+    } catch (error) {
+      manifestError = `invalid manifest.json: ${
+        error instanceof Error ? error.message : String(error)
+      }`;
+    }
+  }
+
+  const generatorReady = Boolean(
+    root && existsSync(join(root, GENERATOR_PATH)),
   );
+  const sdk = root ? join(root, SDK_PATH) : null;
+  const sdkReady = Boolean(
+    sdk &&
+      REQUIRED_SDK_FILES.every((relative) => existsSync(join(sdk, relative))),
+  );
+  const structureReady = generatorReady && sdkReady;
+  const versionCompatible =
+    !manifestPresent ||
+    (manifestError === null && version === ESP32_KIT.version);
+
+  return {
+    expectedVersion: ESP32_KIT.version,
+    manifestError,
+    manifestPath,
+    manifestPresent,
+    ready: structureReady && versionCompatible,
+    structureReady,
+    version,
+    versionCompatible,
+  };
+}
+
+export function readSkillVersion(skillRoot) {
+  return readTrimmedFile(join(skillRoot, SKILL_VERSION_FILE));
 }
 
 function readConfig(path) {
@@ -358,7 +417,7 @@ function writeManagedEnvironment(context, packageVersion) {
     idf_version: PINNED_IDF_VERSION,
     idf_dir: context.idfDir,
     idf_tools_path: context.idfToolsPath,
-    device_kit_version: ESP32_KIT.version,
+    device_kit_version: context.deviceKit.version,
     device_kit_root: context.thingConnectRoot,
     thing_connect_root: context.thingConnectRoot,
     skills_dir: context.skillsDir,
@@ -418,11 +477,31 @@ function setupContext(options, runtime) {
       requestedThingConnect = managedThingConnect;
     }
   }
-  const normalizedThingConnect = normalizeThingConnectRoot(
+  let normalizedThingConnect = normalizeThingConnectRoot(
     requestedThingConnect,
   );
-  const thingConnectRoot =
+  let thingConnectRoot =
     normalizedThingConnect || resolve(requestedThingConnect);
+  let deviceKit = inspectDeviceKit(thingConnectRoot);
+  let thingConnectFallback = null;
+  const versionedKitMismatch =
+    deviceKit.manifestPresent && !deviceKit.versionCompatible;
+  const staleManagedReference =
+    (thingConnectSource === "TIRTC_THING_CONNECT_ROOT" ||
+      thingConnectSource === "managed config") &&
+    !deviceKit.structureReady;
+  if (
+    thingConnectSource !== "explicit --thing-connect-root" &&
+    (versionedKitMismatch || staleManagedReference)
+  ) {
+    thingConnectFallback = `${thingConnectSource}: ${thingConnectRoot}`;
+    requestedThingConnect = managedThingConnect;
+    thingConnectSource = "managed Device Kit";
+    normalizedThingConnect = normalizeThingConnectRoot(requestedThingConnect);
+    thingConnectRoot =
+      normalizedThingConnect || resolve(requestedThingConnect);
+    deviceKit = inspectDeviceKit(thingConnectRoot);
+  }
 
   const active = currentIdf(environment);
   let idfDir;
@@ -459,6 +538,8 @@ function setupContext(options, runtime) {
     ? { ...active, directoryReady: directoryIdf.ready }
     : { ...directoryIdf, root: idfDir, directoryReady: directoryIdf.ready };
 
+  const skillTarget = join(options.skillsDir, runtime.platform.skill);
+  const skillVersion = readSkillVersion(skillTarget);
   return {
     activeIdf: active,
     configPath,
@@ -468,9 +549,17 @@ function setupContext(options, runtime) {
     idfToolsPath,
     managedThingConnect,
     rootDir: options.rootDir,
-    skillTarget: join(options.skillsDir, runtime.platform.skill),
+    deviceKit,
+    skillReady:
+      existsSync(join(skillTarget, "SKILL.md")) &&
+      skillVersion === runtime.packageVersion,
+    skillTarget,
+    skillVersion,
     skillsDir: options.skillsDir,
-    thingConnectReady: thingConnectReady(thingConnectRoot),
+    thingConnectFallback,
+    thingConnectManaged:
+      resolve(thingConnectRoot) === resolve(managedThingConnect),
+    thingConnectReady: deviceKit.ready,
     thingConnectRoot,
     thingConnectSource,
   };
@@ -479,15 +568,29 @@ function setupContext(options, runtime) {
 function printState(context, runtime) {
   printCheck("INFO", "setup root", context.rootDir);
   printCheck(
-    existsSync(join(context.skillTarget, "SKILL.md")) ? "PASS" : "MISS",
+    context.skillReady ? "PASS" : "MISS",
     "Codex Skill",
-    context.skillTarget,
+    `${context.skillTarget} (version ${
+      context.skillVersion || "missing"
+    }; expected ${runtime.packageVersion})`,
   );
+  const kitVersion = context.deviceKit.manifestPresent
+    ? context.deviceKit.version || "invalid manifest"
+    : "legacy workspace (unversioned)";
   printCheck(
     context.thingConnectReady ? "PASS" : "MISS",
     "ESP32 Device Kit",
-    `${context.thingConnectRoot} (${context.thingConnectSource})`,
+    `${context.thingConnectRoot} (${context.thingConnectSource}; version ${
+      kitVersion
+    }; expected ${ESP32_KIT.version})`,
   );
+  if (context.thingConnectFallback) {
+    printCheck(
+      "INFO",
+      "ignored stale Kit reference",
+      context.thingConnectFallback,
+    );
+  }
   printCheck(
     context.idf.ready ? "PASS" : "MISS",
     "ESP-IDF",
@@ -534,10 +637,19 @@ function printSystemDependencyHelp(missing) {
 
 function installSkill(options, context, runtime) {
   const present = existsSync(join(context.skillTarget, "SKILL.md"));
-  if (present && !options.forceSkill) {
-    console.log(`SKIP  Codex Skill already exists: ${context.skillTarget}`);
+  if (present && context.skillReady && !options.forceSkill) {
+    console.log(
+      `SKIP  Codex Skill ${runtime.packageVersion} already exists: ${context.skillTarget}`,
+    );
     return;
   }
+  if (present && !options.forceSkill) {
+    throw new Error(
+      `Codex Skill at ${context.skillTarget} has version ${
+        context.skillVersion || "missing"
+      }, expected ${runtime.packageVersion}; rerun with --force-skill to replace it`,
+    );
+  }
   const args = [
     runtime.cliPath,
     "install",
@@ -560,9 +672,14 @@ function installDeviceKit(options, context, runtime) {
     );
     return context.thingConnectRoot;
   }
-  if (context.thingConnectSource !== "managed Device Kit") {
+  if (!context.thingConnectManaged) {
+    const reason =
+      context.deviceKit.manifestError ||
+      (context.deviceKit.manifestPresent
+        ? `version ${context.deviceKit.version || "missing"}; expected ${ESP32_KIT.version}`
+        : "missing generator or TiRTC SDK");
     throw new Error(
-      `${context.thingConnectSource} does not contain a complete ESP32 Device Kit: ${context.thingConnectRoot}`,
+      `${context.thingConnectSource} is not a compatible ESP32 Device Kit (${reason}): ${context.thingConnectRoot}`,
     );
   }
   if (existsSync(context.managedThingConnect)) {
@@ -577,9 +694,10 @@ function installDeviceKit(options, context, runtime) {
   }
   runOrThrow(process.execPath, args, { environment: runtime.environment });
   const root = normalizeThingConnectRoot(context.managedThingConnect);
-  if (!thingConnectReady(root)) {
+  const installedKit = inspectDeviceKit(root);
+  if (!installedKit.ready || installedKit.version !== ESP32_KIT.version) {
     throw new Error(
-      `installed ESP32 Device Kit is missing its generator or TiRTC SDK: ${context.managedThingConnect}`,
+      `installed ESP32 Device Kit is incomplete or has the wrong version: ${context.managedThingConnect}`,
     );
   }
   return root;
@@ -658,6 +776,9 @@ function runDoctor(context, runtime) {
     context.thingConnectRoot,
     "--require-workspace",
   ];
+  if (context.deviceKit.manifestPresent) {
+    args.push("--expected-kit", ESP32_KIT.version);
+  }
   let result;
   if (context.idfDir && existsSync(join(context.idfDir, "export.sh"))) {
     result = activatedResult(
@@ -691,7 +812,7 @@ function runDoctor(context, runtime) {
 
 function isReady(context) {
   return (
-    existsSync(join(context.skillTarget, "SKILL.md")) &&
+    context.skillReady &&
     context.thingConnectReady &&
     context.idf.ready
   );
@@ -729,7 +850,7 @@ export function runEsp32Setup(args, input) {
     if (!isReady(context)) {
       console.log("OVERALL: NEEDS_SETUP");
       console.log(
-        "NEXT: npx tirtc-device-builder@latest setup esp32 --install",
+        `NEXT: npx tirtc-device-builder@${runtime.packageVersion} setup esp32 --install`,
       );
       return 1;
     }
@@ -756,7 +877,12 @@ export function runEsp32Setup(args, input) {
   try {
     installSkill(options, context, runtime);
     const thingConnectRoot = installDeviceKit(options, context, runtime);
-    context = { ...context, thingConnectRoot, thingConnectReady: true };
+    context = {
+      ...context,
+      deviceKit: inspectDeviceKit(thingConnectRoot),
+      thingConnectRoot,
+      thingConnectReady: true,
+    };
     installIdf(context, runtime);
     context = setupContext(options, {
       ...runtime,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Install and run TiRTC device-development skills for Codex.",
   "license": "MIT",
   "author": {

package/skills/tirtc-esp32-builder/SKILL.md

@@ -9,9 +9,9 @@ Turn board evidence into an evidence-backed ESP-IDF project. Treat the Hardware
 
 ## Start
 
-1. Read [environment.md](references/environment.md). For a first-time setup or a request to check/install prerequisites, prefer `npx tirtc-device-builder@latest setup esp32`. Run its `--install` mode only when the user explicitly authorizes installation at the displayed destinations. The installer may create user-space files but never grants permission for `sudo` or persistent shell-profile edits.
-2. Locate the versioned ESP32 Device Kit root containing `device-sim/` using the explicit input, `TIRTC_THING_CONNECT_ROOT`, the managed setup configuration, or workspace discovery. Treat its manifest and packaged protocol documents as the generation facts. If the user explicitly supplies a full ThingConnect source workspace, also read its applicable `AGENTS.md`.
-3. Run the Doctor through the managed environment helper when one exists; otherwise run `python3 <skill-dir>/scripts/doctor.py --expected-idf 5.5 --target esp32s3`. Add `--require-workspace` when generation or repository reference documents are needed; a self-contained generated project can instead resolve its bundled SDK through `--project`. Resolve every required failure before claiming build readiness.
+1. Read this Skill's `VERSION` file and [environment.md](references/environment.md). Record the `VERSION` value as the installed Skill version; never infer it from the prompt or an npm command run elsewhere. For a first-time setup or a request to check/install prerequisites, prefer `npx tirtc-device-builder@latest setup esp32`. Run its `--install` mode only when the user explicitly authorizes installation at the displayed destinations. The installer may create user-space files but never grants permission for `sudo` or persistent shell-profile edits.
+2. Locate the versioned ESP32 Device Kit root containing `device-sim/` using the explicit input, `TIRTC_THING_CONNECT_ROOT`, the managed setup configuration, or workspace discovery. For a managed Kit, read `manifest.json`, require its exact expected `kit_version`, and treat its manifest and packaged protocol documents as generation facts. An older but structurally complete Kit is not compatible. If the user explicitly supplies an unversioned full ThingConnect source workspace, treat it as legacy input and also read its applicable `AGENTS.md`.
+3. Run the Doctor through the managed environment helper when one exists; otherwise run `python3 <skill-dir>/scripts/doctor.py --expected-idf 5.5 --target esp32s3`. Add `--expected-kit <kit-version> --require-workspace` for managed-Kit generation; a self-contained generated project can instead resolve its bundled SDK through `--project`. Resolve every required failure before claiming build readiness.
 4. Read [workflow.md](references/workflow.md). Select the registered-board, new-board intake, or existing-project branch. The branch is selected when every supplied artifact has been accounted for and the exact board revision is known or explicitly unresolved.
 5. Read [hardware-ir.md](references/hardware-ir.md) when a Hardware IR must be created or updated. New intake uses schema v2; schema v1 remains readable for existing H.264 projects. Record a source and verification level for every hardware fact that affects a requested feature.
 6. Run `python3 <skill-dir>/scripts/hardware_ir.py validate <hardware-ir.json>` and then `assess --phase intake --strict`. `READY_TO_PORT` means the evidence is sufficient to design the adapter without guessing wiring or changing an unapproved public contract; it does not require a final ELF or runtime measurements.

package/skills/tirtc-esp32-builder/VERSION

@@ -0,0 +1 @@
+0.7.2

package/skills/tirtc-esp32-builder/assets/lckfb-szpi-esp32s3-portable-prompt.md

@@ -2,13 +2,24 @@ $tirtc-esp32-builder
 
 请在当前工作区完成一次立创·实战派 ESP32-S3 的 ThingConnect TiRTC clean-room L-1/L0/L1 接入验证。
 
-这是 Skill、提示词和开发板资料的独立有效性测试。允许访问外网。先运行：
+这是 Skill、提示词和开发板资料的独立有效性测试。允许访问外网。
+
+前置条件（必须由开发者在启动本次 Codex 会话前完成，不属于本提示词内的操作）：
+
+```bash
+npx --yes tirtc-device-builder@0.7.2 setup esp32 --install --force-skill
+```
+
+该命令只允许在当前用户目录安装固定版本的 Skill、managed ESP32 Device Kit、ESP-IDF 和工具链；禁止 sudo、系统级包变更和修改 shell profile。安装完成后，开发者必须关闭原 Codex 会话，再从本 clean-room 工作区启动一个新会话，然后粘贴本提示词。
+
+本轮第一步先只读运行：
 
 ```bash
-npx --yes tirtc-device-builder@0.7.0 setup esp32 --install
+npx --yes tirtc-device-builder@0.7.2 --version
+npx --yes tirtc-device-builder@0.7.2 setup esp32
 ```
 
-允许该命令在当前用户目录安装固定版本的 Skill、managed ESP32 Device Kit、ESP-IDF 和工具链；禁止 sudo、系统级包变更和修改 shell profile。安装后必须使用 managed 环境继续执行。
+必须根据命令的实际输出和本机文件确认：npm 包为 0.7.2、已安装 Skill 的 `VERSION` 为 0.7.2、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.1，并且 Doctor 对 `--expected-kit 1.1.1` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
 
 工作区与 clean-room 边界：
 - 将启动 Codex 时的当前目录定义为 `WORKSPACE_ROOT`。

package/skills/tirtc-esp32-builder/references/environment.md

@@ -16,7 +16,7 @@ The automatic branch never runs `sudo` or modifies a persistent shell profile. W
 When `<setup-root>/env.sh` exists, use it only as an activation prefix for the current command:
 
 ```bash
-bash -lc '. "<setup-root>/env.sh" && python3 "<skill-dir>/scripts/doctor.py" --expected-idf 5.5 --target esp32s3 --require-workspace'
+bash -lc '. "<setup-root>/env.sh" && python3 "<skill-dir>/scripts/doctor.py" --expected-idf 5.5 --expected-kit 1.1.1 --target esp32s3 --require-workspace'
 ```
 
 The helper contains paths, not device or network credentials. Read `<setup-root>/config.json` when exact managed paths are needed; the environment helper does not authorize unrelated downloads, shell-profile changes, flashing, or credential writes.
@@ -26,6 +26,7 @@ Run the doctor before generation, build, flash, or monitor:
 ```bash
 python3 <skill-dir>/scripts/doctor.py \
   --expected-idf 5.5 \
+  --expected-kit 1.1.1 \
   --target esp32s3 \
   --require-workspace
 ```
@@ -34,7 +35,11 @@ Add `--project <generated-project>` after generation so the doctor can compare `
 
 ## ESP32 Device Kit
 
-The automatic setup downloads a versioned minimal Kit instead of cloning the ThingConnect server repository. Resolve the generation root in this order:
+The automatic setup downloads a versioned minimal Kit instead of cloning the ThingConnect server repository. A managed Kit is ready only when its generator and SDK files exist and `manifest.json` declares the exact pinned `kit_version`. A stale environment or managed configuration that points at an older Kit is ignored in favor of the current versioned managed path. The setup configuration records the version read from that manifest; it never substitutes the desired version for the actual one.
+
+The installed Skill has its own `<skill-dir>/VERSION` marker. Setup requires it to equal the npm package version and reports both values. Replacing a missing or mismatched marker requires the explicit `--install --force-skill` flow and a new Codex session.
+
+For an explicitly selected legacy workspace, omit `--expected-kit`; otherwise resolve the generation root in this order:
 
 1. an explicit `--thing-connect-root <path>`;
 2. `TIRTC_THING_CONNECT_ROOT`;

package/skills/tirtc-esp32-builder/scripts/doctor.py

@@ -27,6 +27,7 @@ GENERATOR_RELATIVE_PATH = Path("device-sim/scripts/create_esp32_project.py")
 DEFAULT_SDK_RELATIVE_PATH = Path(
     "device-sim/sdk/espressif-esp32s3/2.3.0"
 )
+DEVICE_KIT_MANIFEST = "manifest.json"
 
 
 def check(name: str, status: str, detail: str, required: bool = True) -> dict[str, Any]:
@@ -166,6 +167,43 @@ def normalize_thing_connect_root(candidate: Path) -> Path | None:
     return None
 
 
+def inspect_device_kit(root: Path | None) -> dict[str, str | bool | None]:
+    """Read the managed Kit identity without rejecting legacy workspaces."""
+    if root is None:
+        return {
+            "manifest_present": False,
+            "version": None,
+            "error": "Device Kit root is unresolved",
+        }
+    manifest_path = root / DEVICE_KIT_MANIFEST
+    if not manifest_path.is_file():
+        return {
+            "manifest_present": False,
+            "version": None,
+            "error": None,
+        }
+    try:
+        payload = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return {
+            "manifest_present": True,
+            "version": None,
+            "error": f"invalid {manifest_path}: {exc}",
+        }
+    version = payload.get("kit_version") if isinstance(payload, dict) else None
+    if not isinstance(version, str) or not version.strip():
+        return {
+            "manifest_present": True,
+            "version": None,
+            "error": f"{manifest_path} does not declare kit_version",
+        }
+    return {
+        "manifest_present": True,
+        "version": version.strip(),
+        "error": None,
+    }
+
+
 def find_thing_connect_root(
     explicit: Path | None,
     project: Path | None,
@@ -273,27 +311,51 @@ def diagnose(args: argparse.Namespace) -> dict[str, Any]:
         args.thing_connect_root,
         args.project,
     )
-    workspace_status = "PASS" if thing_connect_root else (
-        "FAIL" if args.require_workspace else "WARN"
-    )
+    kit_identity = inspect_device_kit(thing_connect_root)
+    kit_error = kit_identity["error"]
+    actual_kit = kit_identity["version"]
+    if thing_connect_root is None:
+        workspace_status = "FAIL" if args.require_workspace or args.expected_kit else "WARN"
+        workspace_detail = (
+            f"not found; pass --thing-connect-root or set {THING_CONNECT_ENV}"
+        )
+    elif args.expected_kit and not kit_identity["manifest_present"]:
+        workspace_status = "FAIL"
+        workspace_detail = (
+            f"{thing_connect_root} ({thing_connect_source}) is an unversioned legacy "
+            f"workspace; expected managed Device Kit {args.expected_kit}"
+        )
+    elif kit_error:
+        workspace_status = "FAIL"
+        workspace_detail = str(kit_error)
+    elif args.expected_kit and actual_kit != args.expected_kit:
+        workspace_status = "FAIL"
+        workspace_detail = (
+            f"version {actual_kit or 'missing'} at {thing_connect_root} "
+            f"({thing_connect_source}); expected {args.expected_kit}"
+        )
+    else:
+        workspace_status = "PASS"
+        version_detail = (
+            f"version {actual_kit}"
+            if actual_kit
+            else "unversioned legacy workspace"
+        )
+        workspace_detail = (
+            f"{version_detail} at {thing_connect_root} ({thing_connect_source})"
+        )
     checks.append(
         check(
             "ESP32 Device Kit",
             workspace_status,
-            (
-                f"{thing_connect_root} ({thing_connect_source})"
-                if thing_connect_root
-                else (
-                    f"not found; pass --thing-connect-root or set {THING_CONNECT_ENV}"
-                )
-            ),
-            required=args.require_workspace,
+            workspace_detail,
+            required=args.require_workspace or bool(args.expected_kit),
         )
     )
-    if args.require_workspace and thing_connect_root is None:
+    if (args.require_workspace or args.expected_kit) and workspace_status == "FAIL":
         next_actions.append(
-            "Run setup esp32 --install or pass an existing Device Kit path with "
-            "--thing-connect-root."
+            "Run setup esp32 --install to select the pinned managed Device Kit, or "
+            "pass a matching Kit path with --thing-connect-root."
         )
 
     sdk_dir, sdk_source = resolve_sdk_dir(
@@ -390,6 +452,8 @@ def diagnose(args: argparse.Namespace) -> dict[str, Any]:
     return {
         "overall": overall,
         "expected_idf": args.expected_idf,
+        "expected_kit": args.expected_kit,
+        "device_kit_version": actual_kit,
         "target": args.target,
         "thing_connect_root": (
             str(thing_connect_root) if thing_connect_root is not None else None
@@ -414,6 +478,10 @@ def parse_args() -> argparse.Namespace:
         description="Check ESP-IDF, target tools, TiRTC SDK, project contract, and serial access."
     )
     parser.add_argument("--expected-idf", default="5.5")
+    parser.add_argument(
+        "--expected-kit",
+        help="require an exact managed ESP32 Device Kit manifest version",
+    )
     parser.add_argument("--target", default="esp32s3")
     parser.add_argument("--idf-py", type=Path)
     parser.add_argument("--thing-connect-root", type=Path)