fix: preserve symlinked retained project state

Resolve the full retained state file before containment filtering so external aliases into the selected state directory remain readable. Add real CLI coverage for aliases to a distinct retained file and the selected shared file.

Addresses review: "Compare the resolved full retained file before containment filtering"

Signed-off-by: Duang777 <duangjl007@gmail.com>

Author: Duang777

loopx/project_uninstall.py

@@ -16,7 +16,11 @@
 from .control_plane.runtime.time import now_local_iso, utc_timestamp
 from .file_lock import exclusive_cross_runtime_file_lock
 from .global_registry import GlobalRegistryReduction, mutate_global_registry
-from .paths import global_registry_path, resolve_runtime_root, select_default_runtime_root
+from .paths import (
+    global_registry_path,
+    resolve_runtime_root,
+    select_default_runtime_root,
+)
 from .registry import read_json, registry_goals
 from .runtime import validate_goal_id_path_segment
 
@@ -130,7 +134,7 @@ def _archive_state_directory(
             )
         )
         is not None
-        and _path_is_within(retained_state.parent, state_dir_resolved)
+        and _path_is_within(retained_state, state_dir_resolved)
     ]
     shared_state_owners = [
         retained_goal_id
@@ -165,8 +169,7 @@ def _archive_state_directory(
                 "action": "state-file-missing",
                 "archived": False,
                 "retained_goal_ids": sorted(
-                    retained_goal_id
-                    for retained_goal_id, _ in retained_state_owners
+                    retained_goal_id for retained_goal_id, _ in retained_state_owners
                 ),
                 "warning": (
                     "state directory is still registered by a retained goal; "

loopx/semantics/project_registry_io_manifest_v1.json

@@ -2127,15 +2127,15 @@
     },
     {
       "site": "loopx/project_uninstall.py::<module>.uninstall_project::codec_read:load_registry#1",
-      "line": 324,
+      "line": 327,
       "column": 24,
       "kind": "codec_read",
       "api": "load_registry",
       "classification": "codec_api"
     },
     {
       "site": "loopx/project_uninstall.py::<module>.uninstall_project::codec_transaction:project_registry_transaction#1",
-      "line": 434,
+      "line": 437,
       "column": 18,
       "kind": "codec_transaction",
       "api": "project_registry_transaction",

tests/test_global_registry_write_serialization.py

@@ -2,6 +2,7 @@
 
 import errno
 import json
+import os
 import select
 import subprocess
 import sys
@@ -125,7 +126,9 @@ def recording_write(path: Path, payload: dict[str, Any]) -> None:
             events.append(f"write:{'locked' if held else 'unlocked'}")
         real_write(path, payload)
 
-    monkeypatch.setattr(global_registry, "exclusive_cross_runtime_file_lock", recording_lock)
+    monkeypatch.setattr(
+        global_registry, "exclusive_cross_runtime_file_lock", recording_lock
+    )
     monkeypatch.setattr(global_registry, "_load_global_registry", recording_load)
     monkeypatch.setattr(global_registry, "write_json", recording_write)
 
@@ -162,7 +165,9 @@ def denied_lock(path: Path, **kwargs: Any) -> Iterator[Path]:
         raise failure
         yield path
 
-    monkeypatch.setattr(global_registry, "exclusive_cross_runtime_file_lock", denied_lock)
+    monkeypatch.setattr(
+        global_registry, "exclusive_cross_runtime_file_lock", denied_lock
+    )
     result = sync_project_registry_to_global(
         registry_path=registry_path, runtime_root_override=str(runtime_root)
     )
@@ -191,7 +196,9 @@ def failed_lock(path: Path, **kwargs: Any) -> Iterator[Path]:
         raise failure
         yield path
 
-    monkeypatch.setattr(global_registry, "exclusive_cross_runtime_file_lock", failed_lock)
+    monkeypatch.setattr(
+        global_registry, "exclusive_cross_runtime_file_lock", failed_lock
+    )
     with pytest.raises(OSError) as caught:
         sync_project_registry_to_global(
             registry_path=registry_path, runtime_root_override=str(runtime_root)
@@ -213,7 +220,9 @@ def recording_lock(path: Path, **kwargs: Any) -> Iterator[Path]:
         acquired.append(path)
         yield path
 
-    monkeypatch.setattr(global_registry, "exclusive_cross_runtime_file_lock", recording_lock)
+    monkeypatch.setattr(
+        global_registry, "exclusive_cross_runtime_file_lock", recording_lock
+    )
 
     result = sync_project_registry_to_global(
         registry_path=registry_path,
@@ -270,7 +279,9 @@ def recording_write(path: Path, payload: dict[str, Any]) -> None:
             events.append(f"backup:{'locked' if held else 'unlocked'}")
         real_write(path, payload)
 
-    monkeypatch.setattr(global_registry, "exclusive_cross_runtime_file_lock", recording_lock)
+    monkeypatch.setattr(
+        global_registry, "exclusive_cross_runtime_file_lock", recording_lock
+    )
     monkeypatch.setattr(global_registry, "_load_global_registry", recording_load)
     monkeypatch.setattr(global_registry, "write_json", recording_write)
 
@@ -663,6 +674,111 @@ def test_project_uninstall_archives_only_selected_state_in_a_shared_directory(
     assert [goal["id"] for goal in global_goals] == ["goal-beta"]
 
 
+@pytest.mark.parametrize("shared_target", [False, True])
+def test_project_uninstall_preserves_retained_state_through_an_external_symlink(
+    tmp_path: Path,
+    shared_target: bool,
+) -> None:
+    runtime_root = tmp_path / "runtime"
+    registry_path = _project_registry(tmp_path, "alpha", runtime_root)
+    project_root = registry_path.parents[1]
+    state_dir = project_root / "selected-state"
+    alias_dir = project_root / "aliases"
+    state_dir.mkdir()
+    alias_dir.mkdir()
+    selected_state = state_dir / "goal-alpha.md"
+    selected_state.write_text("# alpha state\n", encoding="utf-8")
+    retained_target = selected_state if shared_target else state_dir / "goal-beta.md"
+    if not shared_target:
+        retained_target.write_text("# beta state\n", encoding="utf-8")
+    retained_alias = alias_dir / "goal-beta.md"
+    try:
+        retained_alias.symlink_to(Path("..") / state_dir.name / retained_target.name)
+    except OSError as exc:
+        pytest.skip(f"file symlinks are unavailable: {exc}")
+
+    registry = json.loads(registry_path.read_text(encoding="utf-8"))
+    registry["goals"][0]["state_file"] = "selected-state/goal-alpha.md"
+    registry["goals"].append(
+        {
+            **registry["goals"][0],
+            "id": "goal-beta",
+            "state_file": "aliases/goal-beta.md",
+        }
+    )
+    registry_path.write_text(json.dumps(registry), encoding="utf-8")
+    sync_project_registry_to_global(
+        registry_path=registry_path,
+        runtime_root_override=str(runtime_root),
+        dry_run=False,
+    )
+    global_path = global_registry_path(runtime_root)
+    registry_before_preview = registry_path.read_bytes()
+    global_before_preview = global_path.read_bytes()
+    expected_retained = retained_alias.read_bytes()
+
+    def run_cli(*arguments: str) -> dict[str, Any]:
+        completed = subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "loopx.cli",
+                "--format",
+                "json",
+                "--registry",
+                str(registry_path),
+                "--runtime-root",
+                str(runtime_root),
+                "uninstall-project",
+                "--goal-id",
+                "goal-alpha",
+                "--archive-state",
+                *arguments,
+            ],
+            cwd=Path(__file__).resolve().parents[1],
+            env={**os.environ, "LOOPX_USAGE_PING": "0"},
+            capture_output=True,
+            text=True,
+            timeout=60,
+            check=False,
+        )
+        assert completed.returncode == 0, completed.stderr
+        return json.loads(completed.stdout)
+
+    preview = run_cli()
+
+    expected_preview_action = (
+        "kept-shared-state-file" if shared_target else "would-move-state-file"
+    )
+    assert preview["state_actions"][0]["action"] == expected_preview_action
+    assert preview["state_actions"][0]["retained_goal_ids"] == ["goal-beta"]
+    assert registry_path.read_bytes() == registry_before_preview
+    assert global_path.read_bytes() == global_before_preview
+    assert retained_alias.is_symlink()
+    assert retained_alias.read_bytes() == expected_retained
+
+    result = run_cli("--execute")
+
+    expected_action = "kept-shared-state-file" if shared_target else "moved-state-file"
+    state_action = result["state_actions"][0]
+    assert state_action["action"] == expected_action
+    assert state_action["retained_goal_ids"] == ["goal-beta"]
+    assert retained_alias.is_symlink()
+    assert retained_alias.read_bytes() == expected_retained
+    if shared_target:
+        assert selected_state.read_bytes() == expected_retained
+    else:
+        assert not selected_state.exists()
+        archived = Path(state_action["archive_path"])
+        assert (archived / selected_state.name).read_text(
+            encoding="utf-8"
+        ) == "# alpha state\n"
+    local_goals = json.loads(registry_path.read_text(encoding="utf-8"))["goals"]
+    assert [goal["id"] for goal in local_goals] == ["goal-beta"]
+    global_goals = json.loads(global_path.read_text(encoding="utf-8"))["goals"]
+    assert [goal["id"] for goal in global_goals] == ["goal-beta"]
+
+
 def test_project_uninstall_keeps_a_state_file_registered_by_a_retained_goal(
     tmp_path: Path,
 ) -> None: