arch: 10 circular dependencies + 19 oversized files — dependency map

[OneStepAt4time]

Circular Dependencies (10 found via madge --circular)

session.ts (842 lines) is the hub — involved in 5 of 10 cycles.

1) services/acp/session-service.ts > services/acp/pause-intervention.ts
2) services/acp/index.ts > services/acp/terminal-bridge.ts
3) pipeline.ts > services/state/state-store.ts
4) session.ts > services/session/permissions.ts
5) services/state/state-store.ts > session.ts > services/session/persistence.ts
6) session.ts > services/session/persistence.ts
7) services/state/state-store.ts > session.ts
8) session.ts > session-discovery.ts
9) session.ts > session-transcripts.ts
10) channels/telegram/types.ts > channels/telegram/topic-persistence.ts

Oversized Files (19 files over 500 lines, source only)

Lines	File
1296	src/routes/openapi.ts
1246	src/services/acp/backend.ts
1195	src/services/acp/local-storage.ts
1085	src/commands/init.ts
1030	src/acp-lifecycle/ndjson-rpc-transport.ts
973	src/validation.ts
961	src/acp-terminal-extension-probe.ts
904	src/services/auth/AuthManager.ts
871	src/monitor.ts
858	src/services/acp/terminal-bridge.ts
842	src/session.ts
841	src/commands/run.ts
810	src/audit.ts
783	src/services/acp/redis-coordination.ts
760	src/routes/sessions.ts
734	src/config/index.ts
704	src/doctor.ts
696	src/services/acp/json-rpc-client.ts
669	src/server.ts

as any Count: 5 (surprisingly clean)

• src/services/session/approval-flow.ts — 2
• src/redis-event-bus.ts — 1
• src/monitor.ts — 1
• src/events.ts — 1

Related

• refactor(server): extract routes and bootstrap from server.ts #4227 — refactor(server): extract routes and bootstrap from server.ts (session.ts cycles directly block this)
• arch(acp-lifecycle-probe.ts): 1521-line file mixing protocol, lifecycle, permissions, and process management #4242 — arch(acp-lifecycle-probe.ts): 1521-line file mixing concerns

Notes

• Data collected 2026-05-29 via madge --circular and wc -l on develop
• session.ts is the highest-priority target: 5 cycles, 842 lines, central to the codebase
• No implementation suggestions — this issue is a dependency map for whoever tackles the refactoring

[aegis-gh-agent]

Updated status after #4492 merge (2026-05-29)

Before #4492: 10 circular deps (session.ts in 5)
After #4492: 5 circular deps (session.ts in ZERO)

Remaining cycles:

1) services/acp/session-service.ts > services/acp/pause-intervention.ts
2) services/acp/index.ts > services/acp/terminal-bridge.ts
3) metrics.ts > metrics-aggregation.ts (NEW — not in original audit)
4) pipeline.ts > services/state/state-store.ts
5) channels/telegram/types.ts > channels/telegram/topic-persistence.ts

Cycle #3 is new — metrics-aggregation.ts was extracted from metrics.ts recently, creating a new bidirectional import. Should be fixable with the same type-only import redirect pattern.

Files over 500 lines: 19 (unchanged — #4492 was type-only, no size reduction)
as any count: 5 (unchanged)

[OneStepAt4time]

Status Update — 2026-05-29 20:00 CET

Circular deps: 10 → 11 (regression)

Ran madge --circular --extensions ts src/ on current develop (commit a036c8f).

All 10 original cycles are STILL PRESENT. No cycles were actually fixed.

Additionally, 1 new cycle was introduced by the metrics split (#4492):

• metrics.ts > metrics-aggregation.ts (NEW)

What happened to #4492?

PR #4492 merged at 16:44 UTC, claiming 11 → 5 cycles. It changed 8 files to import types from session-types.js instead of session.js.

However, commit 344ae37 ("fix(i18n): remove duplicate approveFailed/rejectFailed keys") recreated several of those files with the OLD imports. The session-discovery.ts file appears as "new file" in that commit with from './session.js' — the #4492 redirect was silently reverted during merge conflict resolution.

Verification: All 8 files that #4492 changed still import from session.js, not session-types.js:

session-discovery.ts → from './session.js'
session-transcripts.ts → from './session.js' (x2)
stall-detector.ts → from './session.js'
services/session/permissions.ts → from '../../session.js'
services/session/persistence.ts → from '../../session.js'
services/state/state-store.ts → from '../../session.js'
services/interfaces.ts → from '../session.js'
mcp/client.ts → from '../session.js'

Current cycle count: 11

#	Cycle	Status
1	session-service > pause-intervention	Original
2	acp/index > terminal-bridge	Original
3	metrics > metrics-aggregation	NEW (#4492 side-effect)
4	pipeline > state-store	Original
5	session > session/permissions	Original
6	state-store > session > session/persistence	Original
7	session > session/persistence	Original
8	state-store > session	Original
9	session > session-discovery	Original
10	session > session-transcripts	Original
11	telegram/types > telegram/topic-persistence	Original

Note on check-circular-deps.sh

The gate script runs npx madge --circular src without --extensions ts, which causes madge to process 0 files and report a false negative. The 11 cycles above were found with --extensions ts.

Recommended action

The #4492 fix needs to be re-applied (all 8 files redirected to session-types.js). Additionally, the new metrics > metrics-aggregation cycle should be broken the same way.

[OneStepAt4time]

Current State (post-PR #4492 + #4496)

Original count: 11 circular dependencies (10 per Argus audit + 1 additional found by madge)

Resolved by #4492: 7 session.ts cycles broken (type imports redirected to session-types.ts)
Resolved by #4496: 3 additional real runtime cycles broken

Remaining: 2 type-only false positives (zero runtime impact)

Cycle	Type	Status
pipeline.ts ↔ state-store.ts	import type only	No circular require in compiled JS
telegram/types.ts ↔ topic-persistence.ts	import type only	types.js compiles to export {}

Both remaining cycles are artifacts of madge's static analysis not understanding import type erasure in TypeScript. Verified with compiled output inspection — zero circular requires at runtime.

Recommendation: close this issue once #4496 merges. The 2 remaining "cycles" are not bugs.

[OneStepAt4time]

Correction: no metrics.ts regression

Re-checked both develop and PR #4496 branch — the metrics.ts > metrics-aggregation.ts cycle does NOT exist. The metrics re-exports were removed in an earlier merge to develop, so that cycle was already broken before #4496.

Develop (current): 4 cycles (3 real + 2 type-only, but madge counts 4 distinct paths)
PR #4496 branch: 2 cycles (both type-only, zero runtime impact)

#4496 eliminates the 3 remaining real cycles. No regressions introduced.