Architecture Audit — Circular Dependencies
Found by Argus code quality audit (May 29, 2026).
Circular Dependencies (source files, not tests)
services/acp/session-service.ts ↔ pause-intervention.ts
services/acp/index.ts ↔ terminal-bridge.ts
pipeline.ts ↔ services/state/state-store.ts
session.ts ↔ services/session/permissions.ts
services/state/state-store.ts ↔ session.ts ↔ persistence.ts (3-way)
session.ts ↔ session-discovery.ts
session.ts ↔ session-transcripts.ts
channels/telegram/types.ts ↔ topic-persistence.ts
Worst Offender
session.ts (842 lines) — involved in 5 of 10 cycles. This is the same file flagged in #4227 (server.ts extraction). The cycles make it harder to test, refactor, and reason about session lifecycle.
Proposed Resolution
Extract interfaces/types into separate files to break import cycles:
session-types.ts — shared types currently imported from session.ts
session-interfaces.ts — service interfaces
- Use dependency injection instead of direct imports where possible
- Introduce event-driven communication to replace circular service references
Rules
- One PR per cycle or group of related cycles
- All tests must pass after each fix
- No behavior changes — purely structural
Acceptance Criteria
Architecture Audit — Circular Dependencies
Found by Argus code quality audit (May 29, 2026).
Circular Dependencies (source files, not tests)
services/acp/session-service.ts↔pause-intervention.tsservices/acp/index.ts↔terminal-bridge.tspipeline.ts↔services/state/state-store.tssession.ts↔services/session/permissions.tsservices/state/state-store.ts↔session.ts↔persistence.ts(3-way)session.ts↔session-discovery.tssession.ts↔session-transcripts.tschannels/telegram/types.ts↔topic-persistence.tsWorst Offender
session.ts(842 lines) — involved in 5 of 10 cycles. This is the same file flagged in #4227 (server.ts extraction). The cycles make it harder to test, refactor, and reason about session lifecycle.Proposed Resolution
Extract interfaces/types into separate files to break import cycles:
session-types.ts— shared types currently imported from session.tssession-interfaces.ts— service interfacesRules
Acceptance Criteria
npx madge --circular src/reports 0 circular dependencies