refactor(config): Route all config I/O through AppController

Eliminates 22 call sites that bypassed the AppController state owner
and read/wrote config.toml directly. AppController is now the single
source of truth for self.config; gui_2.py, commands.py, etc. go
through controller.save_config() / controller.load_config().

Production changes:
- src/models.py: rename load_config -> _load_config_from_disk,
  save_config -> _save_config_to_disk (private I/O primitives)
- src/app_controller.py: add public load_config()/save_config() methods
  that own the state. Update 3 internal call sites and 3 ConductorEngine
  call sites to pass max_workers from self.config
- src/multi_agent_conductor.py: ConductorEngine.__init__ now takes
  max_workers as a parameter (caller responsibility, not I/O primitive)
- src/external_editor.py: get_default_launcher() takes config as a
  parameter; gui_2.py:1311,4776 pass app.config
- src/gui_2.py: 17 sites of models.save_config(X.config) replaced with
  X.save_config() (delegates via __getattr__ to controller)
- src/commands.py: save_all() uses app.save_config()

Test changes (route through controller, not I/O primitive):
- tests/conftest.py: mock_app and app_instance fixtures now patch
  AppController.load_config/save_config instead of models I/O primitives
- 18 other test files: patches renamed from models._save_config_to_disk
  to AppController.save_config (and same for load_config)
- tests/test_app_controller_mcp.py: use SLOP_CONFIG env var instead of
  patching removed CONFIG_PATH module constant
- tests/test_parallel_execution.py: pass max_workers=2 explicitly to
  ConductorEngine (caller no longer reads config)
- tests/test_gui_paths.py: add save_config=MagicMock() to MockApp;
  assert on controller method, not I/O primitive
- tests/test_models_no_top_level_tomli_w.py: still calls private
  _save_config_to_disk directly (the only allowed exception; tests
  the lazy-load behavior of the primitive itself)

New files:
- scripts/audit_no_models_config_io.py: enforces the rule (--strict,
  --json modes; AST-based docstring detection to avoid false positives)
- conductor/code_styleguides/config_state_owner.md: documents the rule

Verification:
- 67 targeted tests pass
- scripts/audit_no_models_config_io.py --strict returns 0

This is the architectural cleanup that surfaced during the
audit_architectural_cheats_20260607 review. Closes the smoke-gun
CONFIG_PATH module constant (already done in 0c7ebf22) AND the
free-function models.load_config/save_config smell.

[conductor(checkpoint): config-iO-refactor-20260607]

src/app_controller.py

@@ -1707,7 +1707,7 @@ class AppController:
   self.ui_separate_response_panel   = False
   self.ui_separate_tool_calls_panel = False
   self.ui_separate_external_tools   = False
-  self.config = models.load_config()
+  self.config = self.load_config()
   theme.load_from_config(self.config)
   ai_cfg = self.config.get("ai", {})
   self._current_provider   = ai_cfg.get("provider", "gemini")
@@ -2685,7 +2685,7 @@ class AppController:
  def _cb_project_save(self) -> None:
   self._flush_to_project()
   self._flush_to_config()
-  models.save_config(self.config)
+  self.save_config()
   self.ai_status = "config saved"
 
  def _do_project_switch(self, path: str) -> None:
