LorenEteval_Furious/Furious/Frozenlib/AGENTS.md

Frozenlib foundation guidance

• Frozenlib is the compatibility/platform foundation and a broad public import surface. Keep imports cheap, cross-platform, and free of GUI/application construction side effects. Preserve exported names unless a migration covers all wildcard consumers.
• Constants, enums, version, and pure helpers stay dependency-light. Globals contains narrow accessors for deliberate application-lifetime owners and must return safely during partial startup/shutdown.
• AppSettings is the centralized settings boundary. Preserve defaults, value types, migrations, and compatibility aliases; write requested state only after required host side effects succeed.

Platform and process safety

• Host mutation (proxy, DNS, startup registration, session, routing) is platform-isolated, returns/logs actionable failure, and can be fully mocked. runExternalCommand() intentionally delegates timeout policy to each caller; callers that require bounded execution must pass a timeout or run in a documented non-GUI context. Never test against real host state.
• Own exact daemon threads/processes. Clear dead references so restart is possible; cleanup is bounded and idempotent. Do not suppress a failed shutdown or leave persisted state claiming success.
• parseHostPort and other externally keyed caches must be bounded. Unbounded caches are limited to finite application metadata and must not capture QObject instances or bound methods.
• Rate limiting on GUI-callable paths must not sleep the caller. Network helpers support IPv4/IPv6 and use bounded resolution/connect operations.

Mixins and resources

• Weak instance pools must not be paired with hidden strong references or callbacks that capture the target. Remove dead entries and tolerate already-deleted Qt wrappers.
• Context managers restore the exact prior enabled/signal-block state and remain safe when nested.
• AppResources.py is generated from resource inputs. Do not hand-edit generated bytes or bypass the resource-generation workflow.

Code review rules

• Flag GUI/high-level imports, caller paths that can block the GUI or shutdown without an intentional bound, state persisted after host failure, broad process-name cleanup, sensitive logging, unbounded external-input caches, and globals holding transient objects. Do not add a universal timeout to runExternalCommand().
• Run direct mocked platform/helper tests plus affected controller/service tests.