Refactor: sync/watch lifecycle via SyncCoordinator

[phernandez]

Refactor: sync/watch lifecycle via SyncCoordinator

Why

Background sync + watch lifecycle is a cross-cutting concern that can easily leak into initialization, routers, and MCP lifespan. Centralizing lifecycle improves reliability and reduces coupling.

Scope

• Introduce a SyncCoordinator responsible for:
  • starting/stopping watch service
  • scheduling background sync
  • reporting status
• Entrypoints decide when to start it (API/MCP/CLI) via their containers.

Acceptance criteria

• Lifecycle logic centralized in one place.
• Fewer scattered background-task conditionals.
• Stable shutdown behavior (especially in Postgres test mode where hangs were previously noted).

Dependencies

• After containers + deps split.

[claude]

Claude finished @phernandez's task in 1m 43s —— View job

---

Issue Triage Analysis

Tasks

• Read CLAUDE.md for context
• Search for duplicate issues
• Classify issue type, priority, component, and complexity
• Add appropriate labels
• Provide triage summary

---

Classification

Type: Enhancement (architectural refactoring)

Priority: Medium

• Improves reliability and reduces coupling
• Not critical/blocking, but addresses technical debt
• Will improve stability (especially in Postgres test mode where hangs were noted)

Component: Sync/Watch Services

• Located in /sync directory
• Cross-cutting concern affecting API, MCP, and CLI initialization

Complexity: Complex

• Architectural change requiring careful refactoring
• Touches multiple entry points (API/MCP/CLI)
• Needs to handle lifecycle management across different runtime modes
• Must ensure stable shutdown behavior

Duplicate Check

No duplicates found. This is a unique refactoring initiative.

Related Issues:

• Refactor: split deps.py into feature modules + reduce import graph #491 - Refactor: split deps.py into feature modules (listed as dependency)
• Restore 100% coverage; reduce mocks; fix sync/MCP correctness footguns #487 - Restore 100% coverage; reduce mocks; fix sync/MCP correctness footguns
• [BUG] Sync stops working with "cannot schedule new futures after shutdown" errors #443 - [BUG] Sync stops working with "cannot schedule new futures after shutdown" errors (closed)
• [BUG] --project flag doesn't constrain mcp's background sync to specified project #434 - [BUG] --project flag doesn't constrain mcp's background sync (closed)
• [BUG] MCP background basic-memory process utilizing CPU even as idle #448 - [BUG] MCP background process utilizing CPU even as idle (closed)

Analysis

This refactoring addresses a legitimate architectural concern. The sync/watch lifecycle is currently scattered across multiple initialization points, leading to:

• Coupling between initialization code and background services
• Difficulty managing stable shutdown (Postgres test hangs mentioned)
• Scattered background-task conditionals

Proposed Solution:
Introduce SyncCoordinator to centralize:

• Starting/stopping watch service
• Scheduling background sync
• Status reporting

Dependencies:

• Explicitly depends on Refactor: split deps.py into feature modules + reduce import graph #491 (containers + deps split)
• Should be implemented after that refactoring is complete

Labels Applied

• enhancement - Architectural improvement to existing functionality

Recommendation

This is a well-scoped refactoring with clear acceptance criteria. The dependency on #491 is appropriate since container/dependency refactoring should happen first. Once #491 is complete, this would be a good candidate for implementation.

Next Steps:

1. Wait for Refactor: split deps.py into feature modules + reduce import graph #491 to be completed
2. When ready to implement, consider:
   • Reviewing existing sync/watch initialization code across API/MCP/CLI
   • Designing SyncCoordinator interface
   • Ensuring test coverage for lifecycle scenarios
   • Special attention to shutdown behavior in Postgres mode

---