@@ -3360,7 +3360,7 @@ class AppController:
   """
   self._flush_to_project()
   self._flush_to_config()
-  models.save_config(self.config)
+  self.save_config()
   track_id = self.active_track.id if self.active_track else None
   flat = project_manager.flat_config(self.project, self.active_discussion, track_id=track_id)
   
@@ -3997,7 +3997,9 @@ class AppController:
    if self.active_track and self.active_track.id == track_id:
    # Use the active track object directly to start execution
     self.mma_status = "running"
-    engine = multi_agent_conductor.ConductorEngine(self.active_track, self.event_queue, auto_queue=not self.mma_step_mode)
+    _mma_cfg = self.config.get("mma", {})
+    _max_workers = int(_mma_cfg.get("max_workers", 4))
+    engine = multi_agent_conductor.ConductorEngine(self.active_track, self.event_queue, auto_queue=not self.mma_step_mode, max_workers=_max_workers)
     self.engines[self.active_track.id] = engine
     flat = project_manager.flat_config(self.project, self.active_discussion, track_id=self.active_track.id)
     full_md, _, _ = aggregate.run(flat)
@@ -4008,7 +4010,9 @@ class AppController:
     self._cb_load_track(track_id)
     if self.active_track and self.active_track.id == track_id:
      self.mma_status = "running"
-     engine = multi_agent_conductor.ConductorEngine(self.active_track, self.event_queue, auto_queue=not self.mma_step_mode)
+     _mma_cfg = self.config.get("mma", {})
+     _max_workers = int(_mma_cfg.get("max_workers", 4))
+     engine = multi_agent_conductor.ConductorEngine(self.active_track, self.event_queue, auto_queue=not self.mma_step_mode, max_workers=_max_workers)
      self.engines[self.active_track.id] = engine
      flat = project_manager.flat_config(self.project, self.active_discussion, track_id=self.active_track.id)
      full_md, _, _ = aggregate.run(flat)
@@ -4084,7 +4088,9 @@ class AppController:
    # 4. Initialize ConductorEngine and run loop
    sys.stderr.write(f"[DEBUG] _start_track_logic: Initializing engine for {track_id}...\n")
    sys.stderr.flush()
-   engine = multi_agent_conductor.ConductorEngine(track, self.event_queue, auto_queue=not self.mma_step_mode)
+   _mma_cfg = self.config.get("mma", {})
+   _max_workers = int(_mma_cfg.get("max_workers", 4))
+   engine = multi_agent_conductor.ConductorEngine(track, self.event_queue, auto_queue=not self.mma_step_mode, max_workers=_max_workers)
    self.engines[track.id] = engine
    # Use current full markdown context for the track execution
    track_id_param = track.id
@@ -4369,6 +4375,32 @@ class AppController:
     except Exception as e:
      print(f"Error loading beads: {e}")
 
+ #region: --- Config I/O (single source of truth) ---
+ def load_config(self) -> Dict[str, Any]:
+  """
+  Re-read the global config.toml from disk and update self.config.
+  Returns the dict (also stored in self.config). Single source of
+  truth for the in-memory config is self.config. Direct callers
+  from outside the controller (e.g. models.load_config) are an
+  architectural smell and will be flagged by
+  scripts/audit_no_models_config_io.py.
+  [C: src/app_controller.py:AppController.__init__]
+  """
+  self.config = models._load_config_from_disk()
+  return self.config
+
+ def save_config(self) -> None:
+  """
+  Flush self.config to disk. Single source of truth = self.config.
+  This method owns the write path. Direct callers from outside the
+  controller (e.g. models.save_config) are an architectural smell
+  and will be flagged by
+  scripts/audit_no_models_config_io.py.
+  [C: src/app_controller.py:AppController._cb_project_save, src/app_controller.py:AppController._do_generate]
+  """
+  models._save_config_to_disk(self.config)
+ #endregion: --- Config I/O (single source of truth) ---
+
  #endregion: MMA (Controller)
 
 #region: MMA

src/commands.py

@@ -143,7 +143,7 @@ def save_all(app: "App") -> None:
  if hasattr(app, "_flush_to_config"):  app._flush_to_config()
  if hasattr(app, "config"):
   try:
-   models.save_config(app.config)
+   app.save_config()
   except Exception as e:
    if hasattr(app, "ai_status"):
     app.ai_status = f"save error: {e}"

src/external_editor.py

@@ -7,7 +7,7 @@ import tempfile
 
 # TODO(Ed): Eliminate these?
 from pathlib import Path
-from typing  import Optional, List
+from typing  import Optional, List, Dict, Any
 
 from src.models import ExternalEditorConfig, TextEditorConfig
 
@@ -113,14 +113,16 @@ def auto_detect_vscode() -> Optional[TextEditorConfig]:
  return _cached_vscode_config
 
 
-def get_default_launcher() -> ExternalEditorLauncher:
+def get_default_launcher(config: Optional[Dict[str, Any]] = None) -> ExternalEditorLauncher:
  """
