Scheduler Workers

scheduler-workers

Concurrency-limited multi-task chain scheduler for CLI coding agents. Run many long-running tasks (e.g. model training scripts) in parallel under a parallelism cap, with exclusive/mutex segments, real-time human-in-the-loop, and resumable state — all via a **file-based protocol** and **detached headless workers**.

并发上限调度的多任务链框架（主 agent 事件循环 + 分离 headless worker）。协议跨 agent 通用；参考实现在 opencode（Windows PowerShell）验证通过。

---

What it solves / 解决什么

• Parallelism cap N with instant slot refill (running ≤ N always) — 并行度 N + 即时补位
• Task chains (ordered steps) as the scheduling unit — 任务链（有序步骤）为调度单位
• Exclusive/mutex segments — serialize "edit config → launch" to avoid version conflicts — 互斥段串行"改配置→启动"
• Real-time human-in-the-loop via file messages — 人在环实时交互
• Durable & resumable — state lives in marker files, survives interruptions — 持久化 + 断点续跑
• Long blocking waits (hours) without burning model tokens — 数小时长等待、零模型推理

How it works / 工作原理

main agent (event loop)                         workers (detached processes)
   │                                                 │
   ├─ launch N workers (Start-Process) ─────────────▶│  read chain def, run steps
   │                                                 │  write marker (.task-runner/runs/)
   │  ◀── messages (.task-runner/messages/) ─────────│  question / done / failed
   │  wait-event loop → wake on QUESTION/TERMINAL    │
   │  QUESTION → question tool → write answer ───────▶│  resume on answer
   │  TERMINAL → refill next chain (running ≤ N)     │

The protocol is **plain files + conventions** (`chain definition`, `marker`, `lock`, `message`), so any CLI agent can follow it.

Positioning & compatibility / 定位与兼容性

**Cross-agent, cross-OS protocol** — the reference implementation is tested on **opencode (Windows PowerShell)**.

Layer / 层	Portability / 通用性
Protocol & file formats / 协议与文件格式	✅ any agent, any OS
Event-loop & lock scripts (P