[Phase 5] Dynamic Configuration Reload During Batch Execution

[frankbria]

Summary

Watch for changes to AGENTS.md/CLAUDE.md/CODEFRAME.md during long-running batch executions and hot-reload configuration without restarting. Inspired by Symphony's dynamic WORKFLOW.md reload pattern.

Motivation

During multi-hour batch runs (cf work batch run --all-ready), operators may need to adjust agent behavior — change the prompt, adjust concurrency, modify gate configuration. Currently this requires killing and restarting the batch. Symphony solves this with filesystem watching and automatic config reload.

This is lower priority because single-task execution is short-lived, but it becomes important for Phase 4 multi-agent scenarios where batch runs may run for hours.

Design

Scope (single session)

1. File watcher: Use watchdog or inotify to monitor config files for changes
2. Reload logic in core/agents_config.py:
   • On file change: re-parse config
   • Validate new config (don't apply if invalid)
   • Log reload event with diff summary
   • Apply to future task dispatches (don't restart in-flight agents)
3. Integration with conductor:
   • core/conductor.py checks for config updates between task dispatches
   • New concurrency/strategy settings apply to remaining tasks
   • New prompt/agent settings apply to next agent launch
4. Safety:
   • Invalid config reload → keep last known good config, log error
   • Config reload during agent execution → queued, applied after current task

What reloads dynamically

• Agent prompt / system prompt supplement
• Concurrency limits (max_parallel)
• Gate configuration
• Hook scripts (for future tasks)
• Stall timeout

What requires restart

• Engine selection (react/plan)
• Workspace path
• Tech stack

Acceptance Criteria

• Config file changes detected within 5 seconds during batch execution
• Valid config changes applied to subsequent task dispatches
• Invalid config changes logged as error, previous config retained
• In-flight agent tasks not interrupted by config reload
• cf work batch status shows "config reloaded at HH:MM:SS" if reload occurred
• Integration test: modify config during batch, verify next task uses new config

Dependencies

• Benefits from [Phase 5] Unified CODEFRAME.md Workflow Config #398 (unified CODEFRAME.md) — single file to watch
• No hard prerequisites

[coderabbitai]

🔗 Related PRs

#11 - feat: Convert worker agents to async/await pattern (cf-48) [merged]
#246 - feat(agents): trigger multi-agent execution after task approval [merged]
#356 - fix: agent execution resilience + Phase 2.5 architecture research [merged]
#363 - feat: wire ReactAgent into runtime with --engine react CLI flag [merged]
#384 - feat: adaptive iteration budget, autofix, and loop detection for ReactAgent [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

Plan

Observations

• watchdog is not in pyproject.toml dependencies; Python's standard library threading + time-based polling (already used in events.tail) is the available mechanism.
• core/agents_config.py has a clean load_preferences() function parsing AGENTS.md/CLAUDE.md into AgentPreferences, but it is stateless — no caching or reload logic.
• core/conductor.py drives all batch execution through _execute_serial and _execute_parallel, both of which already have a between-task loop that checks cancellation via get_batch(). This is the natural reload-check injection point.
• core/events.py has EventType as a plain class with string constants, and emit_for_workspace() is the standard emission path.
• batch_status in cli/app.py renders a plain text panel — adding a "config reloaded at HH:MM:SS" line is straightforward.
• BatchRun dataclass has no metadata field for reload events; one needs to be added.

Approach

Since watchdog is absent, use a polling-based file watcher running on a threading.Thread — matching the existing events.tail polling pattern (no new dependencies). The watcher compares file mtime every ~2 seconds, re-parses on change, validates, and stores the result in a shared ConfigReloadState object. The conductor queries this state between task dispatches. Reload timestamps are stored directly in BatchRun so batch_status can display them.

---

Implementation Steps

1. Extend BatchRun — add config_reloads metadata field

In file:codeframe/core/conductor.py, add a config_reloads: list[str] field (list of ISO timestamp strings) to the BatchRun dataclass, defaulting to an empty list. This stores the times at which a config reload was applied during the batch.

Also extend _save_batch and _row_to_batch to persist/restore the new field as a JSON column in the batch_runs table. (If altering the schema is not feasible in the current migration story, store it in the existing results dict under a reserved key like "__config_reloads__".)

---

2. Create core/config_watcher.py — the file watcher component

Create a new module file:codeframe/core/config_watcher.py with:

ConfigReloadState dataclass

• current_prefs: AgentPreferences — last known good config
• last_reload_at: Optional[datetime] — timestamp of last successful reload
• last_error: Optional[str] — last validation error message
• _lock: threading.Lock — for thread-safe access
• Methods: get_prefs(), apply_reload(new_prefs, timestamp), record_error(msg)

ConfigFileWatcher class

• Constructor accepts workspace_path: Path, poll_interval_seconds: float = 2.0
• Internally tracks _watched_files: dict[Path, float] mapping config file paths (AGENTS.md, CLAUDE.md, CODEFRAME.md) to their last-seen mtime
• Holds a ConfigReloadState reference
• start(initial_prefs: AgentPreferences) -> ConfigReloadState — starts the background threading.Thread (daemon=True) and returns the shared state object
• stop() — signals the polling thread to exit via a threading.Event
• _poll_loop() — the thread body: every poll_interval_seconds, calls _check_for_changes()
• _check_for_changes() — iterates watched files, compares current mtime to stored; on any change, calls _reload()
• _reload() — calls load_preferences(workspace_path) from agents_config, performs basic validation (e.g., prefs.has_preferences() and sanity-check that never_do is non-empty or any invariant that signals a parse failure), then either calls state.apply_reload(new_prefs, _utc_now()) or state.record_error(msg) and emits an appropriate event

Validation logic (what counts as "valid"):

• _parse_agents_md did not raise an exception
• The resulting AgentPreferences has at least a non-empty raw_content or some field populated
• If the file is empty/unreadable → treat as invalid, log, retain previous config

Logging on reload — use events.emit_for_workspace with a new EventType.CONFIG_RELOADED or EventType.CONFIG_RELOAD_FAILED constant, including a diff summary built by comparing old vs new field values (e.g., which keys changed in tooling, commands, which items added/removed from never_do).

sequenceDiagram
    participant FS as Filesystem
    participant CW as ConfigFileWatcher (thread)
    participant State as ConfigReloadState
    participant Conductor as conductor._execute_serial

    loop Every 2s
        CW->>FS: stat(AGENTS.md mtime)
        alt mtime changed
            CW->>CW: load_preferences()
            CW->>CW: validate new prefs
            alt valid
                CW->>State: apply_reload(new_prefs, now)
                CW->>Events: emit CONFIG_RELOADED
            else invalid
                CW->>State: record_error(msg)
                CW->>Events: emit CONFIG_RELOAD_FAILED
            end
        end
    end

    Conductor->>State: get_prefs() [between tasks]
    State-->>Conductor: current AgentPreferences

---

3. Add CONFIG_RELOADED and CONFIG_RELOAD_FAILED event types

In file:codeframe/core/events.py, add two new constants to the EventType class:

• CONFIG_RELOADED = "CONFIG_RELOADED"
• CONFIG_RELOAD_FAILED = "CONFIG_RELOAD_FAILED"

The event color map in _get_event_color should return "green" for CONFIG_RELOADED and "red" for CONFIG_RELOAD_FAILED (already covered by the existing COMPLETED/FAILED substring check, so no change needed there).

---

4. Integrate the watcher into start_batch in core/conductor.py

In file:codeframe/core/conductor.py, modify the start_batch function:

1. Before calling _execute_serial / _execute_parallel, instantiate a ConfigFileWatcher(workspace_path=Path(workspace.repo_path)) and call watcher.start(initial_prefs=load_preferences(Path(workspace.repo_path))) to get back a ConfigReloadState.
2. Pass reload_state: ConfigReloadState down to _execute_serial and _execute_parallel (and their helpers) as an optional parameter.
3. In the finally block (or after the execution strategy call completes), call watcher.stop().

Between-task reload check in _execute_serial

At the top of the for i, task_id in enumerate(batch.task_ids) loop body — after the cancellation check — add a call to a helper _apply_pending_config_reload(batch, workspace, reload_state). This helper:

• Calls reload_state.get_prefs() to see if a new reload happened since the last check (compare last_reload_at to a locally tracked _last_seen_reload_at)
• If a new reload occurred, appends the reload timestamp to batch.config_reloads, calls _save_batch, and prints a notice to the terminal
• The reload applies to the next task dispatch: newly reloaded max_parallel, on_failure etc. are read from the returned prefs object for subsequent logic

Between-task reload check in _execute_parallel

In the parallel execution loop (wherever a dispatch group completes and the next group is about to start), add the same _apply_pending_config_reload helper call. Thread safety is handled by ConfigReloadState._lock.

Reloading max_parallel

In _execute_parallel, max_parallel is currently read from batch.max_parallel. Change the parallel dispatch to read it from reload_state.get_prefs() if a reload has occurred (or from the batch default if not). Since the ticket restricts this to config items that are safe to apply to future dispatches, only max_parallel from the reloaded config object needs to be acted upon at the conductor level (prompt/agent settings flow through AgentPreferences which is already read at agent launch time).

---

5. Update batch_status CLI command to display reload timestamps

In file:codeframe/cli/app.py, in the batch_status command's single-batch display block (around line 3071), after printing Status and Duration, add:

if batch.config_reloads:
    for ts in batch.config_reloads:
        console.print(f"  Config reloaded at {ts}")

Format ts as HH:MM:SS (parse the ISO string and call .strftime("%H:%M:%S")).

---

6. Decide which config fields map to which reload categories

To match the ticket's "What reloads dynamically" list, document (in config_watcher.py docstring) which AgentPreferences fields map to each category:

Config field	Reload category	Applied when
always_do, ask_first, never_do, raw_content	Agent prompt / system prompt supplement	Next agent launch (subprocess reads prefs at start)
tooling → (future: max_parallel, stall_timeout)	Concurrency / timeout	Between dispatch groups (conductor reads from state)
commands	Hook scripts	Next agent subprocess

Since max_parallel is not currently a field of AgentPreferences (it's a BatchRun attribute set at batch creation), the watcher only needs to feed AgentPreferences updates to the state object. The conductor can optionally read a special tooling["max_parallel"] key from the reloaded prefs and update batch.max_parallel in-memory (not persisted to DB, since it's a runtime adjustment).

---

7. Ensure in-flight agents are not interrupted

The watcher never signals running subprocesses. _execute_task_subprocess uses Popen.wait() — the watcher thread runs independently and only updates the ConfigReloadState in memory. The _apply_pending_config_reload helper is only called between tasks (before the next _execute_task_subprocess invocation), so in-flight tasks are completely unaffected.

---

8. Database schema migration for config_reloads field

If a new column is added to batch_runs, add the migration in the workspace initialization code (wherever CREATE TABLE batch_runs is defined, likely in file:codeframe/core/workspace.py or a migrations module). The migration should use ALTER TABLE batch_runs ADD COLUMN config_reloads TEXT with a default of NULL (treated as empty list when deserialized).

Alternatively, store reload timestamps inside the existing results JSON dict under a reserved __config_reloads__ key to avoid a schema migration entirely.

Import In IDE

🤖 Prompt for AI Agents

## Observations

- `watchdog` is **not** in `pyproject.toml` dependencies; Python's standard library `threading` + `time`-based polling (already used in `events.tail`) is the available mechanism.
- `core/agents_config.py` has a clean `load_preferences()` function parsing AGENTS.md/CLAUDE.md into `AgentPreferences`, but it is stateless — no caching or reload logic.
- `core/conductor.py` drives all batch execution through `_execute_serial` and `_execute_parallel`, both of which already have a between-task loop that checks cancellation via `get_batch()`. This is the natural reload-check injection point.
- `core/events.py` has `EventType` as a plain class with string constants, and `emit_for_workspace()` is the standard emission path.
- `batch_status` in `cli/app.py` renders a plain text panel — adding a "config reloaded at HH:MM:SS" line is straightforward.
- `BatchRun` dataclass has no metadata field for reload events; one needs to be added.

## Approach

Since `watchdog` is absent, use a **polling-based file watcher** running on a `threading.Thread` — matching the existing `events.tail` polling pattern (no new dependencies). The watcher compares file `mtime` every ~2 seconds, re-parses on change, validates, and stores the result in a shared `ConfigReloadState` object. The conductor queries this state between task dispatches. Reload timestamps are stored directly in `BatchRun` so `batch_status` can display them.

---

## Implementation Steps

### 1. Extend `BatchRun` — add `config_reloads` metadata field

In `file:codeframe/core/conductor.py`, add a `config_reloads: list[str]` field (list of ISO timestamp strings) to the `BatchRun` dataclass, defaulting to an empty list. This stores the times at which a config reload was applied during the batch.

Also extend `_save_batch` and `_row_to_batch` to persist/restore the new field as a JSON column in the `batch_runs` table. (If altering the schema is not feasible in the current migration story, store it in the existing `results` dict under a reserved key like `"__config_reloads__"`.)

---

### 2. Create `core/config_watcher.py` — the file watcher component

Create a new module `file:codeframe/core/config_watcher.py` with:

**`ConfigReloadState` dataclass**
- `current_prefs: AgentPreferences` — last known good config
- `last_reload_at: Optional[datetime]` — timestamp of last successful reload
- `last_error: Optional[str]` — last validation error message
- `_lock: threading.Lock` — for thread-safe access
- Methods: `get_prefs()`, `apply_reload(new_prefs, timestamp)`, `record_error(msg)`

**`ConfigFileWatcher` class**
- Constructor accepts `workspace_path: Path`, `poll_interval_seconds: float = 2.0`
- Internally tracks `_watched_files: dict[Path, float]` mapping config file paths (`AGENTS.md`, `CLAUDE.md`, `CODEFRAME.md`) to their last-seen `mtime`
- Holds a `ConfigReloadState` reference
- `start(initial_prefs: AgentPreferences) -> ConfigReloadState` — starts the background `threading.Thread` (daemon=True) and returns the shared state object
- `stop()` — signals the polling thread to exit via a `threading.Event`
- `_poll_loop()` — the thread body: every `poll_interval_seconds`, calls `_check_for_changes()`
- `_check_for_changes()` — iterates watched files, compares current `mtime` to stored; on any change, calls `_reload()`
- `_reload()` — calls `load_preferences(workspace_path)` from `agents_config`, performs basic validation (e.g., `prefs.has_preferences()` and sanity-check that `never_do` is non-empty or any invariant that signals a parse failure), then either calls `state.apply_reload(new_prefs, _utc_now())` or `state.record_error(msg)` and emits an appropriate event

**Validation logic** (what counts as "valid"):
- `_parse_agents_md` did not raise an exception
- The resulting `AgentPreferences` has at least a non-empty `raw_content` or some field populated
- If the file is empty/unreadable → treat as invalid, log, retain previous config

**Logging on reload** — use `events.emit_for_workspace` with a new `EventType.CONFIG_RELOADED` or `EventType.CONFIG_RELOAD_FAILED` constant, including a diff summary built by comparing old vs new field values (e.g., which keys changed in `tooling`, `commands`, which items added/removed from `never_do`).

```
sequenceDiagram
    participant FS as Filesystem
    participant CW as ConfigFileWatcher (thread)
    participant State as ConfigReloadState
    participant Conductor as conductor._execute_serial

    loop Every 2s
        CW->>FS: stat(AGENTS.md mtime)
        alt mtime changed
            CW->>CW: load_preferences()
            CW->>CW: validate new prefs
            alt valid
                CW->>State: apply_reload(new_prefs, now)
                CW->>Events: emit CONFIG_RELOADED
            else invalid
                CW->>State: record_error(msg)
                CW->>Events: emit CONFIG_RELOAD_FAILED
            end
        end
    end

    Conductor->>State: get_prefs() [between tasks]
    State-->>Conductor: current AgentPreferences
```

---

### 3. Add `CONFIG_RELOADED` and `CONFIG_RELOAD_FAILED` event types

In `file:codeframe/core/events.py`, add two new constants to the `EventType` class:
- `CONFIG_RELOADED = "CONFIG_RELOADED"`
- `CONFIG_RELOAD_FAILED = "CONFIG_RELOAD_FAILED"`

The event color map in `_get_event_color` should return `"green"` for `CONFIG_RELOADED` and `"red"` for `CONFIG_RELOAD_FAILED` (already covered by the existing `COMPLETED`/`FAILED` substring check, so no change needed there).

---

### 4. Integrate the watcher into `start_batch` in `core/conductor.py`

In `file:codeframe/core/conductor.py`, modify the `start_batch` function:

1. Before calling `_execute_serial` / `_execute_parallel`, instantiate a `ConfigFileWatcher(workspace_path=Path(workspace.repo_path))` and call `watcher.start(initial_prefs=load_preferences(Path(workspace.repo_path)))` to get back a `ConfigReloadState`.
2. Pass `reload_state: ConfigReloadState` down to `_execute_serial` and `_execute_parallel` (and their helpers) as an optional parameter.
3. In the `finally` block (or after the execution strategy call completes), call `watcher.stop()`.

**Between-task reload check in `_execute_serial`**

At the top of the `for i, task_id in enumerate(batch.task_ids)` loop body — after the cancellation check — add a call to a helper `_apply_pending_config_reload(batch, workspace, reload_state)`. This helper:
- Calls `reload_state.get_prefs()` to see if a new reload happened since the last check (compare `last_reload_at` to a locally tracked `_last_seen_reload_at`)
- If a new reload occurred, appends the reload timestamp to `batch.config_reloads`, calls `_save_batch`, and prints a notice to the terminal
- The reload applies to the **next** task dispatch: newly reloaded `max_parallel`, `on_failure` etc. are read from the returned prefs object for subsequent logic

**Between-task reload check in `_execute_parallel`**

In the parallel execution loop (wherever a dispatch group completes and the next group is about to start), add the same `_apply_pending_config_reload` helper call. Thread safety is handled by `ConfigReloadState._lock`.

**Reloading `max_parallel`**

In `_execute_parallel`, `max_parallel` is currently read from `batch.max_parallel`. Change the parallel dispatch to read it from `reload_state.get_prefs()` if a reload has occurred (or from the batch default if not). Since the ticket restricts this to config items that are safe to apply to future dispatches, only `max_parallel` from the reloaded config object needs to be acted upon at the conductor level (prompt/agent settings flow through `AgentPreferences` which is already read at agent launch time).

---

### 5. Update `batch_status` CLI command to display reload timestamps

In `file:codeframe/cli/app.py`, in the `batch_status` command's single-batch display block (around line 3071), after printing `Status` and `Duration`, add:

```
if batch.config_reloads:
    for ts in batch.config_reloads:
        console.print(f"  Config reloaded at {ts}")
```

Format `ts` as `HH:MM:SS` (parse the ISO string and call `.strftime("%H:%M:%S")`).

---

### 6. Decide which config fields map to which reload categories

To match the ticket's "What reloads dynamically" list, document (in `config_watcher.py` docstring) which `AgentPreferences` fields map to each category:

| Config field | Reload category | Applied when |
|---|---|---|
| `always_do`, `ask_first`, `never_do`, `raw_content` | Agent prompt / system prompt supplement | Next agent launch (subprocess reads prefs at start) |
| `tooling` → (future: `max_parallel`, `stall_timeout`) | Concurrency / timeout | Between dispatch groups (conductor reads from state) |
| `commands` | Hook scripts | Next agent subprocess |

Since `max_parallel` is not currently a field of `AgentPreferences` (it's a `BatchRun` attribute set at batch creation), the watcher **only** needs to feed `AgentPreferences` updates to the state object. The conductor can optionally read a special `tooling["max_parallel"]` key from the reloaded prefs and update `batch.max_parallel` in-memory (not persisted to DB, since it's a runtime adjustment).

---

### 7. Ensure in-flight agents are not interrupted

The watcher never signals running subprocesses. `_execute_task_subprocess` uses `Popen.wait()` — the watcher thread runs independently and only updates the `ConfigReloadState` in memory. The `_apply_pending_config_reload` helper is only called between tasks (before the next `_execute_task_subprocess` invocation), so in-flight tasks are completely unaffected.

---

### 8. Database schema migration for `config_reloads` field

If a new column is added to `batch_runs`, add the migration in the workspace initialization code (wherever `CREATE TABLE batch_runs` is defined, likely in `file:codeframe/core/workspace.py` or a migrations module). The migration should use `ALTER TABLE batch_runs ADD COLUMN config_reloads TEXT` with a default of `NULL` (treated as empty list when deserialized).

Alternatively, store reload timestamps inside the existing `results` JSON dict under a reserved `__config_reloads__` key to avoid a schema migration entirely.

---

Execution Information

Branch: main
Commit: 705b160

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.