bug(installer): PermissionError in _is_custom_agent_dir crashes Export on Windows (Python 3.12.x / restricted NTFS ACLs)

[itomek]

Summary

On Windows with Python 3.12.x, Path.is_file() raises PermissionError (WinError 5: Access is denied) instead of returning False when called on paths inside directories that have restricted NTFS ACLs. This causes export_custom_agents() to crash with an unhandled exception, and the POST /api/agents/export endpoint returns HTTP 500 to the UI, which shows an error banner.

Affected file: src/gaia/installer/export_import.py
Affected function: _is_custom_agent_dir()

Root Cause

# BEFORE (buggy)
def _is_custom_agent_dir(path: Path) -> bool:
    return path.is_dir() and (
        (path / "agent.py").is_file() or (path / "agent.yaml").is_file()
    )

pathlib.Path.is_file() is documented to return False on errors, but on Windows with Python 3.12.12 it raises PermissionError for NTFS paths where the caller lacks read permission. This is a known CPython regression/platform inconsistency. Any subdirectory of ~/.gaia/agents/ with restricted permissions (e.g. a symlink or directory created by another process with locked-down ACLs) triggers the crash.

Reproduction Steps

1. Install GAIA v0.17.2 on Windows 11 with Python 3.12.x
2. Create a directory with restricted NTFS permissions inside ~/.gaia/agents/:

   $dir = "$env:USERPROFILE\.gaia\agents\restricted-dir"
   New-Item -ItemType Directory -Path $dir
   $acl = Get-Acl $dir
   $acl.SetAccessRuleProtection($true, $false)
   Set-Acl -Path $dir -AclObject $acl

3. Open the GAIA Agent UI desktop app
4. Go to Settings → Custom Agents → Export All
5. Click through the security confirmation dialog
6. Choose a save path and click Save

Expected: Export succeeds, skipping or ignoring the restricted directory
Actual: PermissionError: [WinError 5] Access is denied is raised; UI shows an error banner; no zip file is produced

Fix

Wrap the file checks in a try/except OSError block:

# AFTER (fixed)
def _is_custom_agent_dir(path: Path) -> bool:
    """A directory qualifies as a custom agent if it holds agent.py or agent.yaml."""
    try:
        return path.is_dir() and (
            (path / "agent.py").is_file() or (path / "agent.yaml").is_file()
        )
    except OSError:
        return False

This matches the documented intent of is_file() (return False on errors) and silently skips any unreadable subdirectory rather than crashing the entire export.

Acceptance Criteria

• _is_custom_agent_dir() does not raise when called on a path inside ~/.gaia/agents/ that has restricted NTFS permissions
• Export succeeds (produces a valid zip) when ~/.gaia/agents/ contains a mix of valid agent directories and unreadable/restricted subdirectories
• Restricted/unreadable directories are silently skipped — they do not appear in bundle.json agent_ids
• Unit test added: mock Path.is_file() to raise PermissionError; assert _is_custom_agent_dir() returns False rather than propagating the exception
• Behavior is consistent on Windows (Python 3.12.x) and Linux/macOS

Environment

OS	Windows 11
Python	3.12.12
GAIA version	0.17.2
Hardware	AMD Ryzen AI MAX+ 395

References

• Discovered during integration testing of PR feat(installer): custom installer guide, agent export/import, first-launch seeder #795 (now merged)
• PR comment with original finding: feat(installer): custom installer guide, agent export/import, first-launch seeder #795 (comment)
• Full test report: feat(installer): custom installer guide, agent export/import, first-launch seeder #795 (comment)

[github-actions]

Thanks @itomek — this is a well-scoped bug report with a clear root cause, reproduction, and minimal fix. Confirmed on my read of the code.

Verification of the report:

• src/gaia/installer/export_import.py:93-97 matches the "BEFORE" snippet exactly — no try/except guarding is_file().
• The export call path crashes all the way up: export_custom_agents() → _is_custom_agent_dir() on the unreadable sibling directory, and the exception propagates through src/gaia/ui/routers/agents.py:136, which is what surfaces as the HTTP 500 banner in the Agent UI.
• No duplicate issues found (searched open + closed for PermissionError export is_file).

🟡 Severity: Important — it silently breaks Export All on Windows for any user whose ~/.gaia/agents/ parent has an unrelated restricted subdirectory, and Export is a user-facing desktop-app flow (not just CLI). The fix is tiny and self-contained.

A couple of notes on the patch:

1. Catching OSError (not just PermissionError) is the right call — it also covers FileNotFoundError from races and broken symlinks, and it mirrors pathlib's documented "return False on errors" intent.
2. Please also log at debug level when skipping, so an operator can tell why a directory didn't show up in bundle.json without needing to re-run under a debugger:

   except OSError as exc:
       log.debug("Skipping unreadable path %s: %s", path, exc)
       return False

   (The module already imports log at line 32.)
3. Unit test should go in tests/unit/test_export_import.py (the file exists — no new test module needed). A mocker.patch.object(Path, "is_file", side_effect=PermissionError(...)) style test is the cleanest way to satisfy the fourth acceptance-criteria box without needing real NTFS ACLs in CI.

Scope check: the fix is confined to _is_custom_agent_dir(). I looked for other is_file() / is_dir() calls in the same module that could hit the same class of bug on Windows — rglob("*") at line 173 and the path.is_file() at line 174 inside the zip-writing loop are also technically exposed to the same PermissionError for a restricted subdirectory of a valid agent dir. Out of scope for this issue, but worth a follow-up if the user sees that failure mode after this fix lands.

Next steps: happy to pick this up — the fix + test are small enough to land in one PR with a CHANGELOG note. Before I start: @kovtcharov-amd, do you want this targeted at main only, or also cherry-picked onto the 0.17.x release branch (if one exists) given it's a regression from a released build?