Tidy up logging and rework tests from scratch

SCRATCHPAD.md

@@ -8,6 +8,8 @@
 
 - The biggest near-term wins are in startup cost, repeated subprocess work, repeated database query patterns, and general repo hygiene.
 - This list is intentionally optimization-oriented rather than bug-oriented. Some items below also improve correctness or maintainability, but they were selected because they can reduce runtime cost, operator friction, or iteration overhead.
+- A first modern integration slice now exists under [`tests/integration/subtrack_mapping`](/home/osgw/.local/src/codex/ffx/tests/integration/subtrack_mapping). Remaining test-suite cleanup is now mostly about migrating and shrinking the legacy harness surface under [`tests/legacy`](/home/osgw/.local/src/codex/ffx/tests/legacy).
+- FFX logger setup now reuses named handlers, and fallback logger access no longer mutates handlers in ordinary constructors and helpers.
 
 ## Focused Snapshot
 
@@ -16,17 +18,15 @@
   - Collapse repeated `ffprobe` calls into a single probe result per source file.
   - Replace `query.count()` plus `first()` patterns with single-query ORM accessors.
   - Cache or precompile filename pattern regexes instead of scanning every pattern for every file.
-  - Guard logger handler installation to avoid duplicated handlers and noisy repeated setup.
 
 - Highest-leverage repo and workflow optimizations:
-  - Stop tracking nested `__pycache__` output and other generated artifacts.
   - Consolidate setup and upgrade tooling to reduce overlapping shell-script responsibilities.
-  - Trim or reorganize the oversized test/combinator surface so it is easier to run, debug, and extend.
+  - Continue migrating the oversized legacy test/combinator surface into focused modern tests so it is easier to run, debug, and extend.
 
 ## Optimization Candidates
 
 1. CLI startup and import cost
-- [`src/ffx/ffx.py`](/home/osgw/.local/src/codex/ffx/src/ffx/ffx.py) imports a large portion of the application at module import time, even for cheap commands such as `version`, `help`, `setup_dependencies`, and `upgrade`.
+- [`src/ffx/cli.py`](/home/osgw/.local/src/codex/ffx/src/ffx/cli.py) imports a large portion of the application at module import time, even for cheap commands such as `version`, `help`, `setup_dependencies`, and `upgrade`.
 - Optimization:
   - Move heavy imports into the commands that actually need them.
   - Keep the CLI root importable with only core stdlib and Click dependencies.
@@ -80,28 +80,8 @@
   - Better failure diagnosis.
   - Cleaner process management semantics.
 
-7. Logger handlers can be added repeatedly
-- [`src/ffx/ffx.py`](/home/osgw/.local/src/codex/ffx/src/ffx/ffx.py) adds file and console handlers each invocation.
-- Several helper classes install `NullHandler` instances ad hoc, for example [`src/ffx/process.py`](/home/osgw/.local/src/codex/ffx/src/ffx/process.py), [`src/ffx/tmdb_controller.py`](/home/osgw/.local/src/codex/ffx/src/ffx/tmdb_controller.py), [`src/ffx/media_descriptor.py`](/home/osgw/.local/src/codex/ffx/src/ffx/media_descriptor.py), and [`src/ffx/helper.py`](/home/osgw/.local/src/codex/ffx/src/ffx/helper.py).
-- Optimization:
-  - Guard handler installation so each logger is configured once.
-  - Prefer module-level logger setup patterns over per-instance handler mutation.
-- Expected value:
-  - Less duplicate logging.
-  - Lower confusion in long-running or repeatedly invoked contexts.
-
-8. Repo-local hygiene for generated Python artifacts
-- The repo currently contains nested compiled artifacts under `src/ffx/__pycache__/...`.
-- `.gitignore` only ignores `__pycache__` at the repo root, not recursive `__pycache__/`.
-- Optimization:
-  - Ignore `__pycache__/` recursively and clean tracked generated files.
-  - Consider ignoring local virtualenv or other generated tool directories if they may appear in-repo later.
-- Expected value:
-  - Cleaner diffs and scans.
-  - Lower repo noise.
-
-9. Tooling overlap and naming drift
-- There are now multiple prep-related scripts: [`tools/prepare.sh`](/home/osgw/.local/src/codex/ffx/tools/prepare.sh), [`tools/setup.sh`](/home/osgw/.local/src/codex/ffx/tools/setup.sh), and the legacy-like [`tools/ffx_update.sh`](/home/osgw/.local/src/codex/ffx/tools/ffx_update.sh).
+7. Tooling overlap and naming drift
+- There are still overlapping prep and setup entrypoints across [`tools/prepare.sh`](/home/osgw/.local/src/codex/ffx/tools/prepare.sh), [`tools/setup.sh`](/home/osgw/.local/src/codex/ffx/tools/setup.sh), and newer CLI maintenance commands.
 - Optimization:
   - Decide which scripts remain canonical.
   - Replace or remove legacy wrappers once equivalent CLI commands exist.
@@ -110,7 +90,7 @@
   - Less operator confusion.
   - Fewer duplicated procedures to maintain.
 
-10. Placeholder UI surfaces should either ship or disappear
+8. Placeholder UI surfaces should either ship or disappear
 - [`src/ffx/help_screen.py`](/home/osgw/.local/src/codex/ffx/src/ffx/help_screen.py) and [`src/ffx/settings_screen.py`](/home/osgw/.local/src/codex/ffx/src/ffx/settings_screen.py) are placeholders.
 - Optimization:
   - Either remove them from the active UI surface or complete them.
