Orchestrator and cluster-runOrchestrateur et cluster-run
The queue for heavy jobs: why, how to use cluster-run and heavy_run, the limits that follow your hardware and the pressure rules.La file des travaux lourds : pourquoi, comment utiliser cluster-run et heavy_run, les limites qui suivent le matériel et les règles de pression.
With several sessions building and testing at once a computer saturates: load far above the cores, swap full, compilers crashing. The orchestrator is a small kernel scheduler for the heavy jobs (builds, tests, containers, media, GPU): they wait in a queue, a limited number run at once, and the limit follows the hardware, the live load and your settings. Light commands (ls, grep, git status) never go through it.
Quand plusieurs sessions compilent et testent en même temps, un ordinateur sature : charge très supérieure aux cœurs, swap plein, compilateurs qui plantent. L'orchestrateur est un petit ordonnanceur de noyau pour les travaux lourds (compilations, tests, conteneurs, média, GPU) : ils attendent dans une file, un nombre limité tourne en même temps, et la limite suit le matériel, la charge du moment et vos réglages. Les commandes légères (ls, grep, git status) n'y passent jamais.
1. Using itL'utiliser
| Where | How |
|---|---|
| a shell (a session's or yours) | cluster-run [--class build|tests|container|gpu|custom] [--prio N] [--name x] -- <command>: waits (cluster-run: queued: position 2, waiting for slot (2/2 running) on stderr), then runs in the low profile (nice, ionice, -j / --parallel / MAKEFLAGS / CARGO_BUILD_JOBS lowered to the share granted); output and exit code pass through |
| MCP, a command that waits | heavy_run: returns the result (finished with exit code, duration, tail; failed; killed by whom) or the waiting status |
| MCP, no waiting | jobs_add (woken with [job jN ...]), jobs_list, job_status, job_wait, job_kill, job_stop, job_resume, job_prio |
| the computer | hardware_scan, orchestrator_config |
| interface | the Tasks session (a Jobs section: queue, gauges, kill / stop / resume / priority), settings Orchestrator |
cluster-run is installed next to claude-cluster and is in the PATH of every session. Without a running core it runs the command directly with a warning.
| Où | Comment |
|---|---|
| un shell (celui d'une session ou le vôtre) | cluster-run [--class build|tests|container|gpu|custom] [--prio N] [--name x] -- <commande> : attend (cluster-run: queued: position 2, waiting for slot (2/2 running) sur stderr), puis s'exécute en profil bas (nice, ionice, -j / --parallel / MAKEFLAGS / CARGO_BUILD_JOBS abaissés à la part accordée) ; sortie et code de retour sont transmis |
| MCP, une commande qui attend | heavy_run : rend le résultat (fini avec code, durée, fin de sortie ; échoué ; tué par qui) ou l'état d'attente |
| MCP, sans attendre | jobs_add (réveillé par [job jN ...]), jobs_list, job_status, job_wait, job_kill, job_stop, job_resume, job_prio |
| l'ordinateur | hardware_scan, orchestrator_config |
| interface | la session Tasks (une section Jobs : file, jauges, tuer / arrêter / reprendre / priorité), réglages Orchestrator |
cluster-run est installé à côté de claude-cluster et se trouve dans le PATH de chaque session. Sans cœur en marche, il lance la commande directement avec un avertissement.
2. Who sees whatQui voit quoi
The global session sees and manages every job. A sub-session adds, follows, waits for and kills its own jobs ([orchestrator] sub_add, sub_kill_own, sub_see_others). A closed or archived session loses its jobs.
La session globale voit et gère tous les travaux. Une sous-session ajoute, suit, attend et tue ses propres travaux ([orchestrator] sub_add, sub_kill_own, sub_see_others). Une session fermée ou archivée perd ses travaux.
3. Job statesÉtats d'un travail
queued -> running -> done | failed | killed
\-> stopped (by you, or by pressure) -> runningA job starts only when the orchestrator is enabled, there is no pressure hold, active jobs are below the slots, its session and its class are below their limits and its RAM estimate fits. When nothing runs one job starts anyway so nothing starves. The order is 10 * prio plus session priority, a boost for the session you look at, and aging (a waiting job gains a point every aging_seconds), then FIFO.
queued -> running -> done | failed | killed
\-> stopped (par vous, ou par la pression) -> runningUn travail ne démarre que si l'orchestrateur est actif, qu'il n'y a pas de blocage de pression, que les travaux actifs sont sous les slots, que sa session et sa classe sont sous leurs limites et que son estimation de RAM tient. Quand rien ne tourne un travail démarre quand même pour que rien ne reste affamé. L'ordre est 10 * prio plus la priorité de session, un bonus pour la session que vous regardez, et le vieillissement (un travail en attente gagne un point toutes les aging_seconds), puis FIFO.
4. LimitsLimites
- Automatic: slots = min(usable cores x factor, (RAM - reserved) / RAM of a job), with factor 0.5 / 1 / 1.5 for the profile
low/normal/max; RAM per class (build 2000 MB, tests 1200, container 1500, gpu 2000, custom 1000). - Manual:
max_jobs,max_per_session, per class (gpu1,container2 by default),reserved_cpu,reserved_ram_mb,threads. - Pressure (load,
MemAvailable, swap,/proc/pressure): at hold nothing new starts; at reduce running jobs are reniced and the lowest-priority newest one is stopped (SIGSTOP) until the load falls, then resumed with hysteresis. Never killed unlesskill_on_oom = true. - Auto-detect: a process group outside the queue that burned
detect_cpu_secondsof CPU is listed and its session is told once to usecluster-run.
- Automatiques : slots = min(cœurs utilisables x facteur, (RAM - réservée) / RAM d'un travail), avec le facteur 0,5 / 1 / 1,5 pour le profil
low/normal/max; RAM par classe (build 2000 Mo, tests 1200, container 1500, gpu 2000, custom 1000). - Manuelles :
max_jobs,max_per_session, par classe (gpu1,container2 par défaut),reserved_cpu,reserved_ram_mb,threads. - Pression (charge,
MemAvailable, swap,/proc/pressure) : au niveau hold rien de nouveau ne démarre ; au niveau reduce les travaux en cours sont ralentis (renice) et le plus récent de plus basse priorité est arrêté (SIGSTOP) jusqu'à la baisse de charge, puis repris avec hystérésis. Jamais tués saufkill_on_oom = true. - Détection automatique : un groupe de processus hors file qui a consommé
detect_cpu_secondsde CPU est listé et sa session est prévenue une fois d'utilisercluster-run.
5. Memory guardGarde mémoire
[orchestrator] memory_guard (on) watches, every 5 s and without any model, everything the sessions run - agents, their shells and background commands, sub-agents, heavy jobs, the global session too, never the core. Under guard_free_mb of memory available (0: 5 % of the RAM, at least 500 MB) it kills the biggest of them, its whole process tree, before the system's out-of-memory killer does: a command or job first (never one under guard_min_mb), an agent only when nothing else is big enough, the global session last. The session is told what was killed, how much it used and that it may run it again with less memory; a notice and a notification say it too. Settings > About / Processes shows the memory of each session, the free / total memory, the guard and its last kills.
[orchestrator] memory_guard (activé) surveille toutes les 5 s, sans aucun modèle, tout ce que les sessions font tourner - agents, leurs shells et commandes en arrière-plan, sous-agents, travaux lourds, la session globale aussi, jamais le cœur. Sous guard_free_mb de mémoire disponible (0 : 5 % de la RAM, au moins 500 Mo) il tue le plus gros d'entre eux, tout son arbre de processus, avant que le tueur de mémoire du système ne le fasse : d'abord une commande ou un travail (jamais sous guard_min_mb), un agent seulement quand rien d'autre n'est assez gros, la session globale en dernier. La session apprend ce qui a été tué, combien il utilisait et qu'elle peut le relancer avec moins de mémoire ; une notice et une notification le disent aussi. Réglages > About / Processes montre la mémoire de chaque session, la mémoire libre / totale, la garde et ses derniers arrêts.
6. HardwareMatériel
hardware_scan records the CPU, cores, RAM, swap, disk, GPUs and power in hardware.json, at start and on demand. The sample for pressure is read every second from /proc.
The full design (state machine, wrapper protocol, persistence) is in docs/orchestrator.md of the sources; the protocol page summarises the wrapper messages.
hardware_scan enregistre CPU, cœurs, RAM, swap, disque, GPU et alimentation dans hardware.json, au démarrage et à la demande. L'échantillon de pression est lu chaque seconde dans /proc.
La conception complète (machine à états, protocole du wrapper, persistance) est dans docs/orchestrator.md des sources ; la page protocole résume les messages du wrapper.