@miroshnik/elves 2026.1028.0 → 2026.1029.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +3 -2
- package/bin/elves.ts +19 -4
- package/dist/github/scripts/github.js +17 -2
- package/dist/spec/scripts/architecture.js +2 -2
- package/dist/spec/scripts/{harness-yh09fn5z.js → harness-1rfkbdbn.js} +8 -8
- package/dist/spec/scripts/{harness-wcyv20e3.js → harness-dms3b7ke.js} +1 -1
- package/dist/spec/scripts/harness.js +1 -1
- package/docs/cloud-sessions.md +3 -2
- package/docs/testing.md +1 -1
- package/package.json +2 -2
- package/skills/github/SKILL.md +2 -2
- package/skills/github/locales/en.json +4 -4
- package/skills/github/locales/ru.json +4 -4
- package/skills/github/reference.md +12 -5
- package/skills/github/scripts/github.ts +26 -2
- package/skills/slot/SKILL.md +55 -4
- package/skills/slot/scripts/slot.ts +366 -20
package/AGENTS.md
CHANGED
|
@@ -123,8 +123,9 @@ done. The session can be closed.` · `All done, but there are questions: …` ·
|
|
|
123
123
|
(scope, not merges outside auto) — any session, its task stays; one started
|
|
124
124
|
for it — in the project folder, not a worktree: executors start from `main`.
|
|
125
125
|
`github task queue` prints executors' prompts; an executor — a background
|
|
126
|
-
subagent (own worktree) or a cloud session: at most
|
|
127
|
-
sessions at once, the owner's number replaces
|
|
126
|
+
subagent (own worktree) or a cloud session: at most the machine's executors
|
|
127
|
+
in subagents and 5 cloud sessions at once, the owner's number replaces
|
|
128
|
+
either (`task queue` names the executors, `slot`'s `machine.json` sets them); failed — a task
|
|
128
129
|
comment, no restart; an executor session whose task closed — the dispatcher
|
|
129
130
|
archives it in an auto project, not one still working in the background or
|
|
130
131
|
awaiting the owner's answer; outside auto the owner closes it. A batch
|
package/bin/elves.ts
CHANGED
|
@@ -84,6 +84,7 @@ import { fileURLToPath } from "node:url";
|
|
|
84
84
|
import { packageManager, specRoots } from "../skills/github/scripts/github.ts";
|
|
85
85
|
import locale from "../skills/github/scripts/locale.ts";
|
|
86
86
|
import { PACKAGE_BUNX, PACKAGE_RUN, packageRun } from "../skills/spec/scripts/package-run.ts";
|
|
87
|
+
import { machineCapacity } from "../skills/slot/scripts/slot.ts";
|
|
87
88
|
import { COMPOSE_FILES, proxyName } from "../skills/task-env/scripts/task-env.ts";
|
|
88
89
|
|
|
89
90
|
const SRC = fileURLToPath(new URL("..", import.meta.url)).replace(/\/$/, "");
|
|
@@ -2207,14 +2208,28 @@ function agentShellLines(): string[] {
|
|
|
2207
2208
|
}
|
|
2208
2209
|
|
|
2209
2210
|
/**
|
|
2210
|
-
* The
|
|
2211
|
-
*
|
|
2212
|
-
*
|
|
2211
|
+
* The machine's capacity (the slot skill, #779): heavy runs at once and the dispatcher's executors, and where they come
|
|
2212
|
+
* from — machine.json of the personal configuration or the cores and memory; a value machine.json gets wrong — its line.
|
|
2213
|
+
* Information, not the flow falling behind: it doesn't change the check's code.
|
|
2214
|
+
*/
|
|
2215
|
+
function capacityLines(): string[] {
|
|
2216
|
+
const c = machineCapacity();
|
|
2217
|
+
const set = c.from.slots === "machine.json" || c.from.executors === "machine.json";
|
|
2218
|
+
return [
|
|
2219
|
+
` machine: slots ${c.slots} (${c.from.slots}), executors ${c.executors} (${c.from.executors})${set ? "" : " — ~/.config/elves/machine.json replaces them"}`,
|
|
2220
|
+
...c.warnings.map((w) => ` ${w}`),
|
|
2221
|
+
];
|
|
2222
|
+
}
|
|
2223
|
+
|
|
2224
|
+
/**
|
|
2225
|
+
* The check's result plus the machine's lines, installed or not, behind or not: the capacity (`capacityLines`), the
|
|
2226
|
+
* proxy (`proxyLines`), the agent's Bash environment — the hook passes what writing it gave, `check -g` asks
|
|
2227
|
+
* `agentShellLines` — and Claude Code's prompt cache TTL (`cacheTtlLines`).
|
|
2213
2228
|
*/
|
|
2214
2229
|
function withMachine(global: boolean, r: Result, shell = agentShellLines()): Result {
|
|
2215
2230
|
if (!global || r.absent) return r;
|
|
2216
2231
|
const ttl = cacheTtlLines(os.homedir());
|
|
2217
|
-
const lines = [...proxyLines(os.homedir()), ...shell, ...ttl];
|
|
2232
|
+
const lines = [...capacityLines(), ...proxyLines(os.homedir()), ...shell, ...ttl];
|
|
2218
2233
|
return lines.length ? { ...r, text: [r.text, ...lines].join("\n"), ...(ttl.length ? { ttl: true } : {}) } : r;
|
|
2219
2234
|
}
|
|
2220
2235
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env bun
|
|
2
2
|
import {
|
|
3
3
|
locale_default
|
|
4
|
-
} from "../../spec/scripts/harness-
|
|
4
|
+
} from "../../spec/scripts/harness-1rfkbdbn.js";
|
|
5
5
|
|
|
6
6
|
// skills/github/scripts/github.ts
|
|
7
7
|
import { spawnSync } from "node:child_process";
|
|
@@ -2149,6 +2149,20 @@ function cmdTaskEdit(io, slug, number, edits) {
|
|
|
2149
2149
|
return 0;
|
|
2150
2150
|
}
|
|
2151
2151
|
var QUEUE_EXECUTORS = 3;
|
|
2152
|
+
var slotScript = (io) => io.env["ELVES_SLOT_SCRIPT"] ?? path.resolve(import.meta.dir, "../../slot/scripts/slot.ts");
|
|
2153
|
+
function queueExecutors(io) {
|
|
2154
|
+
const script = slotScript(io);
|
|
2155
|
+
if (!existsSync(script))
|
|
2156
|
+
return { n: QUEUE_EXECUTORS, from: "no slot skill" };
|
|
2157
|
+
const env = Object.fromEntries(Object.entries(io.env).filter((e) => e[1] !== undefined));
|
|
2158
|
+
const r = (io.run ?? realRun)("bun", ["--no-env-file", script, "--capacity"], io.cwd, env);
|
|
2159
|
+
try {
|
|
2160
|
+
const c = JSON.parse(r.stdout);
|
|
2161
|
+
if (Number.isInteger(c.executors) && c.executors > 0)
|
|
2162
|
+
return { n: c.executors, from: c.from.executors };
|
|
2163
|
+
} catch {}
|
|
2164
|
+
return { n: QUEUE_EXECUTORS, from: `slot --capacity: ${why(r)}` };
|
|
2165
|
+
}
|
|
2152
2166
|
var priorityRank = (p) => PRIORITIES.indexOf(p ?? DEFAULT_PRIORITY);
|
|
2153
2167
|
function externalBlocker(io, slug, number, label) {
|
|
2154
2168
|
const marks = locale_default.every((n) => n.comments.externalBlocker);
|
|
@@ -2368,7 +2382,8 @@ ${batches.map((b) => `batch ${b.repo} ${b.branch}
|
|
|
2368
2382
|
} else if (releasing !== null) {
|
|
2369
2383
|
io.out(`Next: the release of ${batch} is open — PR #${releasing} https://github.com/${slug}/pull/${releasing}: no new executors till its merge, ` + `the live executors' PRs into ${batch} wait for it (pr premerge refuses the merge); its steps — ${releaseCommand} prints them; ` + `after each executor's answer — task queue again; ${SESSION_ARCHIVE}.`);
|
|
2370
2384
|
} else if (ready.length) {
|
|
2371
|
-
|
|
2385
|
+
const executors = queueExecutors(io);
|
|
2386
|
+
io.out(`Next: each ready task above — a background subagent in its own worktree while fewer than ${executors.n} run (the machine's capacity: ${executors.from}; a number from the request replaces it); ` + `the indented line is its whole prompt. After each executor's answer — task queue again: new tasks get in${ask}; ${SESSION_ARCHIVE}${now}.`);
|
|
2372
2387
|
} else if (holding || !settled.length && running.length)
|
|
2373
2388
|
io.out(`Next: no ready tasks — wait for the executors' answers; after each — task queue again${ask}; ${SESSION_ARCHIVE}${now}.`);
|
|
2374
2389
|
else if (settled.length) {
|
|
@@ -2,10 +2,10 @@ import {
|
|
|
2
2
|
invariant2,
|
|
3
3
|
codeOnly2,
|
|
4
4
|
envNamesInCode2
|
|
5
|
-
} from "./harness-
|
|
5
|
+
} from "./harness-dms3b7ke.js";
|
|
6
6
|
import {
|
|
7
7
|
locale_default
|
|
8
|
-
} from "./harness-
|
|
8
|
+
} from "./harness-1rfkbdbn.js";
|
|
9
9
|
|
|
10
10
|
// skills/spec/scripts/architecture.ts
|
|
11
11
|
import { readdirSync, readFileSync } from "node:fs";
|
|
@@ -107,13 +107,13 @@ var en_default = {
|
|
|
107
107
|
subagents: "- writing subagents — launch as needed, no limit: each gets its own worktree and «{task} #{number}» at the start of its prompt (`est` links its work by it); bring their commits into your branch, remove their worktrees and branches yourself after the merge — what didn't go, name in the answer;",
|
|
108
108
|
live: "- while any of your subagents works, don't answer: wait for their answers — a background subagent wakes you with its answer; an answer with live subagents looks like a failure, and the dispatcher would give the task to a second executor next to you. Can't wait — answer `waits for subagents: <which and what they do>`: it isn't `failed`, there will be no second executor;",
|
|
109
109
|
refresh: '- the epic refresh — the subagent `task actualize` prints, without a worktree of its own (in yours) and not in the background (`run_in_background: false`): its answer — in the same turn, then `{script} task close {number}`, and only then the answer to the dispatcher: once you answer, a worktree without changes is removed, and a background subagent is left without a directory; a task without a PR (a data edit, a reconciliation, research) — first close the issue as completed with a result comment: `gh issue close {number} --repo {repo} --reason completed --comment "<result>"`;',
|
|
110
|
-
batchLead: "{task} #{number} «{title}» in {repo}{epic}: you are an executor of the dispatcher session, the task goes into the batch `{batch}` — do the task whole by the canon, {mode}: `{script} task start {number} --branch
|
|
110
|
+
batchLead: "{task} #{number} «{title}» in {repo}{epic}: you are an executor of the dispatcher session, the task goes into the batch `{batch}` — do the task whole by the canon, {mode}: `{script} task start {number} --branch exec/<type>/{number}-<slug>` (the task's questions and its parallel work — inside it), the branch from a fresh origin/{batch}, not from main (`git fetch origin {batch}`, then the task branch on `origin/{batch}`), code and tests, the checks before a commit, PR into the batch (`gh pr create --base {batch}`), `pr premerge`, merge. No CI wait, no deploy, no epic refresh and no `task close`: the task stays «{inProgress}» till the batch's release — the dispatcher's, with one full CI run and one refresh per epic.",
|
|
111
111
|
batchWait: "- don't wait for CI: a PR into the batch runs none — its gate is the checks before a commit by the canon (`elves precommit --base origin/<batch branch>`: `lint`, `typecheck`, `test:spec`, the affected tests — `docs/testing.md`) and `pr premerge` (the fast checks on the merge, if the batch moved on); after its code 0 — `gh pr merge <PR> --rebase` without a CI wait; the full run and the deploy are the release's, nothing to wait for after the merge, but before the answer take the task's stacks down (`{taskEnv} down {number}`, unsandboxed: Docker): the task waits for the release, its stack would load the machine till then;",
|
|
112
112
|
batchRefresh: "- the epic refresh and `task close` aren't yours: both are the batch's release — one refresh per epic of its tasks, then `task close` of each, the dispatcher's; a task without a PR (a data edit, a reconciliation, research) isn't in the batch — close the issue as completed with a result comment: `gh issue close {number} --repo {repo} --reason completed --comment \"<result>\"`, then the epic refresh — the subagent `task actualize {number}` prints, without a worktree of its own (in yours) and not in the background (`run_in_background: false`): its answer — in the same turn, then `{script} task close {number}`, and only then the answer to the dispatcher: once you answer, a worktree without changes is removed, and a background subagent is left without a directory;",
|
|
113
113
|
bypass: "- the task goes past the dispatcher's batch `{batch}` — the owner's word: the task branch from a fresh origin/main, not from the batch, the PR into the default branch (not `--base {batch}`) with the full CI, the deploy, the epic refresh and `task close` — yours, as in a project without batches; the batch's release doesn't wait for you;",
|
|
114
|
-
fixLead: '{task} #{number} «{title}» in {repo}{epic}: you are an executor of the dispatcher session — a fix in the batch `{batch}`: its release PR #{release} is red ({checks}), and the task, merged into the batch already, is named guilty — fix it in the batch by the canon, {mode}: `{script} task status {number} "{inProgress}" --branch fix/{number}-<slug>`, a new branch from a fresh origin/{batch} (`git fetch origin {batch}`, then the branch on `origin/{batch}`){previous}, the cause by the failed checks (`gh pr checks {release}`, their logs), the fix and its test, commits with `Refs #{number}`, the checks before a commit, PR into the batch (`gh pr create --base {batch}`, `Refs #{number}` in the body), `pr premerge` (it lets the guilty task\'s PR through the open release), merge. No CI wait, no deploy, no epic refresh and no `task close`: after the merge the dispatcher runs the release again — the full run on the same PR #{release}.',
|
|
114
|
+
fixLead: '{task} #{number} «{title}» in {repo}{epic}: you are an executor of the dispatcher session — a fix in the batch `{batch}`: its release PR #{release} is red ({checks}), and the task, merged into the batch already, is named guilty — fix it in the batch by the canon, {mode}: `{script} task status {number} "{inProgress}" --branch exec/fix/{number}-<slug>`, a new branch from a fresh origin/{batch} (`git fetch origin {batch}`, then the branch on `origin/{batch}`){previous}, the cause by the failed checks (`gh pr checks {release}`, their logs), the fix and its test, commits with `Refs #{number}`, the checks before a commit, PR into the batch (`gh pr create --base {batch}`, `Refs #{number}` in the body), `pr premerge` (it lets the guilty task\'s PR through the open release), merge. No CI wait, no deploy, no epic refresh and no `task close`: after the merge the dispatcher runs the release again — the full run on the same PR #{release}.',
|
|
115
115
|
fixPrevious: ", not the task's earlier branch {branches} — it is in the batch already, merged by a rebase",
|
|
116
|
-
sessionFixLead: '{task} #{number} «{title}» in {repo}{epic}: you are an executor session of the dispatcher session — a fix in the batch `{batch}`: its release PR #{release} is red ({checks}), and the task, merged into the batch already, is named guilty — fix it in the batch by the canon of this project, in its mode (`check` prints it; outside auto — commit, push and merge on the owner\'s «yes»): `{script} task status {number} "{inProgress}" --branch fix/{number}-<slug>`, a new branch from a fresh origin/{batch}{previous}, the cause by the failed checks (`gh pr checks {release}`, their logs), the fix and its test, commits with `Refs #{number}`, the checks before a commit, PR into the batch (`gh pr create --base {batch}`, `Refs #{number}` in the body), `pr premerge`, merge. No CI wait, no deploy, no epic refresh and no `task close`: after the merge the dispatcher runs the release again — the full run on the same PR #{release}.',
|
|
116
|
+
sessionFixLead: '{task} #{number} «{title}» in {repo}{epic}: you are an executor session of the dispatcher session — a fix in the batch `{batch}`: its release PR #{release} is red ({checks}), and the task, merged into the batch already, is named guilty — fix it in the batch by the canon of this project, in its mode (`check` prints it; outside auto — commit, push and merge on the owner\'s «yes»): `{script} task status {number} "{inProgress}" --branch exec/fix/{number}-<slug>`, a new branch from a fresh origin/{batch}{previous}, the cause by the failed checks (`gh pr checks {release}`, their logs), the fix and its test, commits with `Refs #{number}`, the checks before a commit, PR into the batch (`gh pr create --base {batch}`, `Refs #{number}` in the body), `pr premerge`, merge. No CI wait, no deploy, no epic refresh and no `task close`: after the merge the dispatcher runs the release again — the full run on the same PR #{release}.',
|
|
117
117
|
repeats: "- before the PR — repeats in the files the task changes anyway: fix them in the same PR, don't file a task for them; a repeat outside the task's files is the epic refresh's;",
|
|
118
118
|
found: "- work found outside the task — `{script} task new …` (work of the task's epic — with `--epic`: the dispatcher picks it up) — name it in the answer: whether to queue it is the owner's call;",
|
|
119
119
|
question: "- a question without a clear recommendation — into «{questions}» of the task; don't start the code that depends on it and answer the dispatcher: the owner's answer comes back here.",
|
|
@@ -127,7 +127,7 @@ var en_default = {
|
|
|
127
127
|
cloudDispatcher: "- the dispatcher waits for the task to close and closes it locally — the actual, the status, the merged branch, archiving this session: don't message it, don't archive the session;",
|
|
128
128
|
cloudQuestion: "- a question without a clear recommendation — into «{questions}» of the task and to the owner in this session, don't start the code that depends on it; stopped (a question, a failure, a limit) — a «{state}» comment into the task.",
|
|
129
129
|
sessionLead: "{task} #{number} «{title}» in {repo}{epic}: you are an executor session of the dispatcher session — do the task whole by the canon of this project, in its mode (`check` prints it; outside auto — commit, push and merge on the owner's «yes»): `{script} task start {number} --branch <type>/{number}-<slug>` (the task's questions and its parallel work — inside it), the branch from a fresh origin/main, code and tests, PR, green CI, `pr premerge`, merge, deploy, the epic refresh, `{script} task close {number}`.",
|
|
130
|
-
sessionBatchLead: "{task} #{number} «{title}» in {repo}{epic}: you are an executor session of the dispatcher session, the task goes into the batch `{batch}` — do the task whole by the canon of this project, in its mode (`check` prints it; outside auto — commit, push and merge on the owner's «yes»): `{script} task start {number} --branch
|
|
130
|
+
sessionBatchLead: "{task} #{number} «{title}» in {repo}{epic}: you are an executor session of the dispatcher session, the task goes into the batch `{batch}` — do the task whole by the canon of this project, in its mode (`check` prints it; outside auto — commit, push and merge on the owner's «yes»): `{script} task start {number} --branch exec/<type>/{number}-<slug>` (the task's questions and its parallel work — inside it), the branch from a fresh origin/{batch}, not from main, code and tests, the checks before a commit, PR into the batch (`gh pr create --base {batch}`), `pr premerge`, merge. No CI wait, no deploy, no epic refresh and no `task close`: the task stays «{inProgress}» till the batch's release — the dispatcher's, with one full CI run and one refresh per epic.",
|
|
131
131
|
sessionIs: "You are a session, not a subagent:",
|
|
132
132
|
sessionName: "- name the session `#{number} {title}` (`set_session_title`) once the task is taken — `est` links the session to the task by it;",
|
|
133
133
|
sessionWait: "- wait for CI and the deploy with a background command — `{waitCi} pr <PR>` (after the merge — `merged <PR>`): its completion wakes the session; no `Monitor`, watcher loop or `ScheduleWakeup` on top;",
|
|
@@ -587,13 +587,13 @@ var ru_default = {
|
|
|
587
587
|
subagents: "- пишущих субагентов запускай по необходимости, без лимита: каждому — свой worktree и «{task} #{number}» в начале промпта (по нему `est` привяжет его работу); их коммиты перенеси в свою ветку, их worktree и ветки после мержа убери сам — что не убралось, назови в ответе;",
|
|
588
588
|
live: "- пока работает хоть один твой субагент, ответ не отдавай: жди их ответов — фоновый субагент будит тебя своим ответом; ответ при живых субагентах выглядит провалом, и диспетчер отдал бы задачу второму исполнителю рядом с тобой. Ждать нельзя — ответь `ждёт субагентов: <какие и что делают>`: это не «сломалось», второго исполнителя не будет;",
|
|
589
589
|
refresh: '- актуализация эпика — субагент, которого печатает `task actualize`, без своего worktree (в твоём) и не в фоне (`run_in_background: false`): его ответ — в том же ходе, затем `{script} task close {number}`, и только потом ответ диспетчеру: стоит тебе ответить, worktree без изменений убирают, и фоновый субагент остаётся без каталога; у задачи без PR (правка данных, сверка, исследование) — сначала закрой issue как выполненную с итоговым комментарием: `gh issue close {number} --repo {repo} --reason completed --comment "<итог>"`;',
|
|
590
|
-
batchLead: "{task} #{number} «{title}» в {repo}{epic}: ты исполнитель сессии-диспетчера, задача идёт в пачку `{batch}` — сделай задачу целиком по канону, {mode}: `{script} task start {number} --branch
|
|
590
|
+
batchLead: "{task} #{number} «{title}» в {repo}{epic}: ты исполнитель сессии-диспетчера, задача идёт в пачку `{batch}` — сделай задачу целиком по канону, {mode}: `{script} task start {number} --branch exec/<тип>/{number}-<slug>` (вопросы задачи и её параллельная работа — в нём), ветка от свежего origin/{batch}, а не от main (`git fetch origin {batch}`, затем ветка задачи на `origin/{batch}`), код и тесты, проверки перед коммитом, PR в пачку (`gh pr create --base {batch}`), `pr premerge`, мерж. Ожидания CI, деплоя, актуализации эпика и `task close` нет: задача — «{inProgress}» до выпуска пачки, его делает диспетчер — с одним полным прогоном CI и одной актуализацией на эпик.",
|
|
591
591
|
batchWait: "- CI не жди: PR в пачку его не запускает — его ворота — проверки перед коммитом по канону (`elves precommit --base origin/<ветка пачки>`: `lint`, `typecheck`, `test:spec`, затронутые тесты — `docs/testing.md`) и `pr premerge` (быстрые проверки на слиянии, если пачка ушла вперёд); после его кода 0 — `gh pr merge <PR> --rebase` без ожидания CI; полный прогон и деплой — у выпуска, после мержа ждать нечего, но до ответа сними стеки задачи (`{taskEnv} down {number}`, вне песочницы: Docker): задача ждёт выпуска, а её стек до него грузил бы машину;",
|
|
592
592
|
batchRefresh: '- актуализация эпика и `task close` — не твои: обе — у выпуска пачки, одна актуализация на каждый эпик её задач, затем `task close` каждой, их делает диспетчер; задача без PR (правка данных, сверка, исследование) в пачку не идёт — закрой issue как выполненную с итоговым комментарием: `gh issue close {number} --repo {repo} --reason completed --comment "<итог>"`, затем актуализация эпика — субагент, которого печатает `task actualize {number}`, без своего worktree (в твоём) и не в фоне (`run_in_background: false`): его ответ — в том же ходе, затем `{script} task close {number}`, и только потом ответ диспетчеру: стоит тебе ответить, worktree без изменений убирают, и фоновый субагент остаётся без каталога;',
|
|
593
593
|
bypass: "- задача идёт мимо пачки диспетчера `{batch}` — слово владельца: ветка задачи от свежего origin/main, а не от пачки, PR в ветку по умолчанию (не `--base {batch}`) с полным CI, деплой, актуализация эпика и `task close` — твои, как в проекте без пачек; выпуск пачки тебя не ждёт;",
|
|
594
|
-
fixLead: '{task} #{number} «{title}» в {repo}{epic}: ты исполнитель сессии-диспетчера — починка в пачке `{batch}`: её PR выпуска #{release} красный ({checks}), а задача, уже влитая в пачку, названа виновной — почини её в пачке по канону, {mode}: `{script} task status {number} "{inProgress}" --branch fix/{number}-<slug>`, новая ветка от свежего origin/{batch} (`git fetch origin {batch}`, затем ветка на `origin/{batch}`){previous}, причина — по упавшим проверкам (`gh pr checks {release}`, их логи), починка и её тест, коммиты с `Refs #{number}`, проверки перед коммитом, PR в пачку (`gh pr create --base {batch}`, в теле `Refs #{number}`), `pr premerge` (PR виновной задачи он пропускает при открытом выпуске), мерж. Ожидания CI, деплоя, актуализации эпика и `task close` нет: после мержа диспетчер гонит выпуск заново — полный прогон на том же PR #{release}.',
|
|
594
|
+
fixLead: '{task} #{number} «{title}» в {repo}{epic}: ты исполнитель сессии-диспетчера — починка в пачке `{batch}`: её PR выпуска #{release} красный ({checks}), а задача, уже влитая в пачку, названа виновной — почини её в пачке по канону, {mode}: `{script} task status {number} "{inProgress}" --branch exec/fix/{number}-<slug>`, новая ветка от свежего origin/{batch} (`git fetch origin {batch}`, затем ветка на `origin/{batch}`){previous}, причина — по упавшим проверкам (`gh pr checks {release}`, их логи), починка и её тест, коммиты с `Refs #{number}`, проверки перед коммитом, PR в пачку (`gh pr create --base {batch}`, в теле `Refs #{number}`), `pr premerge` (PR виновной задачи он пропускает при открытом выпуске), мерж. Ожидания CI, деплоя, актуализации эпика и `task close` нет: после мержа диспетчер гонит выпуск заново — полный прогон на том же PR #{release}.',
|
|
595
595
|
fixPrevious: ", а не от прежней ветки задачи {branches} — она уже в пачке, влита rebase-мержем",
|
|
596
|
-
sessionFixLead: '{task} #{number} «{title}» в {repo}{epic}: ты сессия-исполнитель сессии-диспетчера — починка в пачке `{batch}`: её PR выпуска #{release} красный ({checks}), а задача, уже влитая в пачку, названа виновной — почини её в пачке по канону этого проекта, в его режиме (его печатает `check`; не в auto — коммит, пуш и мерж по «да» владельца): `{script} task status {number} "{inProgress}" --branch fix/{number}-<slug>`, новая ветка от свежего origin/{batch}{previous}, причина — по упавшим проверкам (`gh pr checks {release}`, их логи), починка и её тест, коммиты с `Refs #{number}`, проверки перед коммитом, PR в пачку (`gh pr create --base {batch}`, в теле `Refs #{number}`), `pr premerge`, мерж. Ожидания CI, деплоя, актуализации эпика и `task close` нет: после мержа диспетчер гонит выпуск заново — полный прогон на том же PR #{release}.',
|
|
596
|
+
sessionFixLead: '{task} #{number} «{title}» в {repo}{epic}: ты сессия-исполнитель сессии-диспетчера — починка в пачке `{batch}`: её PR выпуска #{release} красный ({checks}), а задача, уже влитая в пачку, названа виновной — почини её в пачке по канону этого проекта, в его режиме (его печатает `check`; не в auto — коммит, пуш и мерж по «да» владельца): `{script} task status {number} "{inProgress}" --branch exec/fix/{number}-<slug>`, новая ветка от свежего origin/{batch}{previous}, причина — по упавшим проверкам (`gh pr checks {release}`, их логи), починка и её тест, коммиты с `Refs #{number}`, проверки перед коммитом, PR в пачку (`gh pr create --base {batch}`, в теле `Refs #{number}`), `pr premerge`, мерж. Ожидания CI, деплоя, актуализации эпика и `task close` нет: после мержа диспетчер гонит выпуск заново — полный прогон на том же PR #{release}.',
|
|
597
597
|
repeats: "- перед PR — повторы в файлах, которые задача и так правит: исправь в том же PR, новую задачу на них не заводи; повтор вне файлов задачи — дело актуализации эпика;",
|
|
598
598
|
found: "- найденная работа вне задачи — `{script} task new …` (работа эпика задачи — с `--epic`: диспетчер её подхватит) — назови её в ответе: ставить ли её в очередь, решает владелец;",
|
|
599
599
|
question: "- вопрос без ясной рекомендации — в «{questions}» задачи; код, который от него зависит, не начинай и ответь диспетчеру: ответ владельца придёт сюда же.",
|
|
@@ -607,7 +607,7 @@ var ru_default = {
|
|
|
607
607
|
cloudDispatcher: "- диспетчер ждёт закрытия задачи и закрывает её локально — факт, статус, влитая ветка, архив этой сессии: сообщать ему не нужно, сессию не архивируй;",
|
|
608
608
|
cloudQuestion: "- вопрос без ясной рекомендации — в «{questions}» задачи и владельцу в этой сессии, код, который от него зависит, не начинай; остановился (вопрос, сбой, лимит) — комментарий «{state}» в задачу.",
|
|
609
609
|
sessionLead: "{task} #{number} «{title}» в {repo}{epic}: ты сессия-исполнитель сессии-диспетчера — сделай задачу целиком по канону этого проекта, в его режиме (его печатает `check`; не в auto — коммит, пуш и мерж по «да» владельца): `{script} task start {number} --branch <тип>/{number}-<slug>` (вопросы задачи и её параллельная работа — в нём), ветка от свежего origin/main, код и тесты, PR, зелёный CI, `pr premerge`, мерж, деплой, актуализация эпика, `{script} task close {number}`.",
|
|
610
|
-
sessionBatchLead: "{task} #{number} «{title}» в {repo}{epic}: ты сессия-исполнитель сессии-диспетчера, задача идёт в пачку `{batch}` — сделай задачу целиком по канону этого проекта, в его режиме (его печатает `check`; не в auto — коммит, пуш и мерж по «да» владельца): `{script} task start {number} --branch
|
|
610
|
+
sessionBatchLead: "{task} #{number} «{title}» в {repo}{epic}: ты сессия-исполнитель сессии-диспетчера, задача идёт в пачку `{batch}` — сделай задачу целиком по канону этого проекта, в его режиме (его печатает `check`; не в auto — коммит, пуш и мерж по «да» владельца): `{script} task start {number} --branch exec/<тип>/{number}-<slug>` (вопросы задачи и её параллельная работа — в нём), ветка от свежего origin/{batch}, а не от main, код и тесты, проверки перед коммитом, PR в пачку (`gh pr create --base {batch}`), `pr premerge`, мерж. Ожидания CI, деплоя, актуализации эпика и `task close` нет: задача — «{inProgress}» до выпуска пачки, его делает диспетчер — с одним полным прогоном CI и одной актуализацией на эпик.",
|
|
611
611
|
sessionIs: "Ты сессия, а не субагент:",
|
|
612
612
|
sessionName: "- назови сессию `#{number} {title}` (`set_session_title`), как только взял задачу, — по имени `est` привяжет сессию к задаче;",
|
|
613
613
|
sessionWait: "- CI и деплой жди фоновой командой — `{waitCi} pr <PR>` (после мержа — `merged <PR>`): её завершение будит сессию; без `Monitor`, цикла-наблюдателя и `ScheduleWakeup` поверх;",
|
package/docs/cloud-sessions.md
CHANGED
|
@@ -4,8 +4,9 @@ Reference for the cloud-session line in `AGENTS.md`. A cloud session is
|
|
|
4
4
|
Claude Code on claude.ai/code, including one started from the phone app: a
|
|
5
5
|
temporary container into which only the project repository is cloned.
|
|
6
6
|
A dispatcher's executor can be one (`AGENTS.md`, "Session and branch — one
|
|
7
|
-
task"): at most
|
|
8
|
-
replaces either — a cloud session's container doesn't
|
|
7
|
+
task"): at most the machine's executors in subagents and 5 cloud sessions at
|
|
8
|
+
once, the owner's number replaces either — a cloud session's container doesn't
|
|
9
|
+
load the machine.
|
|
9
10
|
|
|
10
11
|
## What it sees
|
|
11
12
|
|
package/docs/testing.md
CHANGED
|
@@ -24,7 +24,7 @@ against the Playwright, Next.js, Vite, SvelteKit and Nuxt documentation.
|
|
|
24
24
|
and print whom they wait for (the `slot` skill). Without the queue,
|
|
25
25
|
neighboring sessions, the linter and another worktree's e2e share the cores —
|
|
26
26
|
timeouts and flakes that aren't about the code. Runner workers come from
|
|
27
|
-
`ELVES_SLOT_CPUS` (
|
|
27
|
+
`ELVES_SLOT_CPUS` (its slot's share of half of the cores); CI has its own:
|
|
28
28
|
|
|
29
29
|
```ts
|
|
30
30
|
maxWorkers: Number(process.env.ELVES_SLOT_CPUS) || undefined, // vitest.config.ts
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@miroshnik/elves",
|
|
3
|
-
"version": "2026.
|
|
3
|
+
"version": "2026.1029.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Elves — a development flow with AI agents: shared rules and skills for any agent; install — bunx @miroshnik/elves install -g; the installer and skill scripts — TypeScript under Bun, tests — bun test in tests/",
|
|
6
6
|
"repository": {
|
|
@@ -72,5 +72,5 @@
|
|
|
72
72
|
"eslint-plugin-boundaries": "^7.2.0",
|
|
73
73
|
"knip": "^6.41.0"
|
|
74
74
|
},
|
|
75
|
-
"gitHead": "
|
|
75
|
+
"gitHead": "293d7b8e52929a23c58bffe49de33c84f4b8cd12"
|
|
76
76
|
}
|
package/skills/github/SKILL.md
CHANGED
|
@@ -148,8 +148,8 @@ folder, not a worktree: executors (subagents, cloud sessions) start from
|
|
|
148
148
|
`main`. `task queue` prints ready
|
|
149
149
|
tasks, each with an indented line — its executor's prompt. In Claude Code: an executor — `Agent` with
|
|
150
150
|
`isolation: "worktree"` and `run_in_background: true`, the prompt — as
|
|
151
|
-
is; at most
|
|
152
|
-
owner's number replaces either; another project's task — an app session in
|
|
151
|
+
is; at most the machine's executors in subagents and 5 cloud sessions at
|
|
152
|
+
once, the owner's number replaces either; another project's task — an app session in
|
|
153
153
|
its folder (`start_session`, own worktree);
|
|
154
154
|
`=` — a task in work, its line says why, not launched again. A batch project
|
|
155
155
|
(`"batch": true` in `.agents/elves.json`) — executors merge into the batch
|
|
@@ -103,13 +103,13 @@
|
|
|
103
103
|
"subagents": "- writing subagents — launch as needed, no limit: each gets its own worktree and «{task} #{number}» at the start of its prompt (`est` links its work by it); bring their commits into your branch, remove their worktrees and branches yourself after the merge — what didn't go, name in the answer;",
|
|
104
104
|
"live": "- while any of your subagents works, don't answer: wait for their answers — a background subagent wakes you with its answer; an answer with live subagents looks like a failure, and the dispatcher would give the task to a second executor next to you. Can't wait — answer `waits for subagents: <which and what they do>`: it isn't `failed`, there will be no second executor;",
|
|
105
105
|
"refresh": "- the epic refresh — the subagent `task actualize` prints, without a worktree of its own (in yours) and not in the background (`run_in_background: false`): its answer — in the same turn, then `{script} task close {number}`, and only then the answer to the dispatcher: once you answer, a worktree without changes is removed, and a background subagent is left without a directory; a task without a PR (a data edit, a reconciliation, research) — first close the issue as completed with a result comment: `gh issue close {number} --repo {repo} --reason completed --comment \"<result>\"`;",
|
|
106
|
-
"batchLead": "{task} #{number} «{title}» in {repo}{epic}: you are an executor of the dispatcher session, the task goes into the batch `{batch}` — do the task whole by the canon, {mode}: `{script} task start {number} --branch
|
|
106
|
+
"batchLead": "{task} #{number} «{title}» in {repo}{epic}: you are an executor of the dispatcher session, the task goes into the batch `{batch}` — do the task whole by the canon, {mode}: `{script} task start {number} --branch exec/<type>/{number}-<slug>` (the task's questions and its parallel work — inside it), the branch from a fresh origin/{batch}, not from main (`git fetch origin {batch}`, then the task branch on `origin/{batch}`), code and tests, the checks before a commit, PR into the batch (`gh pr create --base {batch}`), `pr premerge`, merge. No CI wait, no deploy, no epic refresh and no `task close`: the task stays «{inProgress}» till the batch's release — the dispatcher's, with one full CI run and one refresh per epic.",
|
|
107
107
|
"batchWait": "- don't wait for CI: a PR into the batch runs none — its gate is the checks before a commit by the canon (`elves precommit --base origin/<batch branch>`: `lint`, `typecheck`, `test:spec`, the affected tests — `docs/testing.md`) and `pr premerge` (the fast checks on the merge, if the batch moved on); after its code 0 — `gh pr merge <PR> --rebase` without a CI wait; the full run and the deploy are the release's, nothing to wait for after the merge, but before the answer take the task's stacks down (`{taskEnv} down {number}`, unsandboxed: Docker): the task waits for the release, its stack would load the machine till then;",
|
|
108
108
|
"batchRefresh": "- the epic refresh and `task close` aren't yours: both are the batch's release — one refresh per epic of its tasks, then `task close` of each, the dispatcher's; a task without a PR (a data edit, a reconciliation, research) isn't in the batch — close the issue as completed with a result comment: `gh issue close {number} --repo {repo} --reason completed --comment \"<result>\"`, then the epic refresh — the subagent `task actualize {number}` prints, without a worktree of its own (in yours) and not in the background (`run_in_background: false`): its answer — in the same turn, then `{script} task close {number}`, and only then the answer to the dispatcher: once you answer, a worktree without changes is removed, and a background subagent is left without a directory;",
|
|
109
109
|
"bypass": "- the task goes past the dispatcher's batch `{batch}` — the owner's word: the task branch from a fresh origin/main, not from the batch, the PR into the default branch (not `--base {batch}`) with the full CI, the deploy, the epic refresh and `task close` — yours, as in a project without batches; the batch's release doesn't wait for you;",
|
|
110
|
-
"fixLead": "{task} #{number} «{title}» in {repo}{epic}: you are an executor of the dispatcher session — a fix in the batch `{batch}`: its release PR #{release} is red ({checks}), and the task, merged into the batch already, is named guilty — fix it in the batch by the canon, {mode}: `{script} task status {number} \"{inProgress}\" --branch fix/{number}-<slug>`, a new branch from a fresh origin/{batch} (`git fetch origin {batch}`, then the branch on `origin/{batch}`){previous}, the cause by the failed checks (`gh pr checks {release}`, their logs), the fix and its test, commits with `Refs #{number}`, the checks before a commit, PR into the batch (`gh pr create --base {batch}`, `Refs #{number}` in the body), `pr premerge` (it lets the guilty task's PR through the open release), merge. No CI wait, no deploy, no epic refresh and no `task close`: after the merge the dispatcher runs the release again — the full run on the same PR #{release}.",
|
|
110
|
+
"fixLead": "{task} #{number} «{title}» in {repo}{epic}: you are an executor of the dispatcher session — a fix in the batch `{batch}`: its release PR #{release} is red ({checks}), and the task, merged into the batch already, is named guilty — fix it in the batch by the canon, {mode}: `{script} task status {number} \"{inProgress}\" --branch exec/fix/{number}-<slug>`, a new branch from a fresh origin/{batch} (`git fetch origin {batch}`, then the branch on `origin/{batch}`){previous}, the cause by the failed checks (`gh pr checks {release}`, their logs), the fix and its test, commits with `Refs #{number}`, the checks before a commit, PR into the batch (`gh pr create --base {batch}`, `Refs #{number}` in the body), `pr premerge` (it lets the guilty task's PR through the open release), merge. No CI wait, no deploy, no epic refresh and no `task close`: after the merge the dispatcher runs the release again — the full run on the same PR #{release}.",
|
|
111
111
|
"fixPrevious": ", not the task's earlier branch {branches} — it is in the batch already, merged by a rebase",
|
|
112
|
-
"sessionFixLead": "{task} #{number} «{title}» in {repo}{epic}: you are an executor session of the dispatcher session — a fix in the batch `{batch}`: its release PR #{release} is red ({checks}), and the task, merged into the batch already, is named guilty — fix it in the batch by the canon of this project, in its mode (`check` prints it; outside auto — commit, push and merge on the owner's «yes»): `{script} task status {number} \"{inProgress}\" --branch fix/{number}-<slug>`, a new branch from a fresh origin/{batch}{previous}, the cause by the failed checks (`gh pr checks {release}`, their logs), the fix and its test, commits with `Refs #{number}`, the checks before a commit, PR into the batch (`gh pr create --base {batch}`, `Refs #{number}` in the body), `pr premerge`, merge. No CI wait, no deploy, no epic refresh and no `task close`: after the merge the dispatcher runs the release again — the full run on the same PR #{release}.",
|
|
112
|
+
"sessionFixLead": "{task} #{number} «{title}» in {repo}{epic}: you are an executor session of the dispatcher session — a fix in the batch `{batch}`: its release PR #{release} is red ({checks}), and the task, merged into the batch already, is named guilty — fix it in the batch by the canon of this project, in its mode (`check` prints it; outside auto — commit, push and merge on the owner's «yes»): `{script} task status {number} \"{inProgress}\" --branch exec/fix/{number}-<slug>`, a new branch from a fresh origin/{batch}{previous}, the cause by the failed checks (`gh pr checks {release}`, their logs), the fix and its test, commits with `Refs #{number}`, the checks before a commit, PR into the batch (`gh pr create --base {batch}`, `Refs #{number}` in the body), `pr premerge`, merge. No CI wait, no deploy, no epic refresh and no `task close`: after the merge the dispatcher runs the release again — the full run on the same PR #{release}.",
|
|
113
113
|
"repeats": "- before the PR — repeats in the files the task changes anyway: fix them in the same PR, don't file a task for them; a repeat outside the task's files is the epic refresh's;",
|
|
114
114
|
"found": "- work found outside the task — `{script} task new …` (work of the task's epic — with `--epic`: the dispatcher picks it up) — name it in the answer: whether to queue it is the owner's call;",
|
|
115
115
|
"question": "- a question without a clear recommendation — into «{questions}» of the task; don't start the code that depends on it and answer the dispatcher: the owner's answer comes back here.",
|
|
@@ -123,7 +123,7 @@
|
|
|
123
123
|
"cloudDispatcher": "- the dispatcher waits for the task to close and closes it locally — the actual, the status, the merged branch, archiving this session: don't message it, don't archive the session;",
|
|
124
124
|
"cloudQuestion": "- a question without a clear recommendation — into «{questions}» of the task and to the owner in this session, don't start the code that depends on it; stopped (a question, a failure, a limit) — a «{state}» comment into the task.",
|
|
125
125
|
"sessionLead": "{task} #{number} «{title}» in {repo}{epic}: you are an executor session of the dispatcher session — do the task whole by the canon of this project, in its mode (`check` prints it; outside auto — commit, push and merge on the owner's «yes»): `{script} task start {number} --branch <type>/{number}-<slug>` (the task's questions and its parallel work — inside it), the branch from a fresh origin/main, code and tests, PR, green CI, `pr premerge`, merge, deploy, the epic refresh, `{script} task close {number}`.",
|
|
126
|
-
"sessionBatchLead": "{task} #{number} «{title}» in {repo}{epic}: you are an executor session of the dispatcher session, the task goes into the batch `{batch}` — do the task whole by the canon of this project, in its mode (`check` prints it; outside auto — commit, push and merge on the owner's «yes»): `{script} task start {number} --branch
|
|
126
|
+
"sessionBatchLead": "{task} #{number} «{title}» in {repo}{epic}: you are an executor session of the dispatcher session, the task goes into the batch `{batch}` — do the task whole by the canon of this project, in its mode (`check` prints it; outside auto — commit, push and merge on the owner's «yes»): `{script} task start {number} --branch exec/<type>/{number}-<slug>` (the task's questions and its parallel work — inside it), the branch from a fresh origin/{batch}, not from main, code and tests, the checks before a commit, PR into the batch (`gh pr create --base {batch}`), `pr premerge`, merge. No CI wait, no deploy, no epic refresh and no `task close`: the task stays «{inProgress}» till the batch's release — the dispatcher's, with one full CI run and one refresh per epic.",
|
|
127
127
|
"sessionIs": "You are a session, not a subagent:",
|
|
128
128
|
"sessionName": "- name the session `#{number} {title}` (`set_session_title`) once the task is taken — `est` links the session to the task by it;",
|
|
129
129
|
"sessionWait": "- wait for CI and the deploy with a background command — `{waitCi} pr <PR>` (after the merge — `merged <PR>`): its completion wakes the session; no `Monitor`, watcher loop or `ScheduleWakeup` on top;",
|
|
@@ -103,13 +103,13 @@
|
|
|
103
103
|
"subagents": "- пишущих субагентов запускай по необходимости, без лимита: каждому — свой worktree и «{task} #{number}» в начале промпта (по нему `est` привяжет его работу); их коммиты перенеси в свою ветку, их worktree и ветки после мержа убери сам — что не убралось, назови в ответе;",
|
|
104
104
|
"live": "- пока работает хоть один твой субагент, ответ не отдавай: жди их ответов — фоновый субагент будит тебя своим ответом; ответ при живых субагентах выглядит провалом, и диспетчер отдал бы задачу второму исполнителю рядом с тобой. Ждать нельзя — ответь `ждёт субагентов: <какие и что делают>`: это не «сломалось», второго исполнителя не будет;",
|
|
105
105
|
"refresh": "- актуализация эпика — субагент, которого печатает `task actualize`, без своего worktree (в твоём) и не в фоне (`run_in_background: false`): его ответ — в том же ходе, затем `{script} task close {number}`, и только потом ответ диспетчеру: стоит тебе ответить, worktree без изменений убирают, и фоновый субагент остаётся без каталога; у задачи без PR (правка данных, сверка, исследование) — сначала закрой issue как выполненную с итоговым комментарием: `gh issue close {number} --repo {repo} --reason completed --comment \"<итог>\"`;",
|
|
106
|
-
"batchLead": "{task} #{number} «{title}» в {repo}{epic}: ты исполнитель сессии-диспетчера, задача идёт в пачку `{batch}` — сделай задачу целиком по канону, {mode}: `{script} task start {number} --branch
|
|
106
|
+
"batchLead": "{task} #{number} «{title}» в {repo}{epic}: ты исполнитель сессии-диспетчера, задача идёт в пачку `{batch}` — сделай задачу целиком по канону, {mode}: `{script} task start {number} --branch exec/<тип>/{number}-<slug>` (вопросы задачи и её параллельная работа — в нём), ветка от свежего origin/{batch}, а не от main (`git fetch origin {batch}`, затем ветка задачи на `origin/{batch}`), код и тесты, проверки перед коммитом, PR в пачку (`gh pr create --base {batch}`), `pr premerge`, мерж. Ожидания CI, деплоя, актуализации эпика и `task close` нет: задача — «{inProgress}» до выпуска пачки, его делает диспетчер — с одним полным прогоном CI и одной актуализацией на эпик.",
|
|
107
107
|
"batchWait": "- CI не жди: PR в пачку его не запускает — его ворота — проверки перед коммитом по канону (`elves precommit --base origin/<ветка пачки>`: `lint`, `typecheck`, `test:spec`, затронутые тесты — `docs/testing.md`) и `pr premerge` (быстрые проверки на слиянии, если пачка ушла вперёд); после его кода 0 — `gh pr merge <PR> --rebase` без ожидания CI; полный прогон и деплой — у выпуска, после мержа ждать нечего, но до ответа сними стеки задачи (`{taskEnv} down {number}`, вне песочницы: Docker): задача ждёт выпуска, а её стек до него грузил бы машину;",
|
|
108
108
|
"batchRefresh": "- актуализация эпика и `task close` — не твои: обе — у выпуска пачки, одна актуализация на каждый эпик её задач, затем `task close` каждой, их делает диспетчер; задача без PR (правка данных, сверка, исследование) в пачку не идёт — закрой issue как выполненную с итоговым комментарием: `gh issue close {number} --repo {repo} --reason completed --comment \"<итог>\"`, затем актуализация эпика — субагент, которого печатает `task actualize {number}`, без своего worktree (в твоём) и не в фоне (`run_in_background: false`): его ответ — в том же ходе, затем `{script} task close {number}`, и только потом ответ диспетчеру: стоит тебе ответить, worktree без изменений убирают, и фоновый субагент остаётся без каталога;",
|
|
109
109
|
"bypass": "- задача идёт мимо пачки диспетчера `{batch}` — слово владельца: ветка задачи от свежего origin/main, а не от пачки, PR в ветку по умолчанию (не `--base {batch}`) с полным CI, деплой, актуализация эпика и `task close` — твои, как в проекте без пачек; выпуск пачки тебя не ждёт;",
|
|
110
|
-
"fixLead": "{task} #{number} «{title}» в {repo}{epic}: ты исполнитель сессии-диспетчера — починка в пачке `{batch}`: её PR выпуска #{release} красный ({checks}), а задача, уже влитая в пачку, названа виновной — почини её в пачке по канону, {mode}: `{script} task status {number} \"{inProgress}\" --branch fix/{number}-<slug>`, новая ветка от свежего origin/{batch} (`git fetch origin {batch}`, затем ветка на `origin/{batch}`){previous}, причина — по упавшим проверкам (`gh pr checks {release}`, их логи), починка и её тест, коммиты с `Refs #{number}`, проверки перед коммитом, PR в пачку (`gh pr create --base {batch}`, в теле `Refs #{number}`), `pr premerge` (PR виновной задачи он пропускает при открытом выпуске), мерж. Ожидания CI, деплоя, актуализации эпика и `task close` нет: после мержа диспетчер гонит выпуск заново — полный прогон на том же PR #{release}.",
|
|
110
|
+
"fixLead": "{task} #{number} «{title}» в {repo}{epic}: ты исполнитель сессии-диспетчера — починка в пачке `{batch}`: её PR выпуска #{release} красный ({checks}), а задача, уже влитая в пачку, названа виновной — почини её в пачке по канону, {mode}: `{script} task status {number} \"{inProgress}\" --branch exec/fix/{number}-<slug>`, новая ветка от свежего origin/{batch} (`git fetch origin {batch}`, затем ветка на `origin/{batch}`){previous}, причина — по упавшим проверкам (`gh pr checks {release}`, их логи), починка и её тест, коммиты с `Refs #{number}`, проверки перед коммитом, PR в пачку (`gh pr create --base {batch}`, в теле `Refs #{number}`), `pr premerge` (PR виновной задачи он пропускает при открытом выпуске), мерж. Ожидания CI, деплоя, актуализации эпика и `task close` нет: после мержа диспетчер гонит выпуск заново — полный прогон на том же PR #{release}.",
|
|
111
111
|
"fixPrevious": ", а не от прежней ветки задачи {branches} — она уже в пачке, влита rebase-мержем",
|
|
112
|
-
"sessionFixLead": "{task} #{number} «{title}» в {repo}{epic}: ты сессия-исполнитель сессии-диспетчера — починка в пачке `{batch}`: её PR выпуска #{release} красный ({checks}), а задача, уже влитая в пачку, названа виновной — почини её в пачке по канону этого проекта, в его режиме (его печатает `check`; не в auto — коммит, пуш и мерж по «да» владельца): `{script} task status {number} \"{inProgress}\" --branch fix/{number}-<slug>`, новая ветка от свежего origin/{batch}{previous}, причина — по упавшим проверкам (`gh pr checks {release}`, их логи), починка и её тест, коммиты с `Refs #{number}`, проверки перед коммитом, PR в пачку (`gh pr create --base {batch}`, в теле `Refs #{number}`), `pr premerge`, мерж. Ожидания CI, деплоя, актуализации эпика и `task close` нет: после мержа диспетчер гонит выпуск заново — полный прогон на том же PR #{release}.",
|
|
112
|
+
"sessionFixLead": "{task} #{number} «{title}» в {repo}{epic}: ты сессия-исполнитель сессии-диспетчера — починка в пачке `{batch}`: её PR выпуска #{release} красный ({checks}), а задача, уже влитая в пачку, названа виновной — почини её в пачке по канону этого проекта, в его режиме (его печатает `check`; не в auto — коммит, пуш и мерж по «да» владельца): `{script} task status {number} \"{inProgress}\" --branch exec/fix/{number}-<slug>`, новая ветка от свежего origin/{batch}{previous}, причина — по упавшим проверкам (`gh pr checks {release}`, их логи), починка и её тест, коммиты с `Refs #{number}`, проверки перед коммитом, PR в пачку (`gh pr create --base {batch}`, в теле `Refs #{number}`), `pr premerge`, мерж. Ожидания CI, деплоя, актуализации эпика и `task close` нет: после мержа диспетчер гонит выпуск заново — полный прогон на том же PR #{release}.",
|
|
113
113
|
"repeats": "- перед PR — повторы в файлах, которые задача и так правит: исправь в том же PR, новую задачу на них не заводи; повтор вне файлов задачи — дело актуализации эпика;",
|
|
114
114
|
"found": "- найденная работа вне задачи — `{script} task new …` (работа эпика задачи — с `--epic`: диспетчер её подхватит) — назови её в ответе: ставить ли её в очередь, решает владелец;",
|
|
115
115
|
"question": "- вопрос без ясной рекомендации — в «{questions}» задачи; код, который от него зависит, не начинай и ответь диспетчеру: ответ владельца придёт сюда же.",
|
|
@@ -123,7 +123,7 @@
|
|
|
123
123
|
"cloudDispatcher": "- диспетчер ждёт закрытия задачи и закрывает её локально — факт, статус, влитая ветка, архив этой сессии: сообщать ему не нужно, сессию не архивируй;",
|
|
124
124
|
"cloudQuestion": "- вопрос без ясной рекомендации — в «{questions}» задачи и владельцу в этой сессии, код, который от него зависит, не начинай; остановился (вопрос, сбой, лимит) — комментарий «{state}» в задачу.",
|
|
125
125
|
"sessionLead": "{task} #{number} «{title}» в {repo}{epic}: ты сессия-исполнитель сессии-диспетчера — сделай задачу целиком по канону этого проекта, в его режиме (его печатает `check`; не в auto — коммит, пуш и мерж по «да» владельца): `{script} task start {number} --branch <тип>/{number}-<slug>` (вопросы задачи и её параллельная работа — в нём), ветка от свежего origin/main, код и тесты, PR, зелёный CI, `pr premerge`, мерж, деплой, актуализация эпика, `{script} task close {number}`.",
|
|
126
|
-
"sessionBatchLead": "{task} #{number} «{title}» в {repo}{epic}: ты сессия-исполнитель сессии-диспетчера, задача идёт в пачку `{batch}` — сделай задачу целиком по канону этого проекта, в его режиме (его печатает `check`; не в auto — коммит, пуш и мерж по «да» владельца): `{script} task start {number} --branch
|
|
126
|
+
"sessionBatchLead": "{task} #{number} «{title}» в {repo}{epic}: ты сессия-исполнитель сессии-диспетчера, задача идёт в пачку `{batch}` — сделай задачу целиком по канону этого проекта, в его режиме (его печатает `check`; не в auto — коммит, пуш и мерж по «да» владельца): `{script} task start {number} --branch exec/<тип>/{number}-<slug>` (вопросы задачи и её параллельная работа — в нём), ветка от свежего origin/{batch}, а не от main, код и тесты, проверки перед коммитом, PR в пачку (`gh pr create --base {batch}`), `pr premerge`, мерж. Ожидания CI, деплоя, актуализации эпика и `task close` нет: задача — «{inProgress}» до выпуска пачки, его делает диспетчер — с одним полным прогоном CI и одной актуализацией на эпик.",
|
|
127
127
|
"sessionIs": "Ты сессия, а не субагент:",
|
|
128
128
|
"sessionName": "- назови сессию `#{number} {title}` (`set_session_title`), как только взял задачу, — по имени `est` привяжет сессию к задаче;",
|
|
129
129
|
"sessionWait": "- CI и деплой жди фоновой командой — `{waitCi} pr <PR>` (после мержа — `merged <PR>`): её завершение будит сессию; без `Monitor`, цикла-наблюдателя и `ScheduleWakeup` поверх;",
|
|
@@ -1028,10 +1028,11 @@ after its answer, and the woken executor of #545 worked unlocked; the wait for C
|
|
|
1028
1028
|
is a Bash call of up to 9 minutes without commits.
|
|
1029
1029
|
|
|
1030
1030
|
In Claude Code: an executor — `Agent` with `isolation: "worktree"` and
|
|
1031
|
-
`run_in_background: true`, the prompt — the indented line as is; at most
|
|
1032
|
-
subagents and 5 cloud sessions at once, the owner's
|
|
1033
|
-
(subagents share the machine
|
|
1034
|
-
|
|
1031
|
+
`run_in_background: true`, the prompt — the indented line as is; at most the
|
|
1032
|
+
machine's executors in subagents and 5 cloud sessions at once, the owner's
|
|
1033
|
+
number replaces either (subagents share the machine: `Next:` names the
|
|
1034
|
+
executors of its capacity — `slot --capacity`, `machine.json` or the cores and
|
|
1035
|
+
memory, without the slot skill — 3; a cloud session has its own container); a task in work (`=`) isn't launched again.
|
|
1035
1036
|
Before each launch — `get_usage`: the 5-hour limit at 85% and more — no new
|
|
1036
1037
|
executors, the running ones finish, then `Remaining: N tasks, the limit`. An
|
|
1037
1038
|
answer arrives as the subagent's notification; after each — `task queue`
|
|
@@ -1109,7 +1110,13 @@ PR till the release — open and In progress (question 1 of the epic); a blocker
|
|
|
1109
1110
|
merged into it doesn't hold a task of the same batch, one outside it — merged
|
|
1110
1111
|
into another batch or not merged — holds. The assignment (`--assignment`,
|
|
1111
1112
|
`--session`) reads the batch from the marker — a subagent shares the session's
|
|
1112
|
-
id: the task branch from `origin/<batch
|
|
1113
|
+
id: the task branch from `origin/<batch>` in the area `exec` —
|
|
1114
|
+
`exec/<type>/<N>-<slug>`, a fix of a red release `exec/fix/<N>-<slug>`
|
|
1115
|
+
(#785): a preview host builds every pushed branch and comments on its PR, one
|
|
1116
|
+
notification per batch task, and decides by the branch's name, not the PR's
|
|
1117
|
+
base — Vercel: `"git": {"deploymentEnabled": {"exec/**": false}}` in
|
|
1118
|
+
`vercel.json` skips them, the release PR keeps its preview; past the batch
|
|
1119
|
+
(`--main`) and outside it — no area. Then the checks before a commit, the PR
|
|
1113
1120
|
`--base <batch>`, `pr premerge` (it checks against the PR's base: by git, #676),
|
|
1114
1121
|
the merge at once — no CI wait (the PR runs none: the slot is free at the
|
|
1115
1122
|
merge, #676), no deploy wait, no epic refresh (the release's, one per epic)
|
|
@@ -2944,9 +2944,32 @@ export interface QueueFilter {
|
|
|
2944
2944
|
priority?: string[] | undefined;
|
|
2945
2945
|
}
|
|
2946
2946
|
|
|
2947
|
-
/**
|
|
2947
|
+
/** Executors at once without the slot skill: `slot` lets two heavy runs through, a third executor writes code meanwhile. */
|
|
2948
2948
|
export const QUEUE_EXECUTORS = 3;
|
|
2949
2949
|
|
|
2950
|
+
/** The slot script next to the skill — laid out like est (`../slot/scripts/slot.ts`). */
|
|
2951
|
+
const slotScript = (io: Io) => io.env["ELVES_SLOT_SCRIPT"] ?? path.resolve(import.meta.dir, "../../slot/scripts/slot.ts");
|
|
2952
|
+
|
|
2953
|
+
/**
|
|
2954
|
+
* How many executors run at once and where the number comes from: the machine's capacity — `slot --capacity` by
|
|
2955
|
+
* machine.json of the personal configuration, otherwise by the cores and memory (#779); a process, not an import
|
|
2956
|
+
* (tests/standards/scripts/skill-imports). No slot skill or it failed — QUEUE_EXECUTORS with the reason.
|
|
2957
|
+
*/
|
|
2958
|
+
function queueExecutors(io: Io): { n: number; from: string } {
|
|
2959
|
+
const script = slotScript(io);
|
|
2960
|
+
if (!existsSync(script)) return { n: QUEUE_EXECUTORS, from: "no slot skill" };
|
|
2961
|
+
// the script's environment — its personal configuration directory is slot's too (tests/standards/scripts/config-dir)
|
|
2962
|
+
const env = Object.fromEntries(Object.entries(io.env).filter((e): e is [string, string] => e[1] !== undefined));
|
|
2963
|
+
const r = (io.run ?? realRun)("bun", ["--no-env-file", script, "--capacity"], io.cwd, env);
|
|
2964
|
+
try {
|
|
2965
|
+
const c = JSON.parse(r.stdout) as { executors: number; from: { executors: string } };
|
|
2966
|
+
if (Number.isInteger(c.executors) && c.executors > 0) return { n: c.executors, from: c.from.executors };
|
|
2967
|
+
} catch {
|
|
2968
|
+
/* the number below, with the reason */
|
|
2969
|
+
}
|
|
2970
|
+
return { n: QUEUE_EXECUTORS, from: `slot --capacity: ${why(r)}` };
|
|
2971
|
+
}
|
|
2972
|
+
|
|
2950
2973
|
const priorityRank = (p: string | null) => PRIORITIES.indexOf((p ?? DEFAULT_PRIORITY) as (typeof PRIORITIES)[number]);
|
|
2951
2974
|
|
|
2952
2975
|
/**
|
|
@@ -3249,8 +3272,9 @@ export function cmdTaskQueue(io: Io, slug: string, o: QueueFilter): number {
|
|
|
3249
3272
|
`after each executor's answer — task queue again; ${SESSION_ARCHIVE}.`,
|
|
3250
3273
|
);
|
|
3251
3274
|
} else if (ready.length) {
|
|
3275
|
+
const executors = queueExecutors(io);
|
|
3252
3276
|
io.out(
|
|
3253
|
-
`Next: each ready task above — a background subagent in its own worktree while fewer than ${
|
|
3277
|
+
`Next: each ready task above — a background subagent in its own worktree while fewer than ${executors.n} run (the machine's capacity: ${executors.from}; a number from the request replaces it); ` +
|
|
3254
3278
|
`the indented line is its whole prompt. After each executor's answer — task queue again: new tasks get in${ask}; ${SESSION_ARCHIVE}${now}.`,
|
|
3255
3279
|
);
|
|
3256
3280
|
} else if (holding || (!settled.length && running.length)) io.out(`Next: no ready tasks — wait for the executors' answers; after each — task queue again${ask}; ${SESSION_ARCHIVE}${now}.`);
|
package/skills/slot/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: slot
|
|
3
|
-
description: "A queue for heavy runs on the machine — project checks (`lint`, `typecheck`, `test`, `test:*`) and bringing a task stack up (`task-env`) go through `slot`, and installing the flow wraps the `package.json` scripts in it;
|
|
3
|
+
description: "A queue for heavy runs on the machine — project checks (`lint`, `typecheck`, `test`, `test:*`) and bringing a task stack up (`task-env`) go through `slot`, and installing the flow wraps the `package.json` scripts in it; as many runs at a time as the machine has slots (`machine.json`, otherwise by the cores), together half of the cores, the rest wait in arrival order and print whom they wait for; the command gets `ELVES_SLOT_CPUS` (its slot's share) for the runner's workers; the machine's capacity also sets the dispatcher's executors. When — you run a full project check, tests, typecheck, lint, e2e; a run is silent with the line 'slot: waiting for the machine queue'; parallel sessions choke the machine and runs hit timeouts; you set up runner workers (Vitest, Playwright, Jest) locally; a heavy command bypasses the project's scripts — even if the word 'queue' was never said."
|
|
4
4
|
allowed-tools: Bash(bun *skills/slot/scripts/slot.ts *)
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -9,8 +9,8 @@ allowed-tools: Bash(bun *skills/slot/scripts/slot.ts *)
|
|
|
9
9
|
Parallel sessions run the full check all at once, and each runner is sized for
|
|
10
10
|
the whole machine: a run that takes seconds alone drags on for minutes next to
|
|
11
11
|
a dozen neighbors and gets cut off by the tool timeout, and a retry adds load.
|
|
12
|
-
The `scripts/slot.ts` script next to this file lets
|
|
13
|
-
time, the rest wait in arrival order; together the slots take half of the
|
|
12
|
+
The `scripts/slot.ts` script next to this file lets as many heavy runs go at a
|
|
13
|
+
time as the machine has slots (below), the rest wait in arrival order; together the slots take half of the
|
|
14
14
|
cores, the other half is for the human, the app and the agents themselves. Why
|
|
15
15
|
it is so and what was rejected — `tests/capabilities/slot/queue.md` in Elves.
|
|
16
16
|
|
|
@@ -83,6 +83,8 @@ what its parent loaded.
|
|
|
83
83
|
| Check before a commit, a full run, e2e | via the project's scripts (`npm run test -- --changed=origin/main`, `bun run typecheck`): they are already queued; which tests before a commit — `docs/testing.md`. As a background command with a generous timeout (Claude Code — `run_in_background`, up to 2 h): waiting in the queue doesn't eat the tool timeout, completion wakes the session |
|
|
84
84
|
| `slot: waiting for the machine queue — running …` | not a hang: who holds the slots (directory, command) and how long they have been running. Don't kill someone else's run or delete its ticket |
|
|
85
85
|
| `slot: waited …` | the time in the queue; compare run speed without it — by CI or by `user` from `time` |
|
|
86
|
+
| `slot: waiting for the machine load — …` | the slot is free, but the machine is loaded from outside the queue (dev servers, builds, Docker, e2e browsers); the run goes when the load drops or past the wait limit — below |
|
|
87
|
+
| `slot: the machine is overloaded — …` at the start, `the machine's load at the end of the run` at the end | the run went past the load wait limit: its timeouts are the machine's load, not a defect — don't fix tests or code for them; rerun when the load is down |
|
|
86
88
|
| A targeted run (`vitest run <file>`) | bypasses the queue — it's cheap |
|
|
87
89
|
| A heavy command bypassing the project's scripts | `bun --no-env-file <skill dir>/scripts/slot.ts '<command>'` |
|
|
88
90
|
| Bringing a task's stack up | heavy work too — containers with databases and a broker start at once: `task-env up` and `e2e` hold a slot until the containers are healthy, not for the stack's life; not `docker compose up` by hand — `check` names a package.json script that does it |
|
|
@@ -90,7 +92,8 @@ what its parent loaded.
|
|
|
90
92
|
|
|
91
93
|
## Runner workers
|
|
92
94
|
|
|
93
|
-
In a slot the command gets `ELVES_SLOT_CPUS` —
|
|
95
|
+
In a slot the command gets `ELVES_SLOT_CPUS` — its share of half of the
|
|
96
|
+
cores (a quarter with two slots). A
|
|
94
97
|
runner that counts workers from all cores takes the whole machine even in a
|
|
95
98
|
slot; its config reads the variable, and in CI and outside the queue it keeps
|
|
96
99
|
its own default:
|
|
@@ -118,6 +121,54 @@ Not `env` and not `globalEnv`: they go into the cache hash, while
|
|
|
118
121
|
machine. A script in `slot` calls turbo without pass-through — `install` and
|
|
119
122
|
`check` warn with a ready-made line.
|
|
120
123
|
|
|
124
|
+
## The machine's capacity
|
|
125
|
+
|
|
126
|
+
How many slots and how many executors a dispatcher runs at once (`github task
|
|
127
|
+
queue`, its `Next:` line) is the machine's, not the project's: the same
|
|
128
|
+
repository opens on a laptop, a workstation and in the cloud. `machine.json`
|
|
129
|
+
of the personal configuration directory sets them:
|
|
130
|
+
|
|
131
|
+
```json
|
|
132
|
+
{ "slots": 3, "executors": 5 }
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Either field is optional. Without it — by the machine: slots — one per 8
|
|
136
|
+
cores, never fewer than two; executors — one per 4 cores and per 8 GB of
|
|
137
|
+
memory, the smaller. All slots together get half of the cores. `slot
|
|
138
|
+
--capacity` prints the machine's capacity as JSON, `check -g` — as the
|
|
139
|
+
`machine:` line with where each number comes from; a value that isn't a
|
|
140
|
+
positive integer — a warning line and its default. Why these defaults —
|
|
141
|
+
`tests/capabilities/slot/capacity.md` in Elves.
|
|
142
|
+
|
|
143
|
+
The defaults are a guess; the run log and a measurement check them on this
|
|
144
|
+
machine (`tests/capabilities/slot/runs.md` in Elves):
|
|
145
|
+
|
|
146
|
+
- **The run log** — every run in the queue appends a line to `runs.jsonl`
|
|
147
|
+
next to `slots/`: the wait, the duration, the load average at the start and
|
|
148
|
+
the end, free memory, the neighbors in slots, the command and the directory;
|
|
149
|
+
it keeps the newest few thousand runs. `slot --log` — the median and the
|
|
150
|
+
90th percentile of the wait and the duration by the number of neighbors and
|
|
151
|
+
by the load per core: the wait grows with neighbors — too few slots; the
|
|
152
|
+
duration grows with the load at the same neighbors — the machine is busy
|
|
153
|
+
outside the queue; little free memory — fewer executors, not slots.
|
|
154
|
+
- **The measurement** — `slot --measure '<command>' [copies]` on an idle
|
|
155
|
+
machine: one heavy command (`bun run typecheck`, the full test run) by 1,
|
|
156
|
+
2, … copies at once (4 by default), each with its share of cores; the time
|
|
157
|
+
of one run at each count and `{"slots": N}` for `machine.json` — the most
|
|
158
|
+
copies before the time grows by half.
|
|
159
|
+
|
|
160
|
+
## The machine's load
|
|
161
|
+
|
|
162
|
+
The queue counts only its own runs. A run whose slot is free also waits while
|
|
163
|
+
the machine's load average for a minute is at the limit per core or above,
|
|
164
|
+
printing the load; past the wait limit it goes anyway and prints the load at
|
|
165
|
+
its start and end (for a `package.json` script — once its shell exits).
|
|
166
|
+
`machine.json` sets both: `{"load": 1, "loadWait": 300}` — the limit per core
|
|
167
|
+
and the wait in seconds, these are the defaults; the variable
|
|
168
|
+
`ELVES_SLOT_LOAD` replaces the limit for a run. The limit is read anew while
|
|
169
|
+
waiting: raising it lets a waiting run go. Why — `tests/capabilities/slot/load.md`
|
|
170
|
+
in Elves.
|
|
171
|
+
|
|
121
172
|
## Queue
|
|
122
173
|
|
|
123
174
|
A run's ticket is a file `<time>-<pid>` in `slots/` of the personal
|
|
@@ -1,19 +1,24 @@
|
|
|
1
1
|
#!/usr/bin/env bun
|
|
2
2
|
/**
|
|
3
|
-
* slot — a queue for heavy runs on the machine (the slot skill): a command goes when one of
|
|
4
|
-
* wait in arrival order and print whom they wait for. Parallel agent sessions ran the full check at once, each
|
|
5
|
-
* all cores, and the runs hit timeouts (tests/capabilities/slot/queue).
|
|
3
|
+
* slot — a queue for heavy runs on the machine (the slot skill): a command goes when one of the machine's slots is free,
|
|
4
|
+
* the rest wait in arrival order and print whom they wait for. Parallel agent sessions ran the full check at once, each
|
|
5
|
+
* runner on all cores, and the runs hit timeouts (tests/capabilities/slot/queue).
|
|
6
6
|
*
|
|
7
7
|
* A slot is a ticket file `<time>-<pid>` in `slots/` of the personal configuration directory: the name sets the order, the
|
|
8
8
|
* PID tells whether the owner is alive. A dead process, even one killed without cleanup, has its ticket ignored and removed
|
|
9
9
|
* by the first one to see it: there are no locks to remove by hand. The command gets ELVES_SLOT_CPUS: all slots together
|
|
10
|
-
* take half of the cores.
|
|
10
|
+
* take half of the cores. How many slots — machine.json of the personal configuration, otherwise by the cores (#779).
|
|
11
11
|
*
|
|
12
12
|
* An agent's sandbox doesn't let the configuration be written: the ticket goes to `elves/slots` of the temp directory
|
|
13
13
|
* (Claude Code's sandbox gives all sessions of the user one TMPDIR), and the queue is read from all places at once — runs
|
|
14
14
|
* inside and outside the sandbox wait for each other. No place takes the ticket — one warning line and the command runs
|
|
15
15
|
* without the queue.
|
|
16
16
|
*
|
|
17
|
+
* The queue counts only its own runs, while parallel sessions' dev servers, builds, Docker VMs and e2e browsers load the
|
|
18
|
+
* machine past it: a run at the head of the queue also waits while the machine's load average is at the limit per core,
|
|
19
|
+
* at most the wait limit — then it goes and says at its start and end that the machine is overloaded, so its timeouts
|
|
20
|
+
* read as load, not as a defect (#778).
|
|
21
|
+
*
|
|
17
22
|
* No queue in CI (the machine is given to the run) and inside a slot (ELVES_SLOT): a script that calls another script
|
|
18
23
|
* through the queue would otherwise wait for itself.
|
|
19
24
|
*
|
|
@@ -21,13 +26,18 @@
|
|
|
21
26
|
* --for $$`): the ticket carries the script's shell, not this process, and the queue variables are printed for the shell
|
|
22
27
|
* to export — the command runs as a plain command of the script, visible to tools that read package.json (knip).
|
|
23
28
|
*
|
|
29
|
+
* Every run in the queue leaves a record in the run log `runs.jsonl` next to its ticket's `slots/`: the wait, the
|
|
30
|
+
* duration, the load and the neighbors (tests/capabilities/slot/runs); `--log` sums it up, `--measure` runs one command
|
|
31
|
+
* by 1…N copies at once — how many slots the machine holds.
|
|
32
|
+
*
|
|
24
33
|
* Runs under Bun (`bun slot.ts`), only node: APIs. A project runs it from its package as `elves slot` (bin/elves.ts
|
|
25
34
|
* imports `main` and `HELP`): the queue starts only when this file is the entry point.
|
|
26
35
|
*/
|
|
27
36
|
import { spawn } from "node:child_process";
|
|
28
|
-
import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
37
|
+
import { appendFileSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
|
|
29
38
|
import os from "node:os";
|
|
30
39
|
import path from "node:path";
|
|
40
|
+
import { fileURLToPath } from "node:url";
|
|
31
41
|
|
|
32
42
|
/**
|
|
33
43
|
* `--help`, `-h` as the first argument — the rest go to the command (tests/standards/scripts/cli-help): synopsis, what, examples;
|
|
@@ -35,22 +45,138 @@ import path from "node:path";
|
|
|
35
45
|
*/
|
|
36
46
|
export const HELP = `slot '<command>' [arguments…]
|
|
37
47
|
slot --for <PID>
|
|
48
|
+
slot --capacity
|
|
49
|
+
slot --log
|
|
50
|
+
slot --measure '<command>' [copies]
|
|
51
|
+
|
|
52
|
+
Runs the command through sh, the arguments appended to its end, as with npm run; waits while the machine's slots are
|
|
53
|
+
taken by heavy runs, then runs with ELVES_SLOT_CPUS — its share of half of the cores. --for — takes a slot for the shell
|
|
54
|
+
<PID> of a package.json script, held until the shell exits, and prints the export of ELVES_SLOT, ELVES_SLOT_CPUS for
|
|
55
|
+
it — the project's shim runs it: ". .agents/slot.sh && <command>". --capacity — the machine's capacity as one JSON line:
|
|
56
|
+
slots, cores per slot, the dispatcher's executors and where each comes from. Slots and executors — machine.json of the
|
|
57
|
+
personal configuration ({"slots": N, "executors": M}), otherwise by the cores and memory. No queue in CI and inside a
|
|
58
|
+
slot. A run at the head of the queue also waits while the machine's load average (1 min) is at the limit per core or
|
|
59
|
+
above — machine.json {"load": L, "loadWait": S}, 1 and 300 s by default, ELVES_SLOT_LOAD replaces L; past S seconds it
|
|
60
|
+
goes and prints the machine's load at its start and end. The exit code is the command's; with --for — 0, nothing
|
|
61
|
+
printed without the queue.
|
|
38
62
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
63
|
+
Every run in the queue goes to the run log runs.jsonl next to slots/: the wait in the queue, the duration, the load
|
|
64
|
+
average at the start and the end, free memory, the neighbors in slots, the command and the directory; the log keeps the
|
|
65
|
+
newest runs. --log — its summary: the median and the 90th percentile of the wait and the duration by the number of
|
|
66
|
+
neighbors and by the load per core. --measure — the command by 1, 2, … copies (4 by default) at once, outside the queue,
|
|
67
|
+
each with its share of cores: the time of one run at each count and the slots for machine.json — the most copies before
|
|
68
|
+
the time grows by half; run it on an idle machine. Exit code — 1 if a copy failed.
|
|
44
69
|
|
|
45
70
|
Examples:
|
|
46
71
|
slot 'vitest run'
|
|
47
72
|
slot 'bun test' tests/standards
|
|
73
|
+
slot --capacity
|
|
74
|
+
slot --log
|
|
75
|
+
slot --measure 'bun run typecheck' 4
|
|
48
76
|
`;
|
|
49
77
|
|
|
50
|
-
/**
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
78
|
+
/** The machine's capacity: heavy runs at once, runner workers per slot, the dispatcher's background executors. */
|
|
79
|
+
export interface Capacity {
|
|
80
|
+
slots: number;
|
|
81
|
+
cpus: number;
|
|
82
|
+
executors: number;
|
|
83
|
+
/** Where slots and executors come from: `machine.json` or the machine's cores and memory. */
|
|
84
|
+
from: { slots: string; executors: string };
|
|
85
|
+
/** A value of machine.json that isn't a positive integer — its default goes instead. */
|
|
86
|
+
warnings: string[];
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* The capacity by the machine's cores and memory (bytes) and machine.json's values. Slots — one per 8 cores, never fewer
|
|
91
|
+
* than two: `lint` and `typecheck` are mostly single-threaded, and two runs by a quarter of the cores pass the queue
|
|
92
|
+
* faster than one by half (tests/capabilities/slot/queue.md). All slots together get half of the cores, the other half
|
|
93
|
+
* is for the human, the app and the agents. Executors — one per 4 cores and per 8 GB, the smaller: each brings its task
|
|
94
|
+
* stack and dev server, and memory runs out before the cores do. machine.json replaces either (#779).
|
|
95
|
+
*/
|
|
96
|
+
export function capacity(cores: number, memory: number, config: Record<string, unknown> = {}): Capacity {
|
|
97
|
+
const warnings: string[] = [];
|
|
98
|
+
const given = (key: "slots" | "executors") => {
|
|
99
|
+
const v = config[key];
|
|
100
|
+
if (v === undefined) return undefined;
|
|
101
|
+
if (Number.isInteger(v) && (v as number) > 0) return v as number;
|
|
102
|
+
warnings.push(`machine.json: ${key} must be a positive integer, got ${JSON.stringify(v)} — the default goes`);
|
|
103
|
+
return undefined;
|
|
104
|
+
};
|
|
105
|
+
const gb = Math.floor(memory / 2 ** 30);
|
|
106
|
+
const slots = given("slots");
|
|
107
|
+
const executors = given("executors");
|
|
108
|
+
const s = slots ?? Math.max(2, Math.floor(cores / 8));
|
|
109
|
+
return {
|
|
110
|
+
slots: s,
|
|
111
|
+
cpus: Math.max(1, Math.floor(cores / 2 / s)),
|
|
112
|
+
executors: executors ?? Math.max(1, Math.min(Math.floor(cores / 4), Math.floor(gb / 8))),
|
|
113
|
+
from: { slots: slots ? "machine.json" : `${cores} cores`, executors: executors ? "machine.json" : `${cores} cores, ${gb} GB` },
|
|
114
|
+
warnings,
|
|
115
|
+
};
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** machine.json of the personal configuration directory: no file — `{}`, a file that isn't a JSON object — `{}` and why. */
|
|
119
|
+
function machineConfig(env: Record<string, string | undefined>): { config: Record<string, unknown>; broken: string } {
|
|
120
|
+
try {
|
|
121
|
+
const parsed: unknown = JSON.parse(readFileSync(path.join(configDir(env), "machine.json"), "utf8"));
|
|
122
|
+
if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return { config: parsed as Record<string, unknown>, broken: "" };
|
|
123
|
+
return { config: {}, broken: "not a JSON object" };
|
|
124
|
+
} catch (e) {
|
|
125
|
+
return { config: {}, broken: (e as NodeJS.ErrnoException).code === "ENOENT" ? "" : (e as Error).message };
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* This machine's capacity: machine.json of the personal configuration directory; no file — the defaults, a file that isn't a JSON object — a warning and the defaults.
|
|
131
|
+
*/
|
|
132
|
+
export function machineCapacity(env: Record<string, string | undefined> = process.env): Capacity {
|
|
133
|
+
const { config, broken } = machineConfig(env);
|
|
134
|
+
const c = capacity(os.availableParallelism(), os.totalmem(), config);
|
|
135
|
+
return broken ? { ...c, warnings: [`machine.json: ${broken} — the defaults go`, ...c.warnings] } : c;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/** When the machine counts as overloaded for a heavy run and how long a run waits for its load to drop. */
|
|
139
|
+
export interface LoadLimit {
|
|
140
|
+
/** The load average (1 min) per core at which the machine is overloaded. */
|
|
141
|
+
perCore: number;
|
|
142
|
+
/** How long a run at the head of the queue waits for the load to drop, ms; past it the run goes anyway. */
|
|
143
|
+
wait: number;
|
|
144
|
+
/** A value that isn't a non-negative number — its default goes instead. */
|
|
145
|
+
warnings: string[];
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* The load limit by machine.json's `load` and `loadWait` and the ELVES_SLOT_LOAD variable, which replaces `load` for a
|
|
150
|
+
* run. A load of 1 per core — every core has a runnable process: the queue's own slots take half of the cores, so at
|
|
151
|
+
* the limit the other half is taken from outside the queue. 300 s — longer than a project's full check usually goes,
|
|
152
|
+
* shorter than an agent's tool timeout (10 min), which would cut off a run that never started (#778).
|
|
153
|
+
*/
|
|
154
|
+
export function loadLimit(config: Record<string, unknown> = {}, env: Record<string, string | undefined> = {}): LoadLimit {
|
|
155
|
+
const warnings: string[] = [];
|
|
156
|
+
const given = (from: string, v: unknown, integer: boolean) => {
|
|
157
|
+
if (v === undefined || v === "") return undefined;
|
|
158
|
+
const n = typeof v === "string" ? Number(v) : v;
|
|
159
|
+
if (typeof n === "number" && Number.isFinite(n) && n >= 0 && (!integer || Number.isInteger(n))) return n;
|
|
160
|
+
warnings.push(`${from} must be a non-negative ${integer ? "integer" : "number"}, got ${JSON.stringify(v)} — the default goes`);
|
|
161
|
+
return undefined;
|
|
162
|
+
};
|
|
163
|
+
const perCore = given("ELVES_SLOT_LOAD", env.ELVES_SLOT_LOAD, false) ?? given("machine.json: load", config.load, false) ?? 1;
|
|
164
|
+
const wait = given("machine.json: loadWait", config.loadWait, true) ?? 300;
|
|
165
|
+
return { perCore, wait: wait * 1000, warnings };
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/** This machine's load limit, machine.json read anew: the owner may raise the limit while a run waits. */
|
|
169
|
+
const machineLoadLimit = () => loadLimit(machineConfig(process.env).config, process.env);
|
|
170
|
+
|
|
171
|
+
/** The machine's load now against the limit: the load average for a minute (Windows has none — 0) and the cores. */
|
|
172
|
+
function machineLoad(limit: LoadLimit) {
|
|
173
|
+
const cores = os.availableParallelism();
|
|
174
|
+
const load = os.loadavg()[0]!;
|
|
175
|
+
return { over: load >= limit.perCore * cores, text: `load ${load.toFixed(1)} on ${cores} cores, the limit ${+(limit.perCore * cores).toFixed(1)} (${limit.perCore} per core)` };
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
/** The line of the end of a run admitted on an overloaded machine: the machine's load then. */
|
|
179
|
+
const endLine = () => `slot: the machine's load at the end of the run — ${machineLoad(machineLoadLimit()).text}\n`;
|
|
54
180
|
/** How often a waiting process looks at the queue, ms: a directory of a few files is read in microseconds. */
|
|
55
181
|
const POLL = 250;
|
|
56
182
|
/**
|
|
@@ -82,14 +208,16 @@ function alive(pid: number) {
|
|
|
82
208
|
}
|
|
83
209
|
}
|
|
84
210
|
|
|
211
|
+
/** The personal configuration directory — the same expression in all scripts (tests/standards/scripts/config-dir). */
|
|
212
|
+
const configDir = (env: Record<string, string | undefined>) => env.ELVES_CONFIG_DIR || path.join(os.homedir(), ".config", "elves");
|
|
213
|
+
|
|
85
214
|
/**
|
|
86
215
|
* Where tickets live, in the order a ticket is written: the personal configuration, then the temp directory — an agent's
|
|
87
216
|
* sandbox doesn't let the configuration be written, while its TMPDIR is shared by the sandbox's sessions; Claude Code
|
|
88
217
|
* passes its sandbox's temp directory as CLAUDE_TMPDIR outside the sandbox too, so runs outside wait for runs inside.
|
|
89
|
-
* The personal configuration directory — the same expression in all scripts (tests/standards/scripts/config-dir).
|
|
90
218
|
*/
|
|
91
219
|
function places() {
|
|
92
|
-
const config = process.env
|
|
220
|
+
const config = configDir(process.env);
|
|
93
221
|
const temps = [os.tmpdir(), process.env.CLAUDE_TMPDIR].filter((d): d is string => !!d);
|
|
94
222
|
return [...new Set([config, ...temps.map((d) => path.join(d, "elves"))].map((d) => path.join(path.resolve(d), "slots")))];
|
|
95
223
|
}
|
|
@@ -165,10 +293,190 @@ function run(command: string, env: Record<string, string>) {
|
|
|
165
293
|
});
|
|
166
294
|
}
|
|
167
295
|
|
|
296
|
+
/** A run of the log: what the queue and the machine were like when it got its slot, and how long it went. */
|
|
297
|
+
export interface RunRecord {
|
|
298
|
+
/** When it got its slot, ms since the epoch. */
|
|
299
|
+
at: number;
|
|
300
|
+
/** In the queue, ms. */
|
|
301
|
+
wait: number;
|
|
302
|
+
/** In its slot, ms: the command — or the script's shell, held with --for. */
|
|
303
|
+
ms: number;
|
|
304
|
+
/** Other runs in slots when it got its own. */
|
|
305
|
+
neighbors: number;
|
|
306
|
+
/** Runs waiting in the queue when it got its slot. */
|
|
307
|
+
queued: number;
|
|
308
|
+
slots: number;
|
|
309
|
+
cores: number;
|
|
310
|
+
/** Load average over a minute at the start and at the end. */
|
|
311
|
+
load: [number, number];
|
|
312
|
+
/** Free memory at the start, a share of all. */
|
|
313
|
+
mem: number;
|
|
314
|
+
cmd: string;
|
|
315
|
+
cwd: string;
|
|
316
|
+
/** The command's exit code; a script's shell (--for) runs the command itself — none. */
|
|
317
|
+
code?: number;
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
/** The run log keeps the newest runs: past this size the older half goes — a few thousand runs remain. */
|
|
321
|
+
const LOG_LIMIT = 1 << 20;
|
|
322
|
+
/** The run log of a place — next to its `slots/`. */
|
|
323
|
+
const logOf = (slots: string) => path.join(path.dirname(slots), "runs.jsonl");
|
|
324
|
+
const load1 = () => Math.round((os.loadavg()[0] ?? 0) * 100) / 100;
|
|
325
|
+
|
|
326
|
+
/**
|
|
327
|
+
* Appends a run to the log; past `limit` bytes the older half of the runs goes. Two runs trimming at once may lose a
|
|
328
|
+
* record — the log is a trace for a summary, not an account; a place that refuses doesn't fail the command.
|
|
329
|
+
*/
|
|
330
|
+
export function record(file: string, run: RunRecord, limit = LOG_LIMIT) {
|
|
331
|
+
try {
|
|
332
|
+
appendFileSync(file, `${JSON.stringify(run)}\n`);
|
|
333
|
+
if (statSync(file).size <= limit) return;
|
|
334
|
+
const lines = readFileSync(file, "utf8").split("\n").filter(Boolean);
|
|
335
|
+
writeFileSync(file, `${lines.slice(Math.floor(lines.length / 2)).join("\n")}\n`);
|
|
336
|
+
} catch {
|
|
337
|
+
/* no log is no reason not to run */
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
/**
|
|
342
|
+
* The end of a script's run (--for): the script's shell runs the command itself, and `slot` exits with the slot taken —
|
|
343
|
+
* a detached process waits for the shell to exit and writes the run; a run admitted on an overloaded machine also gets
|
|
344
|
+
* its end line, on the script's stderr.
|
|
345
|
+
*/
|
|
346
|
+
export async function finish(shell: number, file: string, start: Omit<RunRecord, "ms" | "load"> & { load: number }, overloaded = false) {
|
|
347
|
+
while (alive(shell)) await new Promise((r) => setTimeout(r, POLL));
|
|
348
|
+
record(file, { ...start, ms: Date.now() - start.at, load: [start.load, load1()] });
|
|
349
|
+
if (overloaded) process.stderr.write(endLine());
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/** Runs of all places' logs, oldest first; a broken line is skipped. */
|
|
353
|
+
function readRuns(dirs: string[]): RunRecord[] {
|
|
354
|
+
const runs: RunRecord[] = [];
|
|
355
|
+
for (const dir of dirs) {
|
|
356
|
+
let text = "";
|
|
357
|
+
try {
|
|
358
|
+
text = readFileSync(logOf(dir), "utf8");
|
|
359
|
+
} catch {
|
|
360
|
+
continue;
|
|
361
|
+
}
|
|
362
|
+
for (const line of text.split("\n")) {
|
|
363
|
+
try {
|
|
364
|
+
const r = JSON.parse(line);
|
|
365
|
+
if (typeof r?.wait === "number" && typeof r?.ms === "number") runs.push(r);
|
|
366
|
+
} catch {
|
|
367
|
+
/* an empty or cut line */
|
|
368
|
+
}
|
|
369
|
+
}
|
|
370
|
+
}
|
|
371
|
+
return runs.sort((a, b) => a.at - b.at);
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
/** The p-th percentile by the nearest rank. */
|
|
375
|
+
const percentile = (xs: number[], p: number) => [...xs].sort((a, b) => a - b)[Math.max(0, Math.ceil(p * xs.length) - 1)] ?? 0;
|
|
376
|
+
/** A time for a table: tenths of a second under 10 s. */
|
|
377
|
+
const seconds = (ms: number) => (ms < 10_000 ? `${(ms / 1000).toFixed(1)} s` : duration(ms));
|
|
378
|
+
/** Load per core at the start — bands of a quarter: where the duration breaks. */
|
|
379
|
+
const BANDS = ["< 0.25", "0.25–0.5", "0.5–0.75", "0.75–1", "≥ 1"];
|
|
380
|
+
const band = (r: RunRecord) => BANDS[Math.min(4, Math.floor((r.load[0] / r.cores) * 4))] ?? "≥ 1";
|
|
381
|
+
|
|
382
|
+
/**
|
|
383
|
+
* The log's summary: the median and the 90th percentile of the wait and the duration by the number of neighbors and by
|
|
384
|
+
* the load per core at the start — where the wait or the duration breaks, there the machine's limit is.
|
|
385
|
+
*/
|
|
386
|
+
export function summarize(runs: RunRecord[]): string {
|
|
387
|
+
if (!runs.length) return "slot: the run log is empty — no runs through the queue yet\n";
|
|
388
|
+
const day = (ms: number) => new Date(ms).toISOString().slice(0, 10);
|
|
389
|
+
const head = ["runs", "wait p50", "wait p90", "run p50", "run p90"];
|
|
390
|
+
const table = (title: string, groups: [string, RunRecord[]][]) => {
|
|
391
|
+
const rows = [[title, ...head], ...groups.map(([k, g]) => {
|
|
392
|
+
const wait = g.map((r) => r.wait);
|
|
393
|
+
const ms = g.map((r) => r.ms);
|
|
394
|
+
return [k, String(g.length), seconds(percentile(wait, 0.5)), seconds(percentile(wait, 0.9)), seconds(percentile(ms, 0.5)), seconds(percentile(ms, 0.9))];
|
|
395
|
+
})];
|
|
396
|
+
const width = head.map((_, i) => Math.max(...rows.map((r) => (r[i + 1] ?? "").length)));
|
|
397
|
+
const first = Math.max(...rows.map((r) => (r[0] ?? "").length));
|
|
398
|
+
return rows.map((r) => [(r[0] ?? "").padEnd(first), ...r.slice(1).map((c, i) => c.padStart(width[i] ?? 0))].join(" ")).join("\n");
|
|
399
|
+
};
|
|
400
|
+
const by = <K,>(key: (r: RunRecord) => K) => {
|
|
401
|
+
const m = new Map<K, RunRecord[]>();
|
|
402
|
+
for (const r of runs) m.set(key(r), [...(m.get(key(r)) ?? []), r]);
|
|
403
|
+
return m;
|
|
404
|
+
};
|
|
405
|
+
const neighbors = [...by((r) => r.neighbors)].sort(([a], [b]) => a - b).map(([k, g]) => [String(k), g] as [string, RunRecord[]]);
|
|
406
|
+
const loads = by(band);
|
|
407
|
+
const last = runs.at(-1)!;
|
|
408
|
+
return [
|
|
409
|
+
`slot: ${runs.length} runs ${day(runs[0]!.at)} — ${day(last.at)}; now ${last.slots} slots, ${last.cores} cores`,
|
|
410
|
+
"",
|
|
411
|
+
table("neighbors", neighbors),
|
|
412
|
+
"",
|
|
413
|
+
table("load/core", BANDS.filter((b) => loads.has(b)).map((b) => [b, loads.get(b)!])),
|
|
414
|
+
"",
|
|
415
|
+
].join("\n");
|
|
416
|
+
}
|
|
417
|
+
|
|
418
|
+
/** One run's time grows by more than this share over a run alone — the machine is past its slots. */
|
|
419
|
+
const GROWTH = 1.5;
|
|
420
|
+
|
|
421
|
+
/** Slots by the measurement: `times[k - 1]` — one run's time with k copies at once; the most copies before it grows by half. */
|
|
422
|
+
export function recommend(times: number[]): number {
|
|
423
|
+
let k = 1;
|
|
424
|
+
const [alone = 0] = times;
|
|
425
|
+
while (k < times.length && (times[k] ?? Infinity) <= alone * GROWTH) k++;
|
|
426
|
+
return k;
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
/** The command once, its output kept for a failure; the time, ms. */
|
|
430
|
+
function timed(command: string, env: Record<string, string>) {
|
|
431
|
+
return new Promise<{ code: number; ms: number; out: string }>((resolve) => {
|
|
432
|
+
const t0 = Date.now();
|
|
433
|
+
let out = "";
|
|
434
|
+
const child = spawn(command, { shell: true, stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, ...env } });
|
|
435
|
+
const keep = (d: Buffer) => (out = (out + d).slice(-2000));
|
|
436
|
+
child.stdout.on("data", keep);
|
|
437
|
+
child.stderr.on("data", keep);
|
|
438
|
+
child.on("error", (e) => resolve({ code: 127, ms: Date.now() - t0, out: e.message }));
|
|
439
|
+
child.on("close", (code) => resolve({ code: code ?? 1, ms: Date.now() - t0, out }));
|
|
440
|
+
});
|
|
441
|
+
}
|
|
442
|
+
|
|
443
|
+
/** --measure: the command by 1…copies at once, each with its share of half of the cores — as in that many slots. */
|
|
444
|
+
async function measure(command: string, copies: number): Promise<number> {
|
|
445
|
+
const cores = os.availableParallelism();
|
|
446
|
+
const busy = queue(places()).length;
|
|
447
|
+
if (busy) process.stderr.write(`slot: ${busy} runs in the queue now — the measurement counts them as the machine's load\n`);
|
|
448
|
+
const times: number[] = [];
|
|
449
|
+
for (let k = 1; k <= copies; k++) {
|
|
450
|
+
const cpus = Math.max(1, Math.floor(cores / 2 / k));
|
|
451
|
+
const before = load1();
|
|
452
|
+
const runs = await Promise.all(Array.from({ length: k }, () => timed(command, { ELVES_SLOT: "measure", ELVES_SLOT_CPUS: String(cpus) })));
|
|
453
|
+
const failed = runs.find((r) => r.code !== 0);
|
|
454
|
+
if (failed) return process.stderr.write(`slot: a copy failed with code ${failed.code} — nothing to measure:\n${failed.out}\n`), 1;
|
|
455
|
+
const mean = runs.reduce((s, r) => s + r.ms, 0) / k;
|
|
456
|
+
times.push(mean);
|
|
457
|
+
process.stdout.write(`${k} at once: ${seconds(mean)} per run, ${cpus} cores each, load ${before} → ${load1()}\n`);
|
|
458
|
+
}
|
|
459
|
+
const k = recommend(times);
|
|
460
|
+
process.stdout.write(`slots: ${k} — the most copies before one run's time grows by half; machine.json: {"slots": ${k}}\n`);
|
|
461
|
+
return 0;
|
|
462
|
+
}
|
|
463
|
+
|
|
168
464
|
export async function main(argv: string[]): Promise<number> {
|
|
169
465
|
const [first, ...rest] = argv;
|
|
170
466
|
if (first === "-h" || first === "--help") return process.stdout.write(HELP), 0;
|
|
171
467
|
if (!first) return process.stderr.write(HELP), 2;
|
|
468
|
+
if (first === "--capacity") return process.stdout.write(`${JSON.stringify(machineCapacity())}\n`), 0;
|
|
469
|
+
if (first === "--log") {
|
|
470
|
+
if (rest.length) return process.stderr.write(`slot: --log takes no arguments, got ${rest.join(" ")}\n${HELP}`), 2;
|
|
471
|
+
return process.stdout.write(summarize(readRuns(places()))), 0;
|
|
472
|
+
}
|
|
473
|
+
if (first === "--measure") {
|
|
474
|
+
const copies = rest[1] === undefined ? 4 : Number(rest[1]);
|
|
475
|
+
if (!rest[0] || rest.length > 2 || !Number.isInteger(copies) || copies < 1) {
|
|
476
|
+
return process.stderr.write(`slot: --measure takes a command and the number of copies, got ${rest.join(" ") || "nothing"}\n${HELP}`), 2;
|
|
477
|
+
}
|
|
478
|
+
return measure(rest[0], copies);
|
|
479
|
+
}
|
|
172
480
|
// --for: the slot is the shell's — it holds the ticket, gets the variables and runs the command itself
|
|
173
481
|
const shell = first === "--for" ? Number(rest[0]) : 0;
|
|
174
482
|
if (first === "--for" && !(rest.length === 1 && Number.isInteger(shell) && shell > 0 && alive(shell))) {
|
|
@@ -180,12 +488,15 @@ export async function main(argv: string[]): Promise<number> {
|
|
|
180
488
|
const ci = process.env.CI && !/^(0|false)$/i.test(process.env.CI);
|
|
181
489
|
if (ci || process.env.ELVES_SLOT) return free();
|
|
182
490
|
|
|
491
|
+
const { slots: SLOTS, cpus: CPUS, warnings } = machineCapacity();
|
|
492
|
+
const cmd = shell ? (scriptCommand() ?? "?") : command;
|
|
493
|
+
for (const w of warnings) process.stderr.write(`slot: ${w}\n`);
|
|
183
494
|
const dirs = places();
|
|
184
495
|
const name = `${String(Date.now()).padStart(15, "0")}-${shell || process.pid}`;
|
|
185
496
|
let file = "";
|
|
186
497
|
const enqueue = () => {
|
|
187
498
|
mkdirSync(path.dirname(file), { recursive: true });
|
|
188
|
-
writeFileSync(file, JSON.stringify({ cwd: process.cwd(), cmd
|
|
499
|
+
writeFileSync(file, JSON.stringify({ cwd: process.cwd(), cmd, since: Date.now() }));
|
|
189
500
|
};
|
|
190
501
|
const refused: string[] = [];
|
|
191
502
|
for (const dir of dirs) {
|
|
@@ -216,6 +527,12 @@ export async function main(argv: string[]): Promise<number> {
|
|
|
216
527
|
let confirmed = false;
|
|
217
528
|
let told = "";
|
|
218
529
|
let toldAt = 0;
|
|
530
|
+
let neighbors = 0;
|
|
531
|
+
let queued = 0;
|
|
532
|
+
/** Since when the run stands at a free slot on an overloaded machine; the start line of a run admitted past the wait limit. */
|
|
533
|
+
let loadSince = 0;
|
|
534
|
+
let overloaded = "";
|
|
535
|
+
const warned = new Set<string>();
|
|
219
536
|
for (;;) {
|
|
220
537
|
// the shell is gone while waiting (killed) — its ticket would be put back forever
|
|
221
538
|
if (shell && !alive(shell)) return 1;
|
|
@@ -227,9 +544,28 @@ export async function main(argv: string[]): Promise<number> {
|
|
|
227
544
|
i = q.findIndex((t) => t.name === name);
|
|
228
545
|
}
|
|
229
546
|
if (i >= 0 && i < SLOTS) {
|
|
230
|
-
|
|
231
|
-
confirmed
|
|
232
|
-
|
|
547
|
+
[neighbors, queued] = [Math.min(q.length, SLOTS) - 1, Math.max(0, q.length - SLOTS)];
|
|
548
|
+
if (!confirmed) {
|
|
549
|
+
confirmed = true;
|
|
550
|
+
await new Promise((r) => setTimeout(r, SETTLE));
|
|
551
|
+
continue;
|
|
552
|
+
}
|
|
553
|
+
// a free slot — and the machine's load from outside the queue
|
|
554
|
+
const limit = machineLoadLimit();
|
|
555
|
+
for (const w of limit.warnings) if (!warned.has(w)) warned.add(w), process.stderr.write(`slot: ${w}\n`);
|
|
556
|
+
const load = machineLoad(limit);
|
|
557
|
+
if (!load.over) break;
|
|
558
|
+
loadSince ||= Date.now();
|
|
559
|
+
const waited = Date.now() - loadSince;
|
|
560
|
+
if (waited >= limit.wait) {
|
|
561
|
+
overloaded = `slot: the machine is overloaded — ${load.text}; the run goes after ${duration(waited)} of waiting for the load: its timeouts are the machine's load, not a defect of the tests or the code\n`;
|
|
562
|
+
break;
|
|
563
|
+
}
|
|
564
|
+
if (told !== "load" || Date.now() - toldAt >= REMIND) {
|
|
565
|
+
process.stderr.write(`slot: waiting for the machine load — ${load.text}; the run goes when it drops, at most in ${duration(limit.wait - waited)}\n`);
|
|
566
|
+
[told, toldAt] = ["load", Date.now()];
|
|
567
|
+
}
|
|
568
|
+
await new Promise((r) => setTimeout(r, POLL));
|
|
233
569
|
continue;
|
|
234
570
|
}
|
|
235
571
|
confirmed = false;
|
|
@@ -244,14 +580,24 @@ export async function main(argv: string[]): Promise<number> {
|
|
|
244
580
|
}
|
|
245
581
|
for (const s of SIGNALS) process.off(s, quit);
|
|
246
582
|
if (told) process.stderr.write(`slot: waited ${duration(Date.now() - t0)}\n`);
|
|
583
|
+
if (overloaded) process.stderr.write(overloaded);
|
|
247
584
|
const env = { ELVES_SLOT: name, ELVES_SLOT_CPUS: String(CPUS) };
|
|
585
|
+
const at = Date.now();
|
|
586
|
+
const start = { at, wait: at - t0, neighbors, queued, slots: SLOTS, cores: os.availableParallelism(), load: load1(), mem: Math.round((os.freemem() / os.totalmem()) * 100) / 100, cmd, cwd: process.cwd() };
|
|
587
|
+
const log = logOf(path.dirname(file));
|
|
248
588
|
if (shell) {
|
|
249
589
|
held = true;
|
|
590
|
+
// an overloaded run's end line goes to the script's stderr; its stdout the shim reads to its end — never held
|
|
591
|
+
const self = fileURLToPath(import.meta.url);
|
|
592
|
+
const end = `import(${JSON.stringify(self)}).then((m) => m.finish(${shell}, ${JSON.stringify(log)}, ${JSON.stringify(start)}, ${!!overloaded}))`;
|
|
593
|
+
spawn(process.execPath, ["--no-env-file", "-e", end], { detached: true, stdio: ["ignore", "ignore", overloaded ? "inherit" : "ignore"] }).unref();
|
|
250
594
|
process.stdout.write(`export ${Object.entries(env).map(([k, v]) => `${k}=${v}`).join(" ")}\n`);
|
|
251
595
|
return 0;
|
|
252
596
|
}
|
|
253
597
|
const code = await run(command, env);
|
|
254
598
|
drop();
|
|
599
|
+
record(log, { ...start, ms: Date.now() - at, load: [start.load, load1()], code });
|
|
600
|
+
if (overloaded) process.stderr.write(endLine());
|
|
255
601
|
return code;
|
|
256
602
|
}
|
|
257
603
|
|