+ Caller passes the live config dict (typically app.config from the
+ AppController). Direct file I/O (the legacy public functions on src.models) is an
+ architectural smell (bypasses the controller state owner) and is
+ forbidden by scripts/audit_no_models_config_io.py.
  [C: src/gui_2.py:App._open_patch_in_external_editor, src/gui_2.py:App._render_external_editor_panel]
  """
- from src import models
- config = models.load_config()
- editors_config = config.get("tools", {}).get("text_editors", {})
- default_editor = config.get("tools", {}).get("default_editor", {}).get("default_editor")
+ editors_config = config.get("tools", {}).get("text_editors", {}) if config else {}
+ default_editor = config.get("tools", {}).get("default_editor", {}).get("default_editor") if config else None
  ext_config = ExternalEditorConfig.from_dict({
   "editors":        editors_config,
   "default_editor": default_editor,

src/gui_2.py

@@ -1009,7 +1009,7 @@ class App:
     if imgui.menu_item("Save All", "", False)[0]:
      self._flush_to_project()
      self._flush_to_config()
-     models.save_config(self.config)
+     self.save_config()
      self.ai_status = "config saved"
     if imgui.menu_item("Reset Session", "", False)[0]:
      ai_client.reset_session()
@@ -1167,7 +1167,7 @@ class App:
   if "tools" not in self.config:                   self.config["tools"] = {}
   if "default_editor" not in self.config["tools"]: self.config["tools"]["default_editor"] = {}
   self.config["tools"]["default_editor"]["default_editor"] = editor_name
-  models.save_config(self.config)
+  self.save_config()
   self.ai_status = f"Default editor set to: {editor_name}"
   
   _render_path_field("Logs Directory", "ui_logs_dir", "logs_dir", "Directory where session JSON-L logs and artifacts are stored.")
@@ -1192,7 +1192,7 @@ class App:
   }
   cfg_path = paths.get_config_path()
   if cfg_path.exists(): shutil.copy(cfg_path, str(cfg_path) + ".bak")
-  models.save_config(self.config)
+  self.save_config()
   paths.reset_resolved()
   self.init_state()
   self.ai_status = 'paths applied and session reset'
@@ -1308,7 +1308,7 @@ class App:
    if not self._pending_patch_files:
     self._patch_error_message = "No files to edit"
     return
-   launcher = get_default_launcher()
+   launcher = get_default_launcher(self.config)
    editor = launcher.config.get_default()
    if not editor:
     self._patch_error_message = "No external editor configured"
@@ -1479,7 +1479,7 @@ def render_main_interface(app: App) -> None:
   try:
    app._flush_to_project()
    app._flush_to_config()
-   models.save_config(app.config)
+   app.save_config()
   except Exception:
    pass  # silent — don't disrupt the GUI loop
  
@@ -2022,7 +2022,7 @@ def render_projects_panel(app: App) -> None:
  if imgui.button("Save All"):
   app._flush_to_project()
   app._flush_to_config()
-  models.save_config(app.config)
+  app.save_config()
   app.ai_status = "config saved"
  ch, app.ui_word_wrap              = imgui.checkbox("Word-Wrap (Read-only panels)", app.ui_word_wrap)
  ch, app.ui_auto_scroll_comms      = imgui.checkbox("Auto-scroll Comms History", app.ui_auto_scroll_comms)
@@ -2415,7 +2415,7 @@ def render_save_preset_modal(app: App) -> None:
       "multi_viewport": app.ui_multi_viewport
      }
      app.config["layout_presets"] = app.layout_presets
-     models.save_config(app.config)
+     app.save_config()
      app._show_save_preset_modal = False
      app._new_preset_name = ""
     imgui.close_current_popup()
@@ -4211,7 +4211,7 @@ def render_discussion_entry_controls(app: App) -> None:
  imgui.same_line()
  if imgui.button("Clear All"): app.disc_entries.clear()
  imgui.same_line()
- if imgui.button("Save"): app._flush_to_project(); app._flush_to_config(); models.save_config(app.config); app.ai_status = "discussion saved"
+ if imgui.button("Save"): app._flush_to_project(); app._flush_to_config(); app.save_config(); app.ai_status = "discussion saved"
  imgui.same_line()
  if imgui.button("Compress"): app.controller._handle_compress_discussion()
  _, app.ui_auto_add_history = imgui.checkbox("Auto-add message & response to history", app.ui_auto_add_history)
@@ -4773,7 +4773,7 @@ def render_external_editor_panel(app: App) -> None:
  imgui.text("External Editor for Diff Viewing")
  imgui.separator()
  try:
-  launcher = get_default_launcher()
+  launcher = get_default_launcher(app.config)
   editors = launcher.config.editors
   default_name = launcher.config.default_editor
   if not editors:
@@ -4876,7 +4876,7 @@ def render_theme_panel(app: App) -> None:
     if imgui.selectable(p, p == cp)[0]:
      theme.apply(p)
      app._flush_to_config()
-     models.save_config(app.config)
+     app.save_config()
    imgui.end_combo()
 
   imgui.separator()
@@ -4907,7 +4907,7 @@ def render_theme_panel(app: App) -> None:
   imgui.same_line()
   if imgui.button("Apply Font (Requires Restart)"):
    app._flush_to_config()
-   models.save_config(app.config)
+   app.save_config()
    app.ai_status = "Font settings saved. Restart required."
   imgui.separator()
   imgui.text("UI Scale (DPI)")
@@ -4915,14 +4915,14 @@ def render_theme_panel(app: App) -> None:
   if ch:
    theme.set_scale(scale)
    app._flush_to_config()
-   models.save_config(app.config)
+   app.save_config()
 
   imgui.text("Panel Transparency")
   ch_t, trans = imgui.slider_float("##trans", theme.get_transparency(), 0.1, 1.0, "%.2f")
   if ch_t:
    theme.set_transparency(trans)
    app._flush_to_config()
-   models.save_config(app.config)
+   app.save_config()
 
   imgui.text("Panel Item Transparency")
   ch_ct, ctrans = imgui.slider_float("##ctrans", theme.get_child_transparency(), 0.1, 1.0, "%.2f")
@@ -4934,14 +4934,14 @@ def render_theme_panel(app: App) -> None:
    gui_cfg = app.config.setdefault("gui", {})
    gui_cfg["bg_shader_enabled"] = bg.enabled
    app._flush_to_config()
-   models.save_config(app.config)
+   app.save_config()
 
   ch_crt, app.ui_crt_filter = imgui.checkbox("CRT Filter", app.ui_crt_filter)
   if ch_crt:
    gui_cfg = app.config.setdefault("gui", {})
    gui_cfg["crt_filter_enabled"] = app.ui_crt_filter
    app._flush_to_config()
-   models.save_config(app.config)
+   app.save_config()
   
   imgui.separator()
   imgui.text("Tone Mapping (Per-Palette)")
@@ -4949,20 +4949,20 @@ def render_theme_panel(app: App) -> None:
   
   imgui.text("Brightness")
   ch_b, b = imgui.slider_float("##tm_b", theme.get_brightness(curr_p), 0.1, 2.0, "%.2f")
-  if ch_b: theme.set_brightness(curr_p, b); app._flush_to_config(); models.save_config(app.config)
+  if ch_b: theme.set_brightness(curr_p, b); app._flush_to_config(); app.save_config()
   
   imgui.text("Contrast")
   ch_c, c = imgui.slider_float("##tm_c", theme.get_contrast(curr_p), 0.1, 2.0, "%.2f")
-  if ch_c: theme.set_contrast(curr_p, c); app._flush_to_config(); models.save_config(app.config)
+  if ch_c: theme.set_contrast(curr_p, c); app._flush_to_config(); app.save_config()
   
   imgui.text("Gamma")
   ch_g, g = imgui.slider_float("##tm_g", theme.get_gamma(curr_p), 0.1, 3.0, "%.2f")
-  if ch_g: theme.set_gamma(curr_p, g); app._flush_to_config(); models.save_config(app.config)
+  if ch_g: theme.set_gamma(curr_p, g); app._flush_to_config(); app.save_config()
   
   if imgui.button("Reset Tone Mapping"):
    theme.reset_tone_mapping(curr_p)
    app._flush_to_config()
-   models.save_config(app.config)
+   app.save_config()
   
  imgui.end()
  if app.perf_profiling_enabled: app.perf_monitor.end_component("_render_theme_panel")

src/models.py

@@ -163,14 +163,20 @@ def _clean_nones(data: Any) -> Any:
   return [_clean_nones(v) for v in data if v is not None]
  return data
 
-def load_config() -> dict[str, Any]:
+def _load_config_from_disk() -> dict[str, Any]:
  """
