fix(cli): stop uninstall and kill --port destroying what they do not own - #3361

🔴 Critical

_is_link() returns True for every path on Python < 3.12 (POSIX) — src/gaia/installer/uninstall_command.py:552

os.path.isjunction is 3.12+, so on 3.10/3.11 the fallback runs. On POSIX st_reparse_tag is absent → None, and stat.IO_REPARSE_TAG_MOUNT_POINT is also absent on non-Windows builds → None. The comparison becomes None == None:

$ python3.12 -c "import stat; print(hasattr(stat,'IO_REPARSE_TAG_MOUNT_POINT'))"
False # Linux — the constant is Windows-only in _stat

(Verified in this checkout: reparse_tag is None, the marker is None, equal -> True.)

Failure path on Linux/macOS + 3.10/3.11, gaia uninstall --purge:

• _is_link(~/.gaia/venv) → True → _remove_path takes the link branch (uninstall_command.py:652)
• _unlink_link → path.unlink() raises IsADirectoryError → os.rmdir() raises ENOTEMPTY
• caught at uninstall_command.py:664 → [error] failed to remove ..., all_ok = False → EXIT_FS_ERROR
• venv/, chat/, documents/ all survive; the uninstall is a no-op that reports failure

setup.py:348 declares python_requires=">=3.10" with 3.10/3.11 classifiers; every unit-test workflow pins python-version: '3.12', so this is invisible to CI.

def _is_link(path: Path) -> bool:
 """Whether ``path`` is a symlink or a Windows junction.
 ``Path.is_symlink()`` is False for a junction, and a junction is the only
 way to relocate a directory on Windows without Developer Mode.
 """
 if path.is_symlink():
 return True
 if not sys.platform.startswith("win"):
 return False
 isjunction = getattr(os.path, "isjunction", None) # 3.12+
 if isjunction is not None:
 return bool(isjunction(path))
 try:
 reparse_tag = getattr(path.lstat(), "st_reparse_tag", None)
 except OSError:
 return False
 # The constant is Windows-only, so pin the value rather than getattr-ing it.
 return reparse_tag is not None and reparse_tag == 0xA0000003

Worth a test that pins the pre-3.12 branch, e.g. monkeypatch.delattr(os.path, "isjunction", raising=False) around an ordinary directory and asserting _is_link(...) is False.

🟡 Important

Identity check skips Tier 2 — uninstall_command.py:353

_assert_purgeable_home(home, require_marker=purge) means gaia uninstall --venv with GAIA_HOME=/path/to/some/project deletes /path/to/some/project/venv with no marker check. The structural guard still fires (home dir / root), but GAIA_HOME_MARKERS deliberately excludes venv precisely so a pointed-at checkout keeps its virtualenv — and Tier 2 is the tier that actually deletes it. Either pass require_marker=True for both tiers (a not-yet-created home is already exempted by the resolved.is_dir() guard, so the no-op case stays quiet), or state the purge-only scope in docs/reference/cli.mdx so the note doesn't overpromise.

🟢 Minor

1. chat, logs, and config.json are weak ownership markers (uninstall_command.py:459). A GAIA_HOME aimed at a real data folder that happens to contain any of them passes _has_gaia_marker and becomes purgeable. config.json/gaia.log/memory.db plus the electron-* files carry the signal; the three generic ones mostly widen the hole.

2. The --port doc note overstates the protection (docs/reference/cli.mdx:437). It's accurate that a database or svchost gets refused, but the allowlist admits any python/node/electron process — so a user's own Node dev server on a mistyped port is still kill -9'd. One clause noting that the check is interpreter-level would keep the note honest.

3. Unreadable PID column reads as "nothing listening" (cli.py:128). netstat -tulpn prints - for processes the caller doesn't own, so the int() raises, the row is dropped, and the user is told No process is listening on port N when something is. A distinct message when rows matched but no PID was readable would be more actionable.

Strengths

• The security argument is made in the right place: _safe_roots now carries a note explaining that it is vacuous until _assert_purgeable_home has run, so the next reader can't mistake the containment guard for sufficient on its own.
• TestListenerLookupCallShape asserts the shape of the outgoing lsof argv (-sTCP:LISTEN present, -ti:PORT absent) rather than just that the tool was invoked — exactly the boundary-validity testing CLAUDE.md asks for, and it's what makes the lsof exit-1-vs-failure distinction reviewable.
• Fixtures are real trimmed netstat output covering the actual regression shapes: :80 vs :8009, TIME_WAIT, UDP rows, IPv6 dedupe, and a localized ABHÖREN state column.
• Error messages name what failed, what to do, and the resolved path — Cannot inspect port N: netstat is not on PATH... is a real improvement over the old No process found running on port N catch-all.

src/gaia/installer/uninstall_command.py:567

# current — still broken on pre-3.12 POSIX
return reparse_tag == getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", None)
# both sides are None on Linux → True for every plain directory

 if not sys.platform.startswith("win"):
 return False
 return reparse_tag is not None and reparse_tag == 0xA0000003

