Module agents_consolidate 

Phase 3a — one-shot backfill from db_agent_definitions + db_agent_instances into the new consolidated db_agents table.

See docs/specs/SPEC_AGENT_CONCEPT_CONSOLIDATION_2026_05_24.md.

Phase 3a is write-only: this migration populates db_agents so a later Phase 3b PR can flip readers over with full confidence the data is there. Phase 3c drops the old tables.

Marker-file gated (<data_dir>/migration_agents_consolidate_v1.flag) so the backfill only runs once per data dir. Idempotent on second run (marker check short-circuits).

Algorithm (per spec §“What db_agent_instances rows become”):

1. For each db_agent_definitions WHERE is_seeded = 1: INSERT a template projection (is_template = 1, bindings empty).

2. For each db_agent_definitions WHERE is_seeded = 0: INSERT a user-clone projection (is_template = 0, parent_template_id = parent_id).

3. For each db_agent_instances row whose definition_id points at a TEMPLATE: INSERT a new user-clone projection keyed by instance.id, parent_template_id = definition_id, name + bindings from the instance.

4. For each db_agent_instances row whose definition_id points at an already-user-cloned definition: UPDATE the existing user-clone projection (keyed by the definition id from pass 2) to fold in the instance’s bindings. If multiple instances point at the same user-clone, the most-recent (created_at DESC) wins and a warning is logged.

Continuation rows (parent_instance_id non-empty) are skipped — the consolidated model has no place for them; they were the pre-Option-E continuation chain.

Structs

ConsolidateStats

Backfill statistics — useful for logs + tests.

DefRow 🔒

Snapshot of one db_agent_definitions row, narrow projection matching what the backfill needs.

InstanceRow 🔒

Snapshot of one db_agent_instances row plus the LEFT-JOINed definition fields the backfill copies into db_agents.

Constants

CONSOLIDATE_MARKER

Marker filename. Lives in the data dir (one level above the db/ subdir that holds objects.db).

Functions

run_consolidate_migration

Run the one-shot consolidation backfill, gated by the marker file.