@miroshnik/elves 2026.1107.0 → 2026.1112.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/bin/elves.ts CHANGED
@@ -209,7 +209,7 @@ breaks task isolation, standards and architecture have no test:spec script or th
209
209
  Elves clone too) with "batch": true runs a workflow on a PR into a batch branch — on.pull_request lets a batch branch in,
210
210
  its gate is the checks before a commit and pr premerge (ci.md of the spec skill, «Batches»), 2 — the check is unavailable; the machine's copy and a project's package version are compared with the latest release (from the npm
211
211
  package — by restarting from the latest release's package), a --link clone — with origin/main. For a project names the
212
- mode (auto) and the language, holds the compose file to the task isolation rules (❌ per violation, ○ — not checked: no
212
+ mode (auto) and the language, holds the compose file to the task isolation rules (❌ per violation, ! — a warning, ○ — not checked: no
213
213
  docker compose; the task-env skill), names a test that runs standards and architecture again next to test:spec (○, the
214
214
  ready test without them) and warns (!) if a script in slot calls turbo and turbo.json doesn't pass the queue variables
215
215
  to tasks (the exit code stays the same); for the machine the elves command missing or of another release is falling
@@ -1668,8 +1668,8 @@ interface Result {
1668
1668
 
1669
1669
  /**
1670
1670
  * The project's compose file against the task isolation rules (the task-env skill, tests/capabilities/task-env/stacks): a `❌`
1671
- * line per violation, `○` — not checked (no docker compose, the config doesn't parse): that isn't a violation, and the
1672
- * exit code of `check` doesn't change. No compose file — no lines, the script doesn't start. The script runs under the
1671
+ * line per violation, `!` — a warning, `○` — not checked (no docker compose, the config doesn't parse): neither is a
1672
+ * violation, and the exit code of `check` doesn't change. No compose file — no lines, the script doesn't start. The script runs under the
1673
1673
  * same Bun as the installer.
1674
1674
  */
1675
1675
  function composeCheck(root: string): { lines: string[]; violations: boolean } {
@@ -1678,8 +1678,8 @@ function composeCheck(root: string): { lines: string[]; violations: boolean } {
1678
1678
  const r = spawnSync(process.execPath, ["--no-env-file", TASK_ENV, "check", root], { encoding: "utf8", timeout: TASK_ENV_TIMEOUT });
1679
1679
  const notChecked = (why: string) => ({ lines: [` ○ ${file}: not checked — ${why}`], violations: false });
1680
1680
  if (r.error) return notChecked(`task-env: ${r.error.message}`);
1681
- if (r.status === 0) return { lines: [], violations: false };
1682
1681
  const lines = r.stdout.split("\n").filter(Boolean).map((l) => ` ${l}`);
1682
+ if (r.status === 0) return { lines: lines.filter((l) => l.startsWith(" !")), violations: false };
1683
1683
  if (r.status === 1 || (r.status === 2 && lines.length)) return { lines, violations: r.status === 1 };
1684
1684
  return notChecked(`task-env: ${r.stderr.trim().split("\n")[0] || `exit code ${r.status ?? r.signal}`}`);
1685
1685
  }
@@ -332,6 +332,7 @@ var M = {
332
332
  RemoveBlockedBy: ["removeBlockedBy", "RemoveBlockedByInput", "issue { id }"],
333
333
  SetIssueField: ["setIssueFieldValue", "SetIssueFieldValueInput", "issue { id }"],
334
334
  CloseIssue: ["closeIssue", "CloseIssueInput", "issue { id state }"],
335
+ ReopenIssue: ["reopenIssue", "ReopenIssueInput", "issue { id state }"],
335
336
  UpdateIssue: ["updateIssue", "UpdateIssueInput", "issue { id }"],
336
337
  AddComment: ["addComment", "AddCommentInput", "subject { id }"],
337
338
  CreateRuleset: ["createRepositoryRuleset", "CreateRepositoryRulesetInput", "ruleset { id }"],
@@ -3646,7 +3647,19 @@ function cmdTaskFinish(io, slug, number, o) {
3646
3647
  const outOfTime = (what) => stop(5, `○ out of time (--timeout ${o.timeout}) — ${what}`, `${again} — it goes on from here`);
3647
3648
  const issue = loadIssue(io, slug, number);
3648
3649
  if (issue.state !== "OPEN") {
3649
- const closer = issue.stateReason === "COMPLETED" ? issue.prs.find((p) => p.merged && !isBatchBranch(p.base)) ?? null : null;
3650
+ const closer = issue.stateReason === "COMPLETED" ? lastMerged(issue.prs.filter((p) => !isBatchBranch(p.base))) ?? null : null;
3651
+ const work = workPastMerge(io, slug, number, issue, closer);
3652
+ if (work) {
3653
+ if (issue.stateReason !== "COMPLETED")
3654
+ return stop(1, `! #${number} is closed as ${issue.stateReason ?? "not planned"}, but ${work}`, `gh issue reopen ${number} --repo ${slug}, then ${again}`);
3655
+ mutate(io, { op: "ReopenIssue", input: { issueId: issue.id } });
3656
+ if (!inCloud(io)) {
3657
+ const ctx = taskContext(io, slug);
3658
+ setStatus(io, ctx, ensureItem(io, ctx, issue).id, N.status.inProgress);
3659
+ }
3660
+ io.out(`+ #${number} reopened, ${STATUS} ${q(N.status.inProgress)}: ${work} — the task's merged PR isn't its finish`);
3661
+ return cmdTaskFinish(io, slug, number, { ...o, timeout: Math.max(0, left()) });
3662
+ }
3650
3663
  if (!closer || tailOver(io, slug, number))
3651
3664
  return io.out(`= #${number} is closed — nothing to finish`), 0;
3652
3665
  io.out(`○ #${number} is closed by the merge of PR #${closer.number}, the tail isn't over (no ${q(N.status.done)} with the actual) — going on`);
@@ -3656,8 +3669,9 @@ function cmdTaskFinish(io, slug, number, o) {
3656
3669
  throw new GhError(`task finish runs from a checkout of ${slug}: the current directory is not one`);
3657
3670
  const found = unlinkedPrs(io, slug, number);
3658
3671
  const prs = [...issue.prs, ...found.prs, ...found.batched].filter((p, k, all) => all.findIndex((x) => x.number === p.number) === k);
3659
- const merged = prs.find((p) => p.merged);
3660
- if (merged)
3672
+ const merged = lastMerged(prs);
3673
+ const pending = prs.some((p) => p.state === "OPEN") || merged && unmergedBranch(io, number, merged.base, merged.head);
3674
+ if (merged && !pending)
3661
3675
  return finishMerged(io, slug, number, issue.parent?.number ?? null, merged, { left, again, stop, outOfTime });
3662
3676
  const branch = git(io, io.cwd, "branch", "--show-current").stdout.trim();
3663
3677
  const open = prs.find((p) => p.state === "OPEN");
@@ -3734,6 +3748,36 @@ function cmdTaskFinish(io, slug, number, o) {
3734
3748
  const yes = locale_default.autoProject(io.cwd ?? process.cwd()) ? "" : "the owner's «yes» (the project is without auto) — then ";
3735
3749
  return stop(4, `✅ PR #${pr} is ready to merge`, `${yes}gh pr merge ${pr} --rebase — a separate call, no cd or pipeline (the owner's permission rule matches it); then ${again}${isBatchBranch(base) ? "" : " — in the background: it waits for the deploy"}`);
3736
3750
  }
3751
+ function lastMerged(prs) {
3752
+ return prs.filter((p) => p.merged).sort((a, b) => b.number - a.number)[0];
3753
+ }
3754
+ function unmergedBranch(io, number, base, mergedHead) {
3755
+ const branch = git(io, io.cwd, "branch", "--show-current").stdout.trim();
3756
+ if (!isTaskBranch(branch, number))
3757
+ return null;
3758
+ if (branch === mergedHead) {
3759
+ git(io, io.cwd, "fetch", "-q", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`);
3760
+ const past = git(io, io.cwd, "rev-list", "--count", `refs/remotes/origin/${branch}..HEAD`);
3761
+ if (past.status === 0)
3762
+ return Number(past.stdout.trim()) > 0 ? branch : null;
3763
+ }
3764
+ if (git(io, io.cwd, "fetch", "-q", "origin", `+refs/heads/${base}:refs/remotes/origin/${base}`).status !== 0)
3765
+ return null;
3766
+ const cherry = git(io, io.cwd, "cherry", `origin/${base}`, "HEAD");
3767
+ return cherry.status === 0 && cherry.stdout.split(`
3768
+ `).some((l) => l.startsWith("+")) ? branch : null;
3769
+ }
3770
+ function workPastMerge(io, slug, number, issue, closer) {
3771
+ const open = issue.prs.find((p) => p.state === "OPEN");
3772
+ if (open)
3773
+ return `its PR #${open.number} is open`;
3774
+ const current = git(io, io.cwd, "branch", "--show-current").stdout.trim();
3775
+ if (!isTaskBranch(current, number) || !checkoutOfRepo(io, originUrl(io), slug))
3776
+ return null;
3777
+ const base = closer?.base ?? unlinkedPrs(io, slug, number).base;
3778
+ const branch = unmergedBranch(io, number, base, closer?.head);
3779
+ return branch ? `branch ${branch} has commits that aren't in origin/${base}` : null;
3780
+ }
3737
3781
  function finishBase(io, slug, number, found) {
3738
3782
  const batch = handedPastBatch(io, slug, number) ? null : batchOf(io, slug);
3739
3783
  if (!batch)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@miroshnik/elves",
3
- "version": "2026.1107.0",
3
+ "version": "2026.1112.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": "406b4083596328d0ab347c72262d198c7ec45db0"
75
+ "gitHead": "782e3e75f81a1b20f952a6fa001a44f5de6b4ed5"
76
76
  }
@@ -691,7 +691,12 @@ or 3. Then the merge command, code 4: the merge stays a separate `gh pr merge
691
691
  into a batch — code 0, nothing more (the release does it); otherwise
692
692
  `ci-wait merged`, the refresh's mechanics and its prompt (code 4 — the
693
693
  subagent), and `task close` once its report is on the epic (no epic or no
694
- other open tasks — right away). Code 5 — out of time: the same command
694
+ other open tasks — right away). A task reopened after its merge (#813): an
695
+ open PR of the task or the checkout's task branch with commits not in the
696
+ base (`git cherry`; the merged PR's own branch — commits past its pushed
697
+ head) is the tail, not the merged PR — the latest merged PR is the one
698
+ awaited after the merge; closed with such work — reopened and «In progress»
699
+ (not planned — code 1 with `gh issue reopen`). Code 5 — out of time: the same command
695
700
  again. A session runs it in the background — once before the merge and once
696
701
  after; a subagent — `--timeout 240` (540 with the hour cache,
697
702
  `docs/pr-checks.md`), again on code 5. The separate commands stay for manual
@@ -641,6 +641,7 @@ const M: Record<string, [field: string, inputType: string, select: string]> = {
641
641
  RemoveBlockedBy: ["removeBlockedBy", "RemoveBlockedByInput", "issue { id }"],
642
642
  SetIssueField: ["setIssueFieldValue", "SetIssueFieldValueInput", "issue { id }"],
643
643
  CloseIssue: ["closeIssue", "CloseIssueInput", "issue { id state }"],
644
+ ReopenIssue: ["reopenIssue", "ReopenIssueInput", "issue { id state }"],
644
645
  UpdateIssue: ["updateIssue", "UpdateIssueInput", "issue { id }"],
645
646
  AddComment: ["addComment", "AddCommentInput", "subject { id }"],
646
647
  CreateRuleset: ["createRepositoryRuleset", "CreateRepositoryRulesetInput", "ruleset { id }"],
@@ -5029,7 +5030,19 @@ export function cmdTaskFinish(io: Io, slug: string, number: number, o: { timeout
5029
5030
  const issue = loadIssue(io, slug, number);
5030
5031
  if (issue.state !== "OPEN") {
5031
5032
  // «Closes #N» of the PR closes the task at the merge (#761): a closed issue isn't a finished tail — task close's marks are
5032
- const closer = issue.stateReason === "COMPLETED" ? (issue.prs.find((p) => p.merged && !isBatchBranch(p.base)) ?? null) : null;
5033
+ const closer = issue.stateReason === "COMPLETED" ? (lastMerged(issue.prs.filter((p) => !isBatchBranch(p.base))) ?? null) : null;
5034
+ // a task reopened after its merge (#813): its open PR or its branch's unmerged work is the tail, not the merged PR
5035
+ const work = workPastMerge(io, slug, number, issue, closer);
5036
+ if (work) {
5037
+ if (issue.stateReason !== "COMPLETED") return stop(1, `! #${number} is closed as ${issue.stateReason ?? "not planned"}, but ${work}`, `gh issue reopen ${number} --repo ${slug}, then ${again}`);
5038
+ mutate(io, { op: "ReopenIssue", input: { issueId: issue.id } });
5039
+ if (!inCloud(io)) {
5040
+ const ctx = taskContext(io, slug);
5041
+ setStatus(io, ctx, ensureItem(io, ctx, issue).id, N.status.inProgress);
5042
+ }
5043
+ io.out(`+ #${number} reopened, ${STATUS} ${q(N.status.inProgress)}: ${work} — the task's merged PR isn't its finish`);
5044
+ return cmdTaskFinish(io, slug, number, { ...o, timeout: Math.max(0, left()) });
5045
+ }
5033
5046
  if (!closer || tailOver(io, slug, number)) return io.out(`= #${number} is closed — nothing to finish`), 0;
5034
5047
  io.out(`○ #${number} is closed by the merge of PR #${closer.number}, the tail isn't over (no ${q(N.status.done)} with the actual) — going on`);
5035
5048
  return finishMerged(io, slug, number, issue.parent?.number ?? null, closer, { left, again, stop, outOfTime });
@@ -5037,8 +5050,11 @@ export function cmdTaskFinish(io: Io, slug: string, number: number, o: { timeout
5037
5050
  if (!checkoutOfRepo(io, originUrl(io), slug)) throw new GhError(`task finish runs from a checkout of ${slug}: the current directory is not one`);
5038
5051
  const found = unlinkedPrs(io, slug, number);
5039
5052
  const prs = [...issue.prs, ...found.prs, ...found.batched].filter((p, k, all) => all.findIndex((x) => x.number === p.number) === k);
5040
- const merged = prs.find((p) => p.merged);
5041
- if (merged) return finishMerged(io, slug, number, issue.parent?.number ?? null, merged, { left, again, stop, outOfTime });
5053
+ // the latest merged PR is the task's finish only without an open PR and without unmerged work on its branch (#813):
5054
+ // a task reopened after the merge goes on with its new branch — its push, its PR, its merge
5055
+ const merged = lastMerged(prs);
5056
+ const pending = prs.some((p) => p.state === "OPEN") || (merged && unmergedBranch(io, number, merged.base, merged.head));
5057
+ if (merged && !pending) return finishMerged(io, slug, number, issue.parent?.number ?? null, merged, { left, again, stop, outOfTime });
5042
5058
 
5043
5059
  const branch = git(io, io.cwd, "branch", "--show-current").stdout.trim();
5044
5060
  const open = prs.find((p) => p.state === "OPEN");
@@ -5103,6 +5119,43 @@ export function cmdTaskFinish(io: Io, slug: string, number: number, o: { timeout
5103
5119
  return stop(4, `✅ PR #${pr} is ready to merge`, `${yes}gh pr merge ${pr} --rebase — a separate call, no cd or pipeline (the owner's permission rule matches it); then ${again}${isBatchBranch(base) ? "" : " — in the background: it waits for the deploy"}`);
5104
5120
  }
5105
5121
 
5122
+ /** The task's latest merged PR — the highest number: a task reopened after a merge has several (#813). */
5123
+ function lastMerged<T extends { number: number; merged: boolean }>(prs: T[]): T | undefined {
5124
+ return prs.filter((p) => p.merged).sort((a, b) => b.number - a.number)[0];
5125
+ }
5126
+
5127
+ /**
5128
+ * The checkout's branch of the task with commits that aren't in `origin/<base>` by their changes (`git cherry`: a
5129
+ * rebase merge gives other SHAs) — the work of a task reopened after its merge (#813); none — null. The merged PR's own
5130
+ * branch — by the commits past its pushed head while it is on origin: a squash merge has no commit-for-commit match.
5131
+ */
5132
+ function unmergedBranch(io: Io, number: number, base: string, mergedHead?: string): string | null {
5133
+ const branch = git(io, io.cwd, "branch", "--show-current").stdout.trim();
5134
+ if (!isTaskBranch(branch, number)) return null;
5135
+ if (branch === mergedHead) {
5136
+ git(io, io.cwd, "fetch", "-q", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`);
5137
+ const past = git(io, io.cwd, "rev-list", "--count", `refs/remotes/origin/${branch}..HEAD`);
5138
+ if (past.status === 0) return Number(past.stdout.trim()) > 0 ? branch : null;
5139
+ }
5140
+ if (git(io, io.cwd, "fetch", "-q", "origin", `+refs/heads/${base}:refs/remotes/origin/${base}`).status !== 0) return null;
5141
+ const cherry = git(io, io.cwd, "cherry", `origin/${base}`, "HEAD");
5142
+ return cherry.status === 0 && cherry.stdout.split("\n").some((l) => l.startsWith("+")) ? branch : null;
5143
+ }
5144
+
5145
+ /**
5146
+ * What a closed task still has after its merged PR (#813): an open PR of the task, or the checkout's task branch with
5147
+ * work its base hasn't got. Nothing — null; the checkout isn't the repository's — only the PR counts.
5148
+ */
5149
+ function workPastMerge(io: Io, slug: string, number: number, issue: Issue, closer: Issue["prs"][number] | null): string | null {
5150
+ const open = issue.prs.find((p) => p.state === "OPEN");
5151
+ if (open) return `its PR #${open.number} is open`;
5152
+ const current = git(io, io.cwd, "branch", "--show-current").stdout.trim();
5153
+ if (!isTaskBranch(current, number) || !checkoutOfRepo(io, originUrl(io), slug)) return null;
5154
+ const base = closer?.base ?? unlinkedPrs(io, slug, number).base;
5155
+ const branch = unmergedBranch(io, number, base, closer?.head);
5156
+ return branch ? `branch ${branch} has commits that aren't in origin/${base}` : null;
5157
+ }
5158
+
5106
5159
  /**
5107
5160
  * The base of the task's new PR: the dispatcher's batch branch (#648); a task past the batch (#697) — the default branch,
5108
5161
  * as outside a batch; the batch released (#768: its release PR merged, or its branch gone from origin) — the default
@@ -57,7 +57,8 @@ The settings — `env.http` in the project's `.agents/elves.json`, a service →
57
57
  ```
58
58
 
59
59
  A service of `env.http` that isn't in the compose file — a `!` line, not an error. No `env.http` — no labels, no
60
- proxy, only published ports.
60
+ proxy, only published ports. `env.memoryMb` — what the stack needs, measured: a stack the Docker VM can't fit doesn't
61
+ come up (`reference.md`, "The Docker VM's memory").
61
62
 
62
63
  **The app's own address** — from the compose file: `up` and `e2e` give Compose's process the address of each
63
64
  `env.http` service in `TASK_ENV_<SERVICE>_URL` (the names the e2e command gets), and the compose file passes them to the app — a base URL,
@@ -80,9 +81,10 @@ variables live only in the environment of the script's Compose process — no `.
80
81
  goes into `build.args` the same way: Compose interpolates them too.
81
82
 
82
83
  **The override** — the proxy's labels for the `env.http` services (a database isn't published), on Compose's stdin,
83
- not a file; the script joins those services to the proxy's network itself, without their short name — inside the
84
- stack `http://storage:9000` always reaches the stack's own `storage`; `up` starts the proxy first if it isn't running
85
- — reference.md, "Override and compose files"; the labels — reference.md, "Labels of a task stack's service".
84
+ not a file; the script joins those services to the proxy's network itself, without their short name; still, the short
85
+ name of an `env.http` service isn't guaranteed inside the stack — address it by the container name
86
+ `${COMPOSE_PROJECT_NAME}-<service>-1` (`check` warns with `!`); `up` starts the proxy first if it isn't running —
87
+ reference.md, "Override and compose files"; the labels — reference.md, "Labels of a task stack's service".
86
88
 
87
89
  **e2e** — `<project>-<N>-e2e`, apart from the dev stack of the task: `down --volumes` and `up` again on every run, so
88
90
  the run starts on clean volumes; then the command runs on the host (the current directory, the script's environment)
@@ -24,6 +24,15 @@ chance. Connected by hand, a container is named in the proxy's network only by i
24
24
  `<stack>-<service>-<n>`, and the short name stays in the stack's own networks. The connect goes between creating and
25
25
  starting: Traefik sees the network on the start event, and the next `up` doesn't recreate the container.
26
26
 
27
+ **Inside the stack the short name of an `env.http` service isn't guaranteed** (#806). Docker looks a name up over the
28
+ container's networks in the order of their names, and `elves-proxy` comes before `<stack>_<network>`: a short name that
29
+ got into the proxy's network overrides the stack's own. It happened with two stacks up — a name from stack A led to a
30
+ container of stack B; how the name got there isn't established, and repeating the steps gives no alias. Address such a
31
+ service by the container name `${COMPOSE_PROJECT_NAME}-<service>-1`, one on the machine. `task-env check` warns with a
32
+ `!` line (the exit code doesn't change, the project's `check` prints it too) when a URL or `host:port` in a service's
33
+ variables, `command`, `entrypoint`, a bind-mounted file or `configs` names an `env.http` service by its short name; a
34
+ mounted directory isn't read — it is code.
35
+
27
36
  ## Taking a task's stacks down
28
37
 
29
38
  **down** — `down --volumes --remove-orphans` of `<project>-<N>` and `<project>-<N>-e2e` by the Compose project, from
@@ -86,12 +95,47 @@ stack shop-42: not up — container shop-42-api-1 exited (3)
86
95
  | Error: connect ECONNREFUSED db:5432
87
96
  ```
88
97
 
98
+ ## The Docker VM's memory
99
+
100
+ Containers' limits don't protect the VM: the sum of several stacks' limits is far above it. So `up` and `e2e`, before
101
+ anything starts and inside the machine queue, compare what the stack needs with the VM's `MemAvailable` plus
102
+ `SwapFree` (`/proc/meminfo` from a one-off container of the proxy's image):
103
+
104
+ ```json
105
+ { "env": { "memoryMb": 6144 } }
106
+ ```
107
+
108
+ `env.memoryMb` in `.agents/elves.json` — MiB, a number from the project's measurement of a full stack under load; not
109
+ the sum of `mem_limit`: that upper bound is far above real use, and a full stack would never come up. No field — a
110
+ reserve of 1024 MiB. A stack with a running container is in the VM's numbers itself and isn't checked.
111
+
112
+ ```
113
+ stack shop-42: not started — the Docker VM lacks memory: needs 6144 MiB, has 2560 MiB (available 2048 + free swap 512); stacks on it: shop-41, shop-43-e2e — take down one nobody needs: task-env down <N>
114
+ ○ Docker VM memory not checked — <Docker's reason>
115
+ ```
116
+
117
+ The first — code 2, nothing is started; the second — the bring-up goes on.
118
+
119
+ **A container killed: the VM's memory or its own limit.** From outside both look alike: `docker inspect` gives
120
+ `OOMKilled: true`, exit code 137, and it reads as a code failure or a low limit. The difference is inside:
121
+
122
+ | | the container's `memory.events` | VM kernel log (`dmesg`) | what to do |
123
+ |---|---|---|---|
124
+ | its own limit | `oom` > 0, `oom_kill` > 0 | `constraint=CONSTRAINT_MEMCG`, `oom_memcg=…` | raise the limit or fix the code |
125
+ | the VM's memory | `oom` 0, `oom_kill` 1 | `constraint=CONSTRAINT_NONE`, `global_oom` | take down stacks, enlarge the VM or raise `env.memoryMb` |
126
+
127
+ `memory.events` — `docker exec <container> cat /sys/fs/cgroup/memory.events` in a container still running (a dead
128
+ one's counters are gone: read the kernel log). The kernel log of Docker Desktop's VM — `docker run --rm --privileged
129
+ --entrypoint dmesg traefik:v3.7`. On a VM OOM the victim is the largest process with `oom_score_adj` 0, usually a JVM
130
+ or a database, and not necessarily of the stack that gave the load: the task that sees the failure may not be its
131
+ cause.
132
+
89
133
  ## Exit codes
90
134
 
91
135
  `up` — 0 up, 1 not up, 2 not tried (no compose file, broken settings, Docker unavailable, `docker compose config`
92
- fails); `e2e` — the command's, otherwise as `up`; `down` and `prune` — 0 (an image a container uses, left, too), 2
136
+ fails, the Docker VM can't fit the stack); `e2e` — the command's, otherwise as `up`; `down` and `prune` — 0 (an image a container uses, left, too), 2
93
137
  if a stack or an image isn't removed, Docker is unavailable or (`prune`) a task's state isn't checked; `proxy status` — 0 running, 1 not running (the start command),
94
- 2 no Docker; `check` — 0 the rules hold or no compose file, 1 violations, 2 not checked.
138
+ 2 no Docker; `check` — 0 the rules hold or no compose file (`!` lines too), 1 violations, 2 not checked.
95
139
 
96
140
  ## The proxy — container, routes, API
97
141
 
@@ -43,7 +43,7 @@
43
43
  * unsandboxed call — an `excludedCommands` entry for it doesn't take it out (SKILL.md, «Docker and the sandbox»).
44
44
  */
45
45
  import { spawnSync } from "node:child_process";
46
- import { appendFileSync, existsSync, readFileSync } from "node:fs";
46
+ import { appendFileSync, existsSync, readFileSync, statSync } from "node:fs";
47
47
  import path from "node:path";
48
48
  import { fileURLToPath } from "node:url";
49
49
 
@@ -61,9 +61,11 @@ Brings the task's stack up — the Compose project <project>-<N> by the branch <
61
61
  number (in the middle of a rebase — the branch being rebased; a linked worktree without a task branch — the task of
62
62
  ELVES_TASK=<N>, without it refused: give N) — and prints its addresses: env.http services of .agents/elves.json through the proxy, published ports on
63
63
  127.0.0.1; the HTTP addresses go to the compose file's interpolation in TASK_ENV_<SERVICE>_URL; --profile — Compose
64
- profiles. The bring-up takes a place in the machine queue (slot) until the containers are healthy. Code 0 — up, 1 — a
65
- service failed (its state and log), 2 — not tried; not up — the reason is appended to the file of
66
- ELVES_TASK_ENV_FAILED, if given (pr premerge of the github skill: «couldn't check», not a red check).
64
+ profiles. The bring-up takes a place in the machine queue (slot) until the containers are healthy. A stack not running
65
+ yet that the Docker VM can't fit — env.memoryMb of .agents/elves.json, without it a reserve, against its available
66
+ memory and free swap — isn't brought up: the numbers and the stacks on the VM. Code 0 — up, 1 — a service failed (its
67
+ state and log), 2 — not tried; not up — the reason is appended to the file of ELVES_TASK_ENV_FAILED, if given (pr
68
+ premerge of the github skill: «couldn't check», not a red check).
67
69
 
68
70
  Examples:
69
71
  task-env up
@@ -74,7 +76,7 @@ Examples:
74
76
  The e2e stack <project>-<N>-e2e anew with clean volumes (its own addresses in the interpolation), then the command with
75
77
  its addresses in TASK_ENV_PROJECT, TASK_ENV_<SERVICE>_URL, TASK_ENV_<SERVICE>_<PORT>; the exit code is the command's; the
76
78
  stack stays until the next run. The bring-up takes a place in the machine queue (slot) until the containers are healthy,
77
- the command runs outside it.
79
+ the command runs outside it; the Docker VM's memory is checked as in up.
78
80
 
79
81
  Examples:
80
82
  task-env e2e -- npx playwright test
@@ -101,8 +103,10 @@ Examples:
101
103
 
102
104
  Holds the compose file in <dir> (default — the current directory) to the task isolation rules: no container_name, no
103
105
  fixed host port, volumes and networks without name and external, code by paths relative to the compose file; one ❌ line
104
- per violation. Code 0 — the rules hold or there is no compose file, 1 — violations, 2 — not checked (no docker compose,
105
- the config doesn't parse).
106
+ per violation. A ! line — a service addresses an env.http service by its short name (a variable, command, entrypoint, a
107
+ mounted config): that name isn't guaranteed to stay in the stack, the container name \${COMPOSE_PROJECT_NAME}-<service>-1
108
+ is; the code doesn't change. Code 0 — the rules hold or there is no compose file, 1 — violations, 2 — not checked (no
109
+ docker compose, the config doesn't parse).
106
110
 
107
111
  Examples:
108
112
  task-env check
@@ -387,6 +391,8 @@ export const COMPOSE_FILES = ["compose.yaml", "compose.yml", "docker-compose.yam
387
391
  const MACHINE = /^\/(?:var\/run|run|etc|dev|proc|sys)(?:\/|$)/;
388
392
  /** `docker compose config` reads a few files — longer than this is a hang, not work. */
389
393
  const CONFIG_TIMEOUT = 20_000;
394
+ /** A mounted file bigger than this is data, not a config: `check` doesn't read it for addresses. */
395
+ const MOUNTED_LIMIT = 1024 * 1024;
390
396
 
391
397
  interface Port {
392
398
  target: number;
@@ -404,6 +410,10 @@ interface Service {
404
410
  volumes?: Mount[];
405
411
  build?: { context?: string; dockerfile?: string };
406
412
  networks?: Record<string, unknown>;
413
+ environment?: Record<string, string | null>;
414
+ command?: string[] | null;
415
+ entrypoint?: string[] | null;
416
+ configs?: { source: string }[];
407
417
  }
408
418
  interface Resource {
409
419
  name?: string;
@@ -415,6 +425,7 @@ interface Config {
415
425
  services?: Record<string, Service>;
416
426
  volumes?: Record<string, Resource>;
417
427
  networks?: Record<string, Resource>;
428
+ configs?: Record<string, { file?: string; content?: string }>;
418
429
  }
419
430
 
420
431
  const absolute = (p: string) => p.startsWith("/") || p === "~" || p.startsWith("~/");
@@ -460,6 +471,63 @@ function violations(config: Config, file: string): string[] {
460
471
  return out;
461
472
  }
462
473
 
474
+ /**
475
+ * An address that names `service` by its short name: the host of a URL or `host:port`. A longer name doesn't count —
476
+ * `<stack>-web-1`, `web.42.shop.localhost`, `webapp`, and neither does the last segment of a path or an image
477
+ * (`registry.test/web:3000`).
478
+ */
479
+ function shortAddress(service: string): RegExp {
480
+ const name = service.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
481
+ return new RegExp(`[a-z][a-z0-9+.-]*://(?:[^/\\s@]*@)?${name}(?![\\w.-])|(?<![\\w./-])${name}:\\d{1,5}(?!\\d)`, "i");
482
+ }
483
+
484
+ /** The text of a mounted file relative to the compose file; a directory (code), a missing or an oversized file — nothing. */
485
+ function mountedText(dir: string, source: string): string {
486
+ try {
487
+ const file = path.resolve(dir, source);
488
+ const stat = statSync(file);
489
+ return stat.isFile() && stat.size <= MOUNTED_LIMIT ? readFileSync(file, "utf8") : "";
490
+ } catch {
491
+ return "";
492
+ }
493
+ }
494
+
495
+ /**
496
+ * `!` lines (#806): a service of the stack addresses an `env.http` service by its short name. Docker looks a name up over
497
+ * the container's networks in the order of their names, the proxy's network comes before `<stack>_<network>`, so a short
498
+ * name that got into the proxy's network — it happened, how is not established — leads to another task's stack; the
499
+ * container's name is one on the machine. A warning, not a violation: short names are the norm in compose files, and
500
+ * normally the name stays the stack's. Environment (with `env_file`, Compose merged it), `command`, `entrypoint`, bind
501
+ * mounted files and `configs`.
502
+ */
503
+ function shortNames(config: Config, http: Record<string, number>, dir: string, file: string): string[] {
504
+ const targets = Object.keys(http).filter((s) => config.services?.[s]);
505
+ const out: string[] = [];
506
+ for (const [name, s] of Object.entries(config.services ?? {})) {
507
+ const places: [string, string][] = [
508
+ ...Object.entries(s.environment ?? {}).map(([k, v]): [string, string] => [`environment ${k}`, v ?? ""]),
509
+ ["command", (s.command ?? []).join(" ")],
510
+ ["entrypoint", (s.entrypoint ?? []).join(" ")],
511
+ ];
512
+ for (const v of s.volumes ?? []) {
513
+ if (v.type === "bind" && v.source && !absolute(v.source)) places.push([`mounted file ${v.source}`, mountedText(dir, v.source)]);
514
+ }
515
+ for (const c of s.configs ?? []) {
516
+ const { file: source, content } = config.configs?.[c.source] ?? {};
517
+ if (source) places.push([`mounted file ${source}`, mountedText(dir, source)]);
518
+ if (content) places.push([`config ${c.source}`, content]);
519
+ }
520
+ for (const [where, text] of places) {
521
+ for (const target of targets) {
522
+ if (shortAddress(target).test(text)) {
523
+ out.push(`! ${file}: service ${name} — ${where}: the short name ${target} of an env.http service may reach another task's stack; use the container name \${COMPOSE_PROJECT_NAME}-${target}-1`);
524
+ }
525
+ }
526
+ }
527
+ }
528
+ return out;
529
+ }
530
+
463
531
  /** `check`: the exit code; all lines go to stdout — `check` of the installer reads them from there. */
464
532
  function check(dir: string): number {
465
533
  const file = COMPOSE_FILES.find((f) => existsSync(path.join(dir, f)));
@@ -477,9 +545,11 @@ function check(dir: string): number {
477
545
  return notChecked("docker compose config printed no JSON");
478
546
  }
479
547
  const lines = violations(config, file);
480
- if (!lines.length) return console.log(`${file}: the task isolation rules hold`), 0;
481
- console.log(lines.join("\n"));
482
- return 1;
548
+ // the settings are the repository's, the compose file may be in a subdirectory of it
549
+ const http = httpServices(git(dir, "rev-parse", "--show-toplevel") || dir);
550
+ const notes = typeof http === "string" ? [`○ ${http} — short names of env.http services not checked`] : shortNames(config, http, dir, file);
551
+ console.log([...lines, ...notes, ...(lines.length ? [] : [`${file}: the task isolation rules hold`])].join("\n"));
552
+ return lines.length ? 1 : 0;
483
553
  }
484
554
 
485
555
  // ----------------------------------------------------------------------------
@@ -644,6 +714,17 @@ export function httpServices(root: string): Record<string, number> | string {
644
714
  return Object.values(ports).every((p) => Number.isInteger(p) && (p as number) > 0 && (p as number) < 65536) ? (ports as Record<string, number>) : bad;
645
715
  }
646
716
 
717
+ /**
718
+ * What the project's stack needs of the Docker VM, MiB — `env.memoryMb` of the project's settings, a number from the
719
+ * project's measurement (#809, question 1); no field — undefined, a broken one — the reason.
720
+ */
721
+ export function stackMemory(root: string): number | undefined | string {
722
+ const { file, fields } = manifestOf(root);
723
+ const memory = (fields.env as { memoryMb?: unknown } | null | undefined)?.memoryMb;
724
+ if (memory === undefined) return undefined;
725
+ return Number.isInteger(memory) && (memory as number) > 0 ? (memory as number) : `env.memoryMb of ${file}: what the stack needs of the Docker VM in MiB expected, a positive integer like 6144`;
726
+ }
727
+
647
728
  /** Where the task's stack lives: the worktree's root, its compose files, the project's name, the task and HTTP services. */
648
729
  interface Project {
649
730
  root: string;
@@ -652,6 +733,8 @@ interface Project {
652
733
  name: string;
653
734
  task: number | undefined;
654
735
  http: Record<string, number>;
736
+ /** `env.memoryMb`: what the stack needs of the Docker VM, MiB. */
737
+ memoryMb: number | undefined;
655
738
  }
656
739
 
657
740
  function projectOf(cwd: string, task?: number): Project | string {
@@ -661,8 +744,10 @@ function projectOf(cwd: string, task?: number): Project | string {
661
744
  const extra = OVERRIDE_FILES.find((f) => existsSync(path.join(root, f)));
662
745
  const http = httpServices(root);
663
746
  if (typeof http === "string") return http;
747
+ const memoryMb = stackMemory(root);
748
+ if (typeof memoryMb === "string") return memoryMb;
664
749
  const files = [file, ...(extra ? [extra] : [])].flatMap((f) => ["-f", f]);
665
- return { root, files, name: projectName(root), task: task ?? taskBranch(currentBranch(root))?.issue, http };
750
+ return { root, files, name: projectName(root), task: task ?? taskBranch(currentBranch(root))?.issue, http, memoryMb };
666
751
  }
667
752
 
668
753
  /** `docker compose` in cwd; vars — over the script's environment: Compose takes them into interpolation. */
@@ -684,7 +769,8 @@ const urlVars = (project: Project, stack: Stack, env: NodeJS.ProcessEnv) =>
684
769
  * services of the settings, nothing to the others (a database isn't published). The proxy's network isn't in it:
685
770
  * Compose gives a service in each of its networks the alias of its short name, and in the proxy's network same-named
686
771
  * services of two stacks would answer one name — a neighbour inside the stack (`http://storage:9000`) would reach
687
- * another stack by chance (#700); `upStack` joins the network itself (`joinProxy`). The override goes to Compose's
772
+ * another stack by chance (#700); `upStack` joins the network itself (`joinProxy`), which doesn't guarantee the short
773
+ * name either (#806, `shortNames`). The override goes to Compose's
688
774
  * stdin (`-f -`), not into a file: a `compose.override.yaml` would be the project's. No HTTP service in the compose
689
775
  * file — no override.
690
776
  */
@@ -793,11 +879,57 @@ function addressesOf(project: Project, stack: Stack, env: NodeJS.ProcessEnv): Ad
793
879
  return out;
794
880
  }
795
881
 
882
+ /** What a stack without `env.memoryMb` must find free on the Docker VM, MiB: below it nothing starts safely (#809). */
883
+ const VM_RESERVE_MB = 1024;
884
+ /** `docker run` of a present image takes under a second; the first run pulls it — longer than this, not checked. */
885
+ const VM_TIMEOUT = 30_000;
886
+
887
+ /**
888
+ * The Docker VM's memory in MiB: `/proc/meminfo` from a one-off container isn't namespaced, it is the VM's (the host's
889
+ * on Linux); `docker info` knows only the total. In the proxy's image — it is on the machine already, the version lives
890
+ * in its compose file. Not read — the reason.
891
+ */
892
+ function vmMemory(env: NodeJS.ProcessEnv): { availableMb: number; swapFreeMb: number } | string {
893
+ const image = /^\s*image:\s*(\S+)/m.exec(readFileSync(PROXY_FILE, "utf8"))?.[1];
894
+ if (!image) return `no image in ${PROXY_FILE}`;
895
+ const r = spawnSync("docker", ["run", "--rm", "--network", "none", "--entrypoint", "cat", image, "/proc/meminfo"], { encoding: "utf8", env, timeout: VM_TIMEOUT });
896
+ if (r.error || r.status !== 0) return why(r);
897
+ const mib = (field: string) => Math.floor(Number(new RegExp(`^${field}:\\s+(\\d+) kB`, "m").exec(r.stdout)?.[1] ?? NaN) / 1024);
898
+ const [availableMb, swapFreeMb] = [mib("MemAvailable"), mib("SwapFree")] as [number, number];
899
+ return Number.isNaN(availableMb + swapFreeMb) ? "no MemAvailable or SwapFree in /proc/meminfo" : { availableMb, swapFreeMb };
900
+ }
901
+
902
+ /** The Compose stacks running on the VM, without the proxy: names sorted; not listed — the reason. */
903
+ function vmStacks(env: NodeJS.ProcessEnv): string {
904
+ const r = spawnSync("docker", ["ps", "--filter", `label=${PROJECT_LABEL}`, "--format", `{{.Label "${PROJECT_LABEL}"}}`], { encoding: "utf8", env, timeout: CONFIG_TIMEOUT });
905
+ if (r.error || r.status !== 0) return `not listed — ${why(r)}`;
906
+ return [...new Set(r.stdout.split("\n").filter((s) => s && s !== proxyName(env)))].sort().join(", ") || "none";
907
+ }
908
+
909
+ /**
910
+ * The gate before a stack comes up (#809): containers' limits don't protect the VM — the sum of several stacks' limits
911
+ * is far above it, and the kernel kills the largest process, not necessarily of the stack that gave the load. Available
912
+ * memory plus free swap against what the stack needs: `env.memoryMb`, without it — the reserve. A stack already running
913
+ * is in the VM's numbers itself, so it isn't checked. The refusal, the `○` line of a VM that didn't answer (the bring-up
914
+ * goes on: the gate protects neighbours, it isn't a precondition) or nothing.
915
+ */
916
+ function vmGate(project: Project, stack: Stack, env: NodeJS.ProcessEnv): { refusal?: string; note?: string } {
917
+ if (containers(stack.name).some((c) => c.State === "running")) return {};
918
+ const vm = vmMemory(env);
919
+ if (typeof vm === "string") return { note: `○ Docker VM memory not checked — ${vm}${hint(vm, env)}` };
920
+ const need = project.memoryMb ?? VM_RESERVE_MB;
921
+ const has = vm.availableMb + vm.swapFreeMb;
922
+ if (has >= need) return {};
923
+ const source = project.memoryMb === undefined ? " (the reserve; env.memoryMb of .agents/elves.json sets what the stack needs)" : "";
924
+ return { refusal: `stack ${stack.name}: not started — the Docker VM lacks memory: needs ${need} MiB${source}, has ${has} MiB (available ${vm.availableMb} + free swap ${vm.swapFreeMb}); stacks on it: ${vmStacks(env)} — take down one nobody needs: task-env down <N>` };
925
+ }
926
+
796
927
  /**
797
928
  * Brings the stack up: the project's compose files plus the override, `up --wait` with a build — the stack runs the
798
- * worktree's code, not an image from another task's run. The proxy goes up first when the override joins its network
799
- * and it isn't running (#393, question 8); a running one isn't touched. Both Compose calls get the stack's addresses
800
- * for interpolation — `config` too: a required `${TASK_ENV_WEB_URL:?…}` would fail it.
929
+ * worktree's code, not an image from another task's run. Before anything starts — the VM's memory (`vmGate`), inside
930
+ * the machine queue: two bring-ups don't count the same free memory. The proxy goes up first when the override joins its
931
+ * network and it isn't running (#393, question 8); a running one isn't touched. Both Compose calls get the stack's
932
+ * addresses for interpolation — `config` too: a required `${TASK_ENV_WEB_URL:?…}` would fail it.
801
933
  */
802
934
  function upStack(project: Project, stack: Stack, profiles: string[], env: NodeJS.ProcessEnv): { code: number; lines: string[] } {
803
935
  const vars = urlVars(project, stack, env);
@@ -807,6 +939,9 @@ function upStack(project: Project, stack: Stack, profiles: string[], env: NodeJS
807
939
  const lines = Object.keys(project.http)
808
940
  .filter((s) => !parsed.services?.[s])
809
941
  .map((s) => `! env.http: service ${s} isn't in the compose file — no address for it`);
942
+ const gate = vmGate(project, stack, env);
943
+ if (gate.refusal) return { code: 2, lines: [...lines, gate.refusal] };
944
+ if (gate.note) lines.push(gate.note);
810
945
  const override = overrideOf(parsed, project.http, stack, proxyName(env));
811
946
  if (override) {
812
947
  const running = proxyRunning(env);