autoreg-skills-max: initial public release (restored, redacted, hardened)

skills/telegram-mass-join/references/parallel-multi-process-execution.md

@@ -0,0 +1,86 @@
+# Parallel Multi-Process Join Execution
+
+## Motivation
+Single `join_assigned.py` on 174 accounts × 50 chats with 60s timeout = ~50 minutes. Most of that time is waiting for Telegram responses. Running 3 parallel processes on different account ranges cuts it to ~17 minutes.
+
+## CLI Arguments Added to `join_assigned.py`
+
+```
+--start N      First account index (0-based, default 0)
+--end N        Last account index (exclusive, default all)
+--timeout S    Account hard timeout in seconds (default 120)
+--pause S      Inter-batch pause in seconds (default 15)
+--suffix STR   Progress file suffix (e.g. "_1", "_2", "_3")
+```
+
+## Launch Pattern
+
+174 accounts → 3 processes of 58 each:
+
+```bash
+python -u join_assigned.py --start 0 --end 58 --suffix _1 --timeout 120 --pause 15 &
+python -u join_assigned.py --start 58 --end 116 --suffix _2 --timeout 120 --pause 15 &
+python -u join_assigned.py --start 116 --end 174 --suffix _3 --timeout 120 --pause 15 &
+```
+
+## Why 120s Timeout for 50 Chats
+
+Each chat join takes ~2-3 seconds (get_entity + JoinChannelRequest + random delay). 50 chats × 2.5s avg = 125s. 120s timeout covers most accounts while still catching true hangs.
+
+With 60s timeout and 50 chats → almost all accounts hit hard_timeout. 120s is the sweet spot.
+
+## Progress File Isolation
+
+Each process uses its own progress file:
+- `assigned_join_progress_1.json`
+- `assigned_join_progress_2.json`
+- `assigned_join_progress_3.json`
+
+Each writes to its own `joined_chats{suffix}.json` (NOT shared — race condition otherwise). After all finish:
+
+```bash
+python merge_joined.py
+```
+
+`merge_joined.py` loads all `joined_chats*.json`, deduplicates by username/id, writes to `joined_chats.json`.
+
+### ⚠️ Race Condition on Shared Progress File
+When 3+ processes read/write the same `joined_chats.json`, they overwrite each other's data. Last save wins → ~58% data loss (47 of 81 new joins lost in one run). **Each process MUST use its own suffix throughout:**
+
+| File | Process _1 | Process _2 | Process _3 |
+|------|-----------|-----------|-----------|
+| Joined chats | `joined_chats_1.json` | `joined_chats_2.json` | `joined_chats_3.json` |
+| Progress | `assigned_join_progress_1.json` | `assigned_join_progress_2.json` | `assigned_join_progress_3.json` |
+
+Merge step is mandatory after parallel runs.
+
+## Python Pitfalls Encountered
+
+### 1. `global` before any reference
+```python
+# CRASH: SyntaxError: name 'ACCOUNT_TIMEOUT' is used prior to global declaration
+async def main():
+    parser.add_argument("--timeout", default=ACCOUNT_TIMEOUT)
+    global ACCOUNT_TIMEOUT  # too late
+
+# FIX: global first
+async def main():
+    global ACCOUNT_TIMEOUT, BATCH_PAUSE  # must be FIRST
+    parser.add_argument("--timeout", default=ACCOUNT_TIMEOUT)
+```
+
+### 2. Em-dash in docstrings
+```python
+# CRASH: SyntaxError: invalid character '—' (U+2014)
+"""Join chats — fast and targeted."""
+
+# FIX: use ASCII double dash
+"""Join chats -- fast and targeted."""
+```
+
+## Expected Results
+
+- 3× 58 accounts = 174 total
+- 3× 12 batches = 36 total batches
+- ~17 minutes total runtime
+- 500-1500 new joins (from 50 chats/account, most error out)