@@ -119,7 +99,7 @@
   - Leaner interface.
   - Lower UX ambiguity.
 
-11. Large Textual screens repeat configuration and controller loading
+9. Large Textual screens repeat configuration and controller loading
 - Screens such as [`src/ffx/media_details_screen.py`](/home/osgw/.local/src/codex/ffx/src/ffx/media_details_screen.py), [`src/ffx/pattern_details_screen.py`](/home/osgw/.local/src/codex/ffx/src/ffx/pattern_details_screen.py), and [`src/ffx/show_details_screen.py`](/home/osgw/.local/src/codex/ffx/src/ffx/show_details_screen.py) repeat setup patterns and local metadata filtering extraction.
 - Optimization:
   - Extract a shared screen base or helper for common config/controller/bootstrap logic.
@@ -128,7 +108,7 @@
   - Lower maintenance overhead.
   - Easier UI iteration.
 
-12. Several helper functions are unfinished or dead-weight
+10. Several helper functions are unfinished or dead-weight
 - [`src/ffx/helper.py`](/home/osgw/.local/src/codex/ffx/src/ffx/helper.py) contains `permutateList(...): pass`.
 - There are many combinator and conversion placeholders across tests and migrations.
 - Optimization:
@@ -138,17 +118,18 @@
   - Smaller mental model.
   - Less time spent re-evaluating inactive paths.
 
-13. Test suite shape is expensive to understand and likely expensive to run
-- The project has a large matrix of combinator files under [`src/ffx/test`](/home/osgw/.local/src/codex/ffx/src/ffx/test), several placeholder `pass` implementations, and at least one suspicious filename with an embedded space: [`src/ffx/test/disposition_combinator_2_3 .py`](/home/osgw/.local/src/codex/ffx/src/ffx/test/disposition_combinator_2_3 .py).
+11. Test suite shape is expensive to understand and likely expensive to run
+- The project still carries a large legacy matrix of combinator files under [`tests/legacy`](/home/osgw/.local/src/codex/ffx/tests/legacy), several placeholder `pass` implementations, and at least one suspicious filename with an embedded space: [`tests/legacy/disposition_combinator_2_3 .py`](/home/osgw/.local/src/codex/ffx/tests/legacy/disposition_combinator_2_3 .py).
+- A first focused replacement slice now exists in [`tests/integration/subtrack_mapping/test_cli_bundle.py`](/home/osgw/.local/src/codex/ffx/tests/integration/subtrack_mapping/test_cli_bundle.py), so the remaining work is migration and consolidation rather than creating the modern test shape from scratch.
 - Optimization:
-  - Consolidate combinator families.
-  - Add a lighter smoke-test path.
+  - Continue replacing broad combinator matrices with focused parametrized integration and unit tests.
+  - Retire the bespoke legacy discovery and runner path once equivalent coverage exists.
   - Normalize file naming and test discovery conventions.
 - Expected value:
   - Faster contributor onboarding.
   - Easier CI adoption later.
 
-14. Process resource limiting semantics could be clearer
+12. Process resource limiting semantics could be clearer
 - [`src/ffx/process.py`](/home/osgw/.local/src/codex/ffx/src/ffx/process.py) prepends `nice` and `cpulimit` directly when values are set.
 - Optimization:
   - Validate and document effective behavior for combined `nice` + `cpulimit`.
@@ -157,7 +138,7 @@
   - Fewer surprises in production-like runs.
   - Easier support for user-reported performance behavior.
 
-15. Import-time dependency coupling makes maintenance commands brittle
+13. Import-time dependency coupling makes maintenance commands brittle
 - Even after recent CLI maintenance additions, the top-level CLI module still imports most application modules before Click dispatch.
 - Optimization:
   - Push imports for ORM, Textual, TMDB, ffmpeg helpers, and descriptors behind the commands that actually need them.
@@ -165,7 +146,7 @@
   - Maintenance commands such as setup and upgrade stay usable when optional runtime dependencies are broken.
   - Better separation between media runtime code and maintenance tooling.
 
-16. Regex and string utility cleanup
+14. Regex and string utility cleanup
 - [`src/ffx/helper.py`](/home/osgw/.local/src/codex/ffx/src/ffx/helper.py) still emits a `SyntaxWarning` for `RICH_COLOR_PATTERN`.
 - Optimization:
   - Convert regex literals to raw strings where appropriate.
@@ -174,7 +155,7 @@
   - Cleaner runtime output.
   - Less warning noise during dry-run maintenance commands.
 
-17. Database startup always runs schema creation and version checks
+15. Database startup always runs schema creation and version checks
 - [`src/ffx/database.py`](/home/osgw/.local/src/codex/ffx/src/ffx/database.py) runs `Base.metadata.create_all(...)` and version checks every time a DB-backed context is created.
 - Optimization:
   - Measure startup cost and consider separating bootstrapping from ordinary command execution.
@@ -198,7 +179,6 @@
 
 1. Triage the list into quick wins, medium refactors, and long-horizon cleanup.
 2. Tackle the cheapest high-impact items first:
-   - recursive `__pycache__/` ignore and cleanup,
    - regex raw-string warning cleanup,
    - `count()` plus `first()` query cleanup,
    - single-call `ffprobe` refactor.