-  [C: src/multi_agent_conductor.py:ConductorEngine.__init__]
+ Re-read the global config.toml from disk and return the parsed
+ dict. The single source of truth for the in-memory config is
+ the AppController's self.config attribute; this function is the
+ disk I/O primitive that the controller owns. Direct callers in
+ src/ are an architectural smell (bypassing the state owner) and
+ will be flagged by scripts/audit_no_models_config_io.py.
+ [C: src/app_controller.py:AppController.load_config, src/app_controller.py:AppController.__init__]
  """
  with open(get_config_path(), "rb") as f:
   return tomllib.load(f)
 
-def save_config(config: dict[str, Any]) -> None:
+def _save_config_to_disk(config: dict[str, Any]) -> None:
  # tomli_w is loaded on-demand (sub-track 2 of startup_speedup_20260606).
  # If it's already in sys.modules (e.g. warmed up or loaded by a prior
  # call), the import is a fast lookup; otherwise it's a cold load paid

src/multi_agent_conductor.py

@@ -113,7 +113,7 @@ class ConductorEngine:
  Orchestrates the execution of tickets within a track.
  """
 
- def __init__(self, track: Track, event_queue: Optional[events.AsyncEventQueue] = None, auto_queue: bool = False) -> None:
+ def __init__(self, track: Track, event_queue: Optional[events.AsyncEventQueue] = None, auto_queue: bool = False, max_workers: int = 4) -> None:
   self.track = track
   self.event_queue = event_queue
   self.tier_usage = {
@@ -124,15 +124,7 @@ class ConductorEngine:
   }
   self.dag    = TrackDAG(self.track.tickets)
   self.engine = ExecutionEngine(self.dag, auto_queue=auto_queue)
-  
-  # Load MMA config
-  try:
-   config      = models.load_config()
-   mma_cfg     = config.get("mma", {})
-   max_workers = mma_cfg.get("max_workers", 4)
-  except Exception:
-   max_workers = 4
-  
+
   self.pool =           WorkerPool(max_workers=max_workers)
   self._workers_lock =  threading.Lock()
   self._active_workers: dict[str, threading.Thread] = {}