fix(bundles): keep the pin check's errors clean and fail on unknown versions

Run the unowned-component pin check inside the install try, so a raw
error from an unreadable registry becomes the usual BundlerError, and
treat an installed version that can't be read as a mismatch instead of
skipping the component.

Refs #4434

Assisted-by: Claude Code (model: Claude Opus 5.5, autonomous)

Author: kartsan03

docs/reference/bundles.md

@@ -69,7 +69,7 @@ specify bundle install <bundle_id | path>
 
 Installs a bundle's full component set through each primitive's machinery. The argument may be a catalog bundle id, or a local path to a built `.zip` artifact, a bundle directory, or a `bundle.yml` file; local sources install directly without consulting the catalog stack.
 
-If the current directory is not yet a Spec Kit project, `install` initializes one first so a fresh checkout reaches a working state in a single command. `--integration` selects the integration when initializing a new project, and confirms the target when a bundle pins a specific integration but the project's active integration can't be determined (missing or unreadable `.specify/integration.json`). It does **not** override an already-initialized project's active integration: if a bundle targets a different integration than the project's, install aborts with no changes. Integration-agnostic bundles inherit the project's active integration. Without `--refresh`, installation is idempotent — components already present are skipped. Components installed outside any bundle are skipped and never adopted, so their installed version must match the manifest pin; if it doesn't, install and refresh stop before changing anything and name the component, so you can remove it or install the pinned version yourself. On failure, no provenance record is written (a failed install records nothing), and the components installed during that run are removed on a best-effort basis — removal errors are swallowed, so partial on-disk state may remain.
+If the current directory is not yet a Spec Kit project, `install` initializes one first so a fresh checkout reaches a working state in a single command. `--integration` selects the integration when initializing a new project, and confirms the target when a bundle pins a specific integration but the project's active integration can't be determined (missing or unreadable `.specify/integration.json`). It does **not** override an already-initialized project's active integration: if a bundle targets a different integration than the project's, install aborts with no changes. Integration-agnostic bundles inherit the project's active integration. Without `--refresh`, installation is idempotent — components already present are skipped. Components installed outside any bundle are skipped and never adopted, so their installed version must match the manifest pin; if it doesn't, or can't be read, install and refresh stop before changing anything and name the component, so you can remove it or install the pinned version yourself. On failure, no provenance record is written (a failed install records nothing), and the components installed during that run are removed on a best-effort basis — removal errors are swallowed, so partial on-disk state may remain.
 
 A normal install rejects a change to an already-recorded bundle's version or owned component metadata (version, source, preset priority, or strategy), including removal of an owned component. This applies even if a local manifest keeps the same bundle version. Reordering unchanged components or adding new components does not require refresh. To apply changes to a local bundle without adding it to a catalog, pass the revised source with `--refresh`:
 

src/specify_cli/bundles/installer.py

@@ -132,11 +132,10 @@ def install_bundle(
         if r.bundle_id != plan.bundle_id
         for c in r.contributed_components
     }
-    _check_unowned_pins(project_root, plan, installer, prior_ours | other_tracked)
-
     contributed: list[ComponentRef] = []
     done: list[ComponentRef] = []
     try:
+        _check_unowned_pins(project_root, plan, installer, prior_ours | other_tracked)
         for component in plan.components:
             key = (component.kind, component.id)
             if installer.is_installed(project_root, component):
@@ -264,9 +263,9 @@ def _check_unowned_pins(
     A component tracked by no bundle is skipped and never refreshed (FR-022), so
     skipping it is only correct when it already has the pinned version.
     Otherwise the bundle record would advance while the project keeps running a
-    different version (#4434). Runs before any primitive is touched. Installers
-    without an ``installed_version`` hook, and components whose installed
-    version is unknown, are not checked.
+    different version (#4434). Runs before any primitive is touched. A component
+    whose installed version can't be read fails too, since it can't be shown to
+    match. Installers without an ``installed_version`` hook are not checked.
     """
     installed_version = getattr(installer, "installed_version", None)
     if not callable(installed_version):
@@ -278,11 +277,11 @@ def _check_unowned_pins(
         if not installer.is_installed(project_root, component):
             continue
         actual = installed_version(project_root, component)
-        if actual is not None and not same_version(actual, component.version):
-            mismatches.append(
-                f"{component.kind[:-1]} '{component.id}' to {component.version}, "
-                f"but {actual} is installed"
-            )
+        pinned = f"{component.kind[:-1]} '{component.id}' to {component.version}"
+        if actual is None:
+            mismatches.append(f"{pinned}, but its installed version is unknown")
+        elif not same_version(actual, component.version):
+            mismatches.append(f"{pinned}, but {actual} is installed")
     if mismatches:
         raise BundlerError(
             f"Bundle '{plan.bundle_id}' pins {'; '.join(mismatches)}. Bundles "

tests/specify_cli/bundles/test_installer.py

@@ -492,6 +492,7 @@ def test_refresh_does_not_touch_independently_installed_component(tmp_path: Path
     manifest = BundleManifest.from_dict(valid_manifest_dict())
     installer = FakeInstaller()
     installer.installed.add(("extensions", "ext-a"))
+    installer.versions[("extensions", "ext-a")] = "1.0.0"
 
     result = install_bundle(
         tmp_path, _plan(manifest), installer, manifest=manifest, refresh=True
@@ -516,6 +517,7 @@ def test_pre_existing_component_is_not_attributed_or_removed(tmp_path: Path):
     installer = FakeInstaller()
     # Pre-install ext-a independently — no bundle record references it yet.
     installer.installed.add(("extensions", "ext-a"))
+    installer.versions[("extensions", "ext-a")] = "1.0.0"
 
     install_bundle(tmp_path, _plan(manifest), installer, manifest=manifest)
 
@@ -572,6 +574,47 @@ def test_refresh_rejects_independently_installed_component_at_other_version(
     assert records_path(tmp_path).read_bytes() == original_record
 
 
+def test_install_rejects_independently_installed_component_of_unknown_version(
+    tmp_path: Path,
+):
+    # A registry entry without a readable version can't be shown to meet the
+    # pin, and skipping it would recreate the #4434 mismatch.
+    make_project(tmp_path)
+    manifest = BundleManifest.from_dict(valid_manifest_dict())
+    installer = FakeInstaller()
+    installer.installed.add(("extensions", "ext-a"))
+
+    with pytest.raises(
+        BundlerError, match=r"ext-a' to 1\.0\.0, but its installed version is unknown"
+    ):
+        install_bundle(tmp_path, _plan(manifest), installer, manifest=manifest)
+
+    assert installer.install_calls == []
+    assert not records_path(tmp_path).exists()
+
+
+def test_install_converts_raw_pin_check_exception_to_bundler_error(
+    tmp_path: Path,
+):
+    # The pin check runs before anything is installed, but an unreadable
+    # registry (e.g. _WorkflowKindManager failing closed at construction) must
+    # still surface as the clean BundlerError the CLI catches.
+    make_project(tmp_path)
+    manifest = BundleManifest.from_dict(valid_manifest_dict())
+    installer = FakeInstaller()
+    installer.installed.add(("extensions", "ext-a"))
+
+    def boom(project_root, component):
+        raise OSError("workflow registry unreadable")
+
+    installer.installed_version = boom
+    with pytest.raises(BundlerError, match="workflow registry unreadable"):
+        install_bundle(tmp_path, _plan(manifest), installer, manifest=manifest)
+
+    assert installer.install_calls == []
+    assert not records_path(tmp_path).exists()
+
+
 def test_independently_installed_component_at_pinned_version_stays_unowned(
     tmp_path: Path,
 ):