docs: update file inventory and module header contracts

Refresh both AGENTS guides and clarify module purpose, usage, ownership, threading, return values and wire formats in headers. Remove the unused timeout_heap freed_count field and unimplemented getter.

src/proxy/icmp_proxy.h

@@ -1,4 +1,7 @@
-// icmp_proxy.h — ICMP echo (ping) прокси: клиент ↔ exit через etcp_router
+/* IPv4 ICMP echo через UTUN-router: exit отправляет ping через raw socket, сопоставляет reply
+ * по собственному wire id/seq и восстанавливает исходные id/seq клиента. Запросы ограничены таймаутом.
+ * init/destroy и callbacks — в uasync; контекст принадлежит inst, роль берётся из tcp_proxy_server.enabled.
+ * test_loopback возвращает виртуальные ответы без сетевой отправки и предназначен для тестов. */
 #ifndef ICMP_PROXY_H
 #define ICMP_PROXY_H
 

src/proxy/socks_proxy.h

@@ -1,4 +1,6 @@
-// socks_proxy.h — SOCKS5 / HTTP CONNECT proxy (client side)
+/* Локальные SOCKS5 CONNECT и HTTP proxy/CONNECT: DNS, handshake и передача TCP через удалённый exit.
+ * tcp_proxy_client владеет listener и списками соединений; их callbacks выполняются в uasync.
+ * init_listen заимствует указатели на списки/счётчики до close_listen; закрытие listener не освобождает клиентов. */
 #ifndef SOCKS_PROXY_H
 #define SOCKS_PROXY_H
 
@@ -81,13 +83,13 @@ struct listen_ctx* socks_proxy_init_listen(struct UASYNC* ua, const char* addr_s
     struct UTUN_INSTANCE* inst, uint64_t via_node_id, int is_http);
 
 // Закрыть слушающий сокет и освободить listen_ctx.
-// sock_out получает значение сокета (для последующего close).
+// Если sock_out задан, в него записывается SOCKET_INVALID: сокет уже закрыт.
 void socks_proxy_close_listen(struct UASYNC* ua, struct listen_ctx* ctx, socket_t* sock_out);
 
 // Найти соединение по stream_id
 struct socks_proxy_conn* socks_proxy_find_conn(struct socks_proxy_conn* head, uint32_t stream_id);
 
-// Обработать входящее ETCP сообщение (DATA/CLOSE/ERROR/FIN)
+// Обработать ответ exit: CONNECTED/DATA/WINDOW_UPDATE/CLOSE/ERROR/FIN.
 // Возвращает 1 если обработано, 0 если stream_id не найден
 int socks_proxy_handle_etcp(struct socks_proxy_conn** head, int* count,
                             uint32_t stream_id, uint8_t subcmd,

src/proxy/tcp_proxy_client.h

@@ -1,4 +1,7 @@
-// tcp_proxy_client.h — TCP прокси-клиент: стек lwIP TCP → ETCP → удалённый exit узел
+/* Клиент TCP-прокси: принимает IPv4 с отдельного TUN через lwIP либо TCP от SOCKS/HTTP listener.
+ * Передаёт потоки через UTUN-router на via_node_id; proxy_flow обеспечивает окно и backpressure.
+ * create/destroy и callbacks — в uasync. Владеет созданными TUN/lwIP/listener/потоками,
+ * заимствует inst/ua/mappings до destroy. Без tun_name/tun_ip может работать только SOCKS/HTTP. */
 #ifndef TCP_PROXY_CLIENT_H
 #define TCP_PROXY_CLIENT_H
 

src/proxy/tcp_proxy_server.h

@@ -1,4 +1,7 @@
-// tcp_proxy_server.h — TCP прокси-сервер (exit node)
+/* Exit TCP-прокси: принимает CONNECT/DATA через UTUN-router и открывает обычный TCP к назначению.
+ * Поток определяется парой peer_node_id/stream_id; proxy_flow согласует окна и half-close.
+ * init учитывает tcp_proxy_server_enabled в конфиге; destroy закрывает потоки и общий UDP/ICMP-прокси.
+ * Состояние принадлежит UTUN_INSTANCE, операции и callbacks выполняются в его uasync-потоке. */
 #ifndef TCP_PROXY_SERVER_H
 #define TCP_PROXY_SERVER_H
 

src/proxy/udp_proxy.h

@@ -1,4 +1,6 @@
-// udp_proxy.h — UDP датаграммный прокси: клиент ↔ exit через etcp_router
+/* UDP из TUN через UTUN-router: клиент отправляет REQUEST, exit открывает сокет для кортежа адресов
+ * и возвращает REPLY. Потоки exit удаляются по таймауту неактивности.
+ * init/destroy и callbacks — в uasync; контекст принадлежит inst, роль берётся из tcp_proxy_server.enabled. */
 #ifndef UDP_PROXY_H
 #define UDP_PROXY_H