Or as a one-liner in the return:

 return (
 reparse_tag is not None
 and reparse_tag == getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", reparse_tag + 1)
 )

(The reparse_tag + 1 default makes the equality false when the constant is absent; the is not None guard makes the whole expression false when st_reparse_tag is absent.)

Simplest and clearest: sys.platform guard + hardcoded 0xA0000003.

A test for the pre-3.12 path would be:

def test_is_link_returns_false_for_plain_dir_when_isjunction_absent(self, tmp_path, monkeypatch):
 monkeypatch.delattr(os.path, "isjunction", raising=False)
 assert not uc._is_link(tmp_path)

_is_link() — uninstall_command.py:561

if path.is_symlink():
 return True
isjunction = getattr(os.path, "isjunction", None) # 3.12+
if isjunction is not None:
 return bool(isjunction(path))
if not sys.platform.startswith("win"):
 return False # ← platform guard, before any lstat
mount_point_tag = getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", None)
if mount_point_tag is None:
 return False # ← never compare against a missing constant
try:
 return getattr(path.lstat(), "st_reparse_tag", None) == mount_point_tag
except OSError:
 return False

Two independent closes on the None == None trap. I kept getattr(stat, ...) over a hardcoded 0xA0000003 because the guarded form can't produce a false positive and the named constant documents itself; either is correct.

The regression test — test_uninstall_command.py:1280

TestLinkDetectionFallback (4 tests). The posix_pre_312 fixture at :1289 simulates pre-3.12 POSIX on any interpreter: it deletes os.path.isjunction, deletes stat.IO_REPARSE_TAG_MOUNT_POINT, sets sys.platform to linux, and — the part that matters — wraps Path.lstat so the result raises AttributeError for st_reparse_tag.

That last piece was necessary. My first attempt only deleted os.path.isjunction, and it passed against the broken code: Windows lstat() still returns a real st_reparse_tag of 0, so the comparison was 0 == None, not None == None. I verified the finished tests by reverting the fix and re-running — 3 of the 4 fail against the previous commit, all 4 pass now. :1330 is the end-to-end one: a populated ~/.gaia/venv must actually be removed and the run must exit 0.

Ownership check on both tiers — uninstall_command.py:278, :362

_assert_purgeable_home no longer takes require_marker; build_plan calls it for both tiers and passes tier= so the error names the flag actually used. Nothing legitimate is refused by extending it: both installers shadow the environment variable with a hardcoded path (installer/scripts/install.sh:11 sets GAIA_HOME="$HOME/.gaia", install.ps1:7 sets "$env:USERPROFILE\.gaia"), so a venv is only ever created under ~/.gaia, which passes on its name alone. A custom GAIA_HOME that GAIA has actually used carries a marker; one that doesn't exist yet skips the check as a no-op.

Coverage: test_a_venv_alone_is_not_proof_that_gaia_owns_the_directory (:1005) is parametrized over both tiers and asserts the right flag appears in the message; :1024 is the end-to-end --venv refusal; two more confirm --venv still works on a marked custom home and on the default ~/.gaia.

One correction

The review states "CI only runs 3.12" and "every unit-test workflow pins python-version: '3.12'". test_unit.yml in fact runs a py3.10 / py3.11 / py3.12 matrix plus a macOS smoke lane — which is why this was caught before merge rather than after. The conclusion was right; the reason it was invisible was that my local box is Windows/py3.13, where the buggy branch is unreachable.

Current uninstall_command.py:561 (the cited line 567 is now if path.is_symlink():):

isjunction = getattr(os.path, "isjunction", None) # 3.12+
if isjunction is not None:
 return bool(isjunction(path))
if not sys.platform.startswith("win"): # :572 — your suggested guard
 return False
mount_point_tag = getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", None)
if mount_point_tag is None: # :576 — second, independent close
 return False
try:
 return getattr(path.lstat(), "st_reparse_tag", None) == mount_point_tag
except OSError:
 return False

I kept the named constant rather than hardcoding 0xA0000003: with both guards in place the equality can't be reached with either side None, and the name documents itself. Functionally equivalent to your suggestion.

On the test — your proposed version would not have caught this.

monkeypatch.delattr(os.path, "isjunction", raising=False)
assert not uc._is_link(tmp_path)

That's what I wrote first, and it passed against the broken code. On Windows lstat() returns a real st_reparse_tag of 0, so the comparison is 0 == None → False, and the bug hides. Reproducing it off-Linux needs the missing attribute simulated on both sides.

posix_pre_312 (test_uninstall_command.py:1289) does that: deletes os.path.isjunction, deletes stat.IO_REPARSE_TAG_MOUNT_POINT, sets sys.platform to linux, and wraps Path.lstat so the result raises AttributeError for st_reparse_tag. Verified by reverting the fix: 3 of 4 fail against 70678f66, all 4 pass on 56f41d87. :1330 covers the end-to-end symptom — a populated ~/.gaia/venv must be removed and the run must exit 0.

CI on 31d58e48 and later is green on py3.10, py3.11, py3.12 and the macOS smoke lane.