security(codeql): document false-positive suppression for py/unsafe-cyclic-import on simulation/{base,policy_runner,benchmark}.py

[cagataycali]

Context

Follow-up tracking issue for the architectural deadlock identified in PR #209 (currently draft, paused per AGENTS.md round budget).

Problem (from PR #209 S13/R6)

In strands_robots/simulation/{base.py, policy_runner.py, benchmark.py}, mypy and CodeQL have mutually exclusive requirements:

Helper signature	mypy	CodeQL
tuple[type[PolicyRunner], type[VideoConfig]] + line-28 TYPE_CHECKING import	clean	FAIL: alerts #254, #255 reopen on line 28
tuple[type[PolicyRunner], type[VideoConfig]] + drop line 28 + string forward-refs	FAIL: 6 errors (name-defined)	(would pass, but mypy blocks it)
tuple[type, type] (R4 form) + drop line 28	FAIL: 5 errors (no-any-return, attr-defined on VideoConfig.from_dict)	clean

mypy needs a module-scope name binding to resolve return-type names; CodeQL forbids any module-scope edge (TYPE_CHECKING included) to policy_runner.

Why a CodeQL config suppression is the right answer

The runtime is provably safe under from __future__ import annotations:

• All type hints are strings at runtime, never resolved at module-import time.
• The _lazy_policy_runner() helper is a function, not module-level code; its body executes only at call time, by which point both modules are fully loaded.
• The companion regression tests in tests/simulation/test_no_import_cycle.py pin three AST-level invariants (helper exists, helper is called by all four SimEngine methods, no module-level direct import) and round-trip-verify they fail on pre-fix code.

This is the textbook profile of a documented false-positive for py/unsafe-cyclic-import.

Proposed approach (Option A in PR #209 S13)

1. Add .github/codeql/config.yml (or extend the existing one if any) with a path-scoped suppression:

   query-filters:
     - exclude:
         id: py/unsafe-cyclic-import
         paths:
           - strands_robots/simulation/base.py
           - strands_robots/simulation/policy_runner.py
           - strands_robots/simulation/benchmark.py

2. Reference the GitHub Actions CodeQL workflow to use this config.
3. Add a top-of-file comment in each of the three files pointing at the config and explaining the runtime-safety argument.
4. Add a security-review note in SECURITY.md (or equivalent) documenting the suppression and its rationale.
5. Once landed, mark PR fix(simulation): defer policy_runner import to break unsafe cyclic-import cycle #209 ready for review or close it as superseded.

Round budget

1 round expected. The change is small (~20 lines of config + a doc note) and has been pre-justified by the multi-round investigation in PR #209.

Out of scope

• Architectural refactor merging policy_runner.py into base.py (Option B in PR fix(simulation): defer policy_runner import to break unsafe cyclic-import cycle #209). Defer until/unless Option A is rejected by maintainers.
• Suppressions of py/unsafe-cyclic-import for any files outside the simulation triple.

References

• PR fix(simulation): defer policy_runner import to break unsafe cyclic-import cycle #209 (paused; full constraint analysis in S13/R6)
• CodeQL alerts chore: modernize build system — uv lockfile, Python >=3.12 #83, feat: simulation foundation — models, ABC, factory, model registry, assets #84 (closed by R4), feat: MuJoCo simulation backend - AgentTool with 50+ actions #85, feat: Robot() factory + top-level lazy imports #86, docs: rewrite README, update AGENTS.md, add 8 examples #87 (status unverified), #254, #255 (reopened by R5)
• AGENTS.md > S0 (round budget) -- the PR was correctly paused at draft to avoid further iteration