fix(manifest): document OS errors on record_existing + filter orphan recovered_files on load

Round 9 — addresses Copilot review on PR #2483:

1. record_existing's docstring now documents OSError/PermissionError as
   possible raises (in addition to ValueError) — the implementation has
   always been able to raise them from is_symlink, is_file, or the
   file-read used to hash, but the contract did not reflect that.
   Callers should be prepared for both surfaces.

2. load() now filters recovered_files entries that don't correspond to
   keys in files. An externally-edited or partially-corrupted manifest
   can deserialize with orphan recovered paths; rather than reject the
   whole manifest (too strict on the upgrade path), we drop the orphans
   and let the inconsistency self-correct on the next save(). is_recovered
   then returns the truthful False for the orphan.

Tests: new test_load_filters_recovered_files_not_in_files asserting an
orphan recovered entry is dropped on load.

Author: eldar702

src/specify_cli/integrations/manifest.py

@@ -169,6 +169,12 @@ def record_existing(self, rel_path: str | Path, *, recovered: bool = False) -> N
                 non-file path cannot be silently recorded — its hash would
                 be meaningless and ``check_modified``/``uninstall`` would
                 treat the entry as permanently broken.
+            OSError: if the underlying filesystem call (``is_symlink``,
+                ``is_file``, or the file-read used to compute the hash)
+                fails — for example a ``PermissionError`` on the path.
+                Callers should be prepared to handle ``OSError`` (and its
+                subclasses such as ``PermissionError``) in addition to
+                ``ValueError``.
         """
         rel = Path(rel_path)
         # Cheap lexical pre-check first so absolute / parent-traversal paths
@@ -423,6 +429,10 @@ def load(cls, key: str, project_root: Path) -> IntegrationManifest:
                 "list of string paths"
             )
         inst._recovered_files = set(recovered)
+        # Drop any recovered_files entries that don't correspond to tracked
+        # files — defensive against externally-edited or partially-corrupted
+        # manifests. Inconsistent state self-corrects on next save().
+        inst._recovered_files &= set(inst._files.keys())
 
         stored_key = data.get("integration", "")
         if stored_key and stored_key != key:

tests/integrations/test_manifest.py

@@ -297,6 +297,24 @@ def test_load_invalid_json_raises(self, tmp_path):
         with pytest.raises(ValueError, match="invalid JSON"):
             IntegrationManifest.load("bad", tmp_path)
 
+    def test_load_filters_recovered_files_not_in_files(self, tmp_path):
+        # Finding B (Round-9): a recovered_files entry referencing a path
+        # not present in files indicates an internally-inconsistent manifest
+        # (e.g. external edit). load() filters those entries silently so the
+        # manifest self-heals on next save(); is_recovered then returns the
+        # truthful False for the orphan.
+        path = tmp_path / ".specify" / "integrations" / "test.manifest.json"
+        path.parent.mkdir(parents=True)
+        path.write_text(json.dumps({
+            "integration": "test",
+            "files": {"kept.txt": "abc123"},
+            "recovered_files": ["kept.txt", "orphan.txt"],
+        }), encoding="utf-8")
+        m = IntegrationManifest.load("test", tmp_path)
+        assert m.recovered_files == {"kept.txt"}
+        assert m.is_recovered("kept.txt") is True
+        assert m.is_recovered("orphan.txt") is False
+
 
 class TestManifestRecoveredFiles:
     """Coverage for the ``recovered_files`` channel added in #2483.