Parallel Agent Orphaned Module Wiring

Parallel Agent Orphaned Module Wiring

Problem

When parallel agents build modules in separate worktrees, each agent completes its scope but doesn’t wire the module into shared state (e.g., main.rs, state.rs, mod.rs). The modules are fully implemented with tests but are completely orphaned — either not mod-declared or band-aided with #[allow(dead_code)].

Symptoms:

• #[allow(dead_code)] on module declarations (e.g., ollama_manager)
• Files exist in src/ but have no mod declaration in main.rs
• cargo clippy --workspace reports entire modules as unused
• Modules have internal tests that pass, but nothing in the app calls them

Investigation

How It Happens

In wave-based parallel execution (see agent-team-orchestration-at-scale.md):

1. Wave N: Agent A builds ollama_manager.rs (700 lines, 14 tests)
2. Wave N: Agent B builds dspy_daemon.rs (500 lines, 12 tests)
3. Wave N: Agent C builds uv_manager.rs (414 lines, 11 tests)
4. Post-merge: Each agent completed its file scope, but none modified main.rs or state.rs (shared files assigned to other agents or deferred)
5. Result: Three fully-functional modules that nothing calls

Detection

# Find modules with #[allow(dead_code)] band-aids
grep -rn "allow(dead_code)" apps/desktop/src-tauri/src/main.rs

# Find .rs files not declared as modules
diff <(ls src/*.rs | sed 's|.*/||;s|\.rs||' | sort) \
     <(grep "^mod " src/main.rs | awk '{print $2}' | tr -d ';' | sort)

Root Cause

Wave-based parallel execution assigns file ownership to prevent merge conflicts. Shared integration files (main.rs, state.rs) are either:

• Assigned to a separate “wiring” agent that may not exist
• Deferred to a later wave that may not happen
• Each agent assumes another agent handles integration

The modules are “complete” within their scope but the integration step falls through the cracks.

Solution

1. Detect and Declare Modules

// main.rs — before (orphaned)
// ollama_manager.rs exists but no declaration
// dspy_daemon.rs exists but no declaration

// main.rs — after (declared with dead_code for now)
// Callers wired in Part 2: INK-690 (uv), INK-691 (dspy), INK-692 (ollama)
#[allow(dead_code)]
pub(crate) mod dspy_daemon;
#[allow(dead_code)]
pub(crate) mod ollama_manager;
#[allow(dead_code)]
pub(crate) mod uv_manager;

2. Wire into Shared State

// state.rs — add to ManagerBundle or AppState
pub struct ManagerBundle {
    // ... existing fields ...
    #[allow(dead_code)] // Callers: INK-692
    pub ollama_manager: Arc<OllamaManager>,
    #[allow(dead_code)] // Callers: INK-690
    pub venv_manager: tokio::sync::Mutex<VenvManager>,
    #[allow(dead_code)] // Callers: INK-691
    pub dspy_daemon: Arc<DspyDaemon>,
}

3. Bridge Clean Architecture Boundaries

When a module in the framework layer needs to be consumed by infrastructure, add a trait:

// In infrastructure crate (agent-harness) — defines the abstraction
#[async_trait]
pub trait DspyRuntime: Send + Sync {
    async fn execute_module(&self, skill_id: &str, module_code: &str,
        inputs: serde_json::Value) -> Result<serde_json::Value, String>;
}

// In framework layer (src-tauri) — implements via the orphaned module
impl DspyRuntime for DspyDaemonAdapter {
    // delegates to DspyDaemon::send()
}

4. Track Remaining Wiring as Issues

Each #[allow(dead_code)] should reference the issue that creates callers:

// Callers wired in Part 2: INK-690 (uv), INK-691 (dspy), INK-692 (ollama)
#[allow(dead_code)]
pub(crate) mod dspy_daemon;

Prevention

Best Practices

• Include a “wiring wave” in parallel execution plans — a final wave that integrates all modules
• Assign shared files explicitly — main.rs and state.rs must have a designated owner per wave
• Pre-include integration stubs — foundation wave adds empty module declarations and ManagerBundle fields before parallel agents create the implementations
• Post-merge audit — after merging all agent branches, run cargo clippy --workspace and look for dead_code on entire modules (not just individual items)

Warning Signs

• Agent issues say “Create X module” but don’t mention “Wire into AppState”
• Wave plan has no explicit “integration” or “wiring” task
• git log --stat shows new files added but main.rs/state.rs unchanged
• #[allow(dead_code)] appears in merge commits (band-aid applied during merge)

References

• INK-689: Wire OllamaManager/VenvManager/DspyDaemon into AppState
• docs/solutions/workflow-issues/agent-team-orchestration-at-scale.md
• docs/solutions/workflow-issues/derive-copy-cross-agent-ripple.md