Merge pull request 'Cap the memory of each container a heavy command makes under run-heavy at its slot's share' (#373) from item-227 into main

This commit was merged in pull request #373.
This commit is contained in:
2026-10-24 11:54:30 +02:00
20 changed files with 352 additions and 56 deletions
+2
View File
@@ -71,6 +71,8 @@
!bin/run-heavy
!bin/run_heavy/
!bin/run_heavy/*.py
!bin/run_heavy/path_entry/
!bin/run_heavy/path_entry/docker
!bin/score-outcomes
!bin/score_outcomes/
!bin/score_outcomes/*.py
+1 -1
View File
@@ -16,7 +16,7 @@ Decisions live in `docs/decisions.md`:
- loop-claude: one session per project, its id derived from the checkout's path relative to `~/code`, or to `/` outside it
- loop-claude: the archive keeps the raw transcript, and a failed archive stops the loop
- machine load: a heavy command waits for one of the machine's heavy slots, one for every 4 CPUs, which every session shares, and loop-claude starts a worker only while at least a quarter of the machine's memory is available
- machine load: every container a session starts has a memory limit and a swap limit as large as its work needs, which rule-hook's `docker-run-memory` enforces on `docker run` and `docker create`, and no daemon-wide cap limits all containers together
- machine load: every container a session starts has a memory limit and a swap limit as large as its work needs; rule-hook's `docker-run-memory` blocks a `docker run` or `docker create` without them outside run-heavy, under which a container that lacks them gets the slot's share of three quarters of the memory; and no daemon-wide cap limits all containers together
- principles: about seven things per level, four or five where they act on each other, more where a reader finds them by name; crossing a limit asks for a grouping or a recorded reason
- reading cost and `score-outcomes`: each waits for 10 finished chunks before it shows a median
- reading cost: a rise is the last 5 chunks' median above the 5 before them, and files or refreshes one plan item
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- On Linux, `run-heavy` now caps the memory of a container its command makes with `docker run` or `docker create`. A container that sets no limit gets a memory limit and a swap limit, both the slot's share: three quarters of the machine's memory, split across the heavy slots. A container that sets one of the two limits keeps it, and gets the other as large. This covers containers a project's own scripts start, which rule-hook can't see. A `docker compose` service, and a docker named by its full path, get no cap. rule-hook's `docker-run-memory` now lets a `docker run` under run-heavy pass.
- rule-hook has a new rule, `docker-run-memory`. It blocks a `docker run` or `docker create` that lacks a memory limit or a swap limit, such as `--memory 4g --memory-swap 4g`, sized to what the work needs. `--memory-swap -1`, unlimited swap, counts as none. `CLAUDE.md` asks for the same limits on a container a script or a compose file starts, which rule-hook can't see. rule-hook's `run-heavy` rule also now reads docker's `--tlscacert`, `--tlscert`, `--tlskey` and buildx's `--builder` as options that take a value, and reads `docker container run` as a run: `docker --tlscacert ca.pem build .` was not blocked outside run-heavy before.
- Reviewers now mark a 🔴 or 🟡 `[misread]` where it arose because the implementer misread code that had already shipped. A round's commit title now counts the marked findings, as in `Answer stability round 1: 1 🔴, 2 🟡 (1 misread); …`, and rule-hook's `round-title-counts` blocks a round title without that count. `score-outcomes` shows the count on each finished item, and lists it after the medians for each chunk whose round titles carry it, newest first. A chunk whose round titles predate this change reads as unknown.
- Sessions running at once no longer starve the machine. A new tool, `run-heavy <command>`, runs a heavy command, such as a full gate, mutation tests, an e2e run or a `docker build`, once it holds one of the machine's heavy slots: one per 4 CPUs, shared by every session. `CLAUDE.md` has every session run its heavy commands under it, and rule-hook blocks a `docker build` or a mutation run outside it. loop-claude now waits to start a worker while less than a quarter of the machine's memory is available.
+1 -1
View File
@@ -66,7 +66,7 @@ The rules only reviewers apply, for quality, comments, READMEs and prose, live i
- Run a project's language runtime, package manager, and task runner through its container/tooling setup, never directly on the host unless a decision puts them there. Example: `docker compose run --rm app <tool> …`.
- Tear down test containers after a run.
- Give every container you start a memory limit and a swap limit, as large as its work needs: `--memory 4g --memory-swap 4g` on `docker run`, or `mem_limit` and `memswap_limit` in a compose file, scripts included. rule-hook checks only the `docker run` and `docker create` in your Bash commands.
- A heavy command loads the machine for minutes: a full gate, mutation tests, an e2e run, a `docker build`. Run each one under `~/.claude/bin/run-heavy`, as in `~/.claude/bin/run-heavy ./ci.sh`. run-heavy waits for one of the heavy slots that every session on the machine shares. Run it in the background, since the wait can outlast the Bash tool's timeout.
- A heavy command loads the machine for minutes: a full gate, mutation tests, an e2e run, a `docker build`. Run each one under `~/.claude/bin/run-heavy`, as in `~/.claude/bin/run-heavy ./ci.sh`. run-heavy waits for one of the heavy slots that every session on the machine shares. It also caps each container the command makes at the slot's share of memory, where the container sets no limits; give a container that needs more its own. Run it in the background, since the wait can outlast the Bash tool's timeout.
- Delegate a task to a subagent only when you need just its conclusion: a search or read across many files, or work independent enough to run in parallel. Keep edits, and whatever you must check line by line, in your own thread: you would read a delegated diff again to check it. Score the task's L as for a `todo.md` item; a task that changes no file, such as a search, is L 1. `<model>` below is the project's model id, such as `claude-opus-5-5`: the one loop-claude's prompt names as the project's, or else your own. Launch the subagent with the model and effort of the first case that fits:
1. A reviewer, a comprehension seat or the security pass: those loop-claude's prompt gives it. Given none, pass no model or effort, so it runs on your model.
2. An escalated task, below: the rung loop-claude's prompt names for escalation, or case 3's rung where the subagent files or scores `todo.md` items and that rung is higher.
+2 -2
View File
@@ -104,7 +104,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `reading-cost [--reset] [record]` appends a figure for each chunk `loop-claude` finished to a project's `docs/reading-cost.md`, and says whether the figures rise; `reading-cost --help` states the measure.
- `review-replay <pass> <model>` replays a review pass's archived rounds from the projects run on the model, on the code each reviewed, and prints the lowest rung below the project's that, like each rung above it, finds every 🔴 and 🟡 the project's rung finds again; `review-replay --help` states the replay. Each replayed reviewer skips every permission prompt, stability-reviewer has Bash, and an archived prompt may name paths on the host.
- `rule-hook [overrides]` blocks a tool call that breaks a rule a program can check, unless the call overrides the rule; `settings.json` → `hooks` runs it before each Bash, Edit, MultiEdit, Write and Agent call, and `rule-hook --help` states the rules and the override.
- `run-heavy <command>` runs a heavy command once it holds one of the machine's heavy slots, one per 4 CPUs, which every session shares; `run-heavy --help` states the slots.
- `run-heavy <command>` runs a heavy command once it holds one of the machine's heavy slots, one per 4 CPUs, which every session shares; `run-heavy --help` states the slots, and the memory cap it gives a container that sets no limit.
- `score-outcomes [L E I S]` lists the finished items whose guessed scores sit nearest the given ones, and the shipped items the project's `docs/score-anchors.md` names for each level of L, E and I, each with what its chunk measured; then the median outcome at each guessed R and S, and how well L, E and I each order the chunks by review rounds and 🔴 findings; then each chunk's 🔴 and 🟡 findings with how many a reviewer marked `[misread]`, code health's counter-signal; `score-outcomes --help` states the measures.
- `settings_filter.py` is git's clean filter for `settings.json`: it drops `"model"` and sorts the keys. `.gitattributes` sets the filter `settings` on `settings.json`, and Install's `git config` line makes this script that filter.
- `statusline.py` renders Claude Code's status line; `settings.json` → `statusLine` runs it.
@@ -125,7 +125,7 @@ pytest_add_cli_args=-k
Then, in the copy: `uvx --with pytest 'mutmut>=3,<4' run && uvx --with pytest 'mutmut>=3,<4' results`, and `uvx --with pytest 'mutmut>=3,<4' show <mutant>` to see a mutant's change. The config keys are mutmut 3's.
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests; `rank_todo.py`, `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them, `rule_hook` imports `rank_todo.py`'s check, `larv_review` imports `rank_todo.py`'s ranking, `score_outcomes` imports `reading_cost`'s record path, `judge_replay` imports `loop_claude`'s judge, and `loop_claude` runs `chunk-preflight` as a process of its own. `judge_replay` and `review_replay` share `rung_replay/`: the rung search, the argument reader, the candidate rungs and the exits. `rung_replay/` reads `loop_claude`'s retry count and models file. `docker_command.py` reads a docker command's subcommand and memory limits for `rule_hook`, and sits at the root so `run_heavy` can read them too. The other non-test modules at `bin/`'s root, `claude_code/` and `transcript_archive/` serve more than one tool; `model_routing/` holds the routing ladder, which loop-claude, `rule_hook`, both replay tools and `subagent-rung` read. `routing_figures/` measures loop-claude's archive for loop-claude's routing calls. `machine_load/` takes the machine's heavy slots, its shared lock files, for `run_heavy`, and reads the memory share that loop-claude waits for. `test_env.py` serves the tests, and `repo_checks/` tests the repo itself.
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests; `rank_todo.py`, `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them, `rule_hook` imports `rank_todo.py`'s check, `larv_review` imports `rank_todo.py`'s ranking, `score_outcomes` imports `reading_cost`'s record path, `judge_replay` imports `loop_claude`'s judge, and `loop_claude` runs `chunk-preflight` as a process of its own. `judge_replay` and `review_replay` share `rung_replay/`: the rung search, the argument reader, the candidate rungs and the exits. `rung_replay/` reads `loop_claude`'s retry count and models file. The other non-test modules at `bin/`'s root, `claude_code/` and `transcript_archive/` serve more than one tool; `model_routing/` holds the routing ladder, which loop-claude, `rule_hook`, both replay tools and `subagent-rung` read. `routing_figures/` measures loop-claude's archive for loop-claude's routing calls. `machine_load/` takes the machine's heavy slots, its shared lock files, for `run_heavy`, and reads the memory share that loop-claude waits for. `test_env.py` serves the tests, and `repo_checks/` tests the repo itself.
## Tracking a new file
+1 -1
View File
@@ -13,7 +13,7 @@ You are an elite stability-focused code reviewer with deep expertise in defensiv
2. **Read every file under `~/.claude/principles/`**, the shared principles, and `~/.claude/skills/larv-review/standards/quality.md`. These are mandatory org guidelines; all code MUST comply with each that applies. A file's `Applies to` line says what it covers; one without the line covers every change. Re-read each time — they change. Flag violations prominently.
3. **Read README.md, AGENTS.md and `docs/decisions.md`** in the current project for project-specific conventions, build instructions, tooling, and the accepted trade-offs a reviewer should honor rather than re-flag. Note the documented test, lint, and static-analysis commands — you will run them.
4. **Verify, don't just read.** Run the test suite and static analysis/linters through the project's container tooling, unless a decision puts them on the host; tear down test containers afterwards. Run the full suite under `~/.claude/bin/run-heavy`. Run it in the background or with the Bash tool's longest timeout: that timeout includes the wait for a slot. A full-suite run catches broken callers that diff-reading misses. When a suspected bug is cheap to confirm, reproduce it — a scratch script, a targeted test run — before reporting it. Make scratch work with Bash, since Write is for your report alone. Put it in a directory you create for this run, and delete it when done; delete nothing else, since a directory the prompt names may hold other agents' files. Leave the working tree exactly as you found it. Anything you could not run goes in Coverage & Verification, never silently skipped.
5. **Mutation-test the changed lines.** Run the project's documented mutation command, or else a widely deployed mutation tool for the language: cargo-mutants for Rust, Infection for PHP, mutmut for Python, Stryker for JavaScript and TypeScript. Limit it to the lines the change adds or modifies, through the tool's own option where it has one (cargo-mutants `--in-diff <diff file>`, Infection `--git-diff-lines`, Stryker `--mutate <file>:<lines>`); otherwise mutate only the changed files and keep only the mutants on changed lines. Run it through the project's tooling and run-heavy, as in step 4, on a scratch copy: the tools write files. Report its wall time and mutant count in Coverage & Verification, or why nothing was mutated. Ignore a surviving mutant that leaves behaviour unchanged, or changes only message or log text no caller or user depends on. Report one 🟡 per test to add or strengthen, naming the surviving mutants it would catch.
5. **Mutation-test the changed lines.** Run the project's documented mutation command, or else a widely deployed mutation tool for the language: cargo-mutants for Rust, Infection for PHP, mutmut for Python, Stryker for JavaScript and TypeScript. Limit it to the lines the change adds or modifies, through the tool's own option where it has one (cargo-mutants `--in-diff <diff file>`, Infection `--git-diff-lines`, Stryker `--mutate <file>:<lines>`); otherwise mutate only the changed files and keep only the mutants on changed lines. Run it through the project's tooling and run-heavy, as in step 4, on a scratch copy: the tools write files. Under run-heavy, a container that sets neither memory limit gets the slot's share, in MiB in `RUN_HEAVY_MEMORY`. Set the tool's concurrency so that its parallel test runs together fit in that share. Report its wall time and mutant count in Coverage & Verification, or why nothing was mutated. Ignore a surviving mutant that leaves behaviour unchanged, or changes only message or log text no caller or user depends on. Report one 🟡 per test to add or strengthen, naming the surviving mutants it would catch.
6. **Two passes minimum, then hunt absences.**
- *Breadth:* every hunk in every changed file, no skimming. Track which files you have covered; batch large diffs, never truncate the review.
- *Depth:* trace the riskiest data paths end-to-end (input → logic → persistence/response), the interactions between changed pieces, and between the change and config (timeout hierarchies, retries × idempotency, queue worker counts, env parity).
+93 -28
View File
@@ -1,30 +1,66 @@
"""What a docker command asks of docker: its subcommand, and whether a container it starts has a memory limit and a swap limit."""
"""What a docker command asks of docker: its subcommand, and whether a container it makes has a memory limit and a swap limit. capped adds the limits such a container lacks."""
import re
from shell_command import launched
import typing
# The options of docker, docker buildx and docker compose that take a value, so the value is not read as a subcommand.
DOCKER_VALUED = frozenset({"--ansi", "--builder", "--config", "--context", "--env-file", "--file", "--host", "--log-level", "--parallel", "--profile", "--progress", "--project-directory", "--project-name", "--tlscacert", "--tlscert", "--tlskey", "-c", "-f", "-H", "-l", "-p"})
# The subcommands that make a container, whose memory limits docker reads from the same options.
STARTS_CONTAINER = (["container", "create"], ["container", "run"], ["create"], ["run"])
# A size as docker reads one, such as 4g, 512M or 1.5GiB: the pattern go-units' RAMInBytes parses.
SIZE = r"\d+(?:\.\d+)*[kKmMgGtTpP]?[iI]?[bB]?"
# A swap limit is a size other than 0: docker reads --memory-swap -1 as unlimited swap, and 0 as unset.
SWAP = rf"(?!0+(?:\.0+)*[kKmMgGtTpP]?[iI]?[bB]?$){SIZE}"
# A size as docker reads one, such as 4g, 512M or 1.5GiB, each unit a power of 1024: go-units' RAMInBytes pattern, less a number with two points, such as 1.2.3, which its float parse refuses.
SIZE = r"(\d+(?:\.\d+)?)([kKmMgGtTpP]?)[iI]?[bB]?"
# Docker's documented floor for --memory, 6m: a smaller value, such as grep -m 1's, belongs to the container's own command.
MEMORY_FLOOR = 6 * 1024**2
MEMORY_OPTIONS = ("-m", "--memory")
SWAP_OPTIONS = ("--memory-swap",)
class Option(typing.NamedTuple):
"""An option the arguments give: where it stands, how many words it takes, and its value."""
at: int
length: int
value: str
def size(value: str) -> float | None:
"""The bytes a docker size spells; None for a value that is no size."""
spelled = re.fullmatch(SIZE, value)
return float(spelled.group(1)) * 1024 ** " kmgtp".index(spelled.group(2).lower() or " ") if spelled else None
def memory_limit(value: str) -> bool:
return (size(value) or 0) >= MEMORY_FLOOR
def swap_limit(value: str) -> bool:
"""Whether a --memory-swap value limits swap: -1 leaves it unlimited, and 0 leaves it unset, which docker reads as twice the memory limit."""
return bool(size(value))
def unset_swap(value: str) -> bool:
return value == "-1" or size(value) == 0
def zero(value: str) -> bool:
return size(value) == 0
def docker_subcommand(arguments: list[str]) -> list[str]:
"""The subcommand docker's arguments name, past its options: such as ["build"], ["compose", "run"] or ["buildx", "build"]."""
positional: list[str] = []
return [arguments[at] for at in subcommand_at(arguments)]
def subcommand_at(arguments: list[str]) -> list[int]:
"""Where in docker's arguments each word of its subcommand stands, so a global option's value that spells it, as in --context run, is not taken for it."""
positional: list[int] = []
skip = False
for word in arguments:
for at, word in enumerate(arguments):
if skip:
skip = False
elif word.startswith("-"):
skip = word in DOCKER_VALUED
else:
positional.append(word)
if positional[0] not in ("buildx", "compose", "container") or len(positional) == 2:
positional.append(at)
if arguments[positional[0]] not in ("buildx", "compose", "container") or len(positional) == 2:
break
return positional
@@ -32,26 +68,55 @@ def docker_subcommand(arguments: list[str]) -> list[str]:
def unlimited(arguments: list[str]) -> bool:
"""Whether docker's arguments make a container, with docker run or docker create, and leave its memory or its swap without a limit.
The container's own arguments, past its image, are read too: telling them apart needs every value-taking option of docker run. So a -m 4g there reads as a limit, while python -m pytest does not, since pytest is no size.
The container's own arguments, past its image, are read too: telling them apart needs every value-taking option of docker run. So a -m 4g there reads as a limit, while python -m pytest and grep -m 1 do not, since neither is a size docker takes.
"""
subcommand = docker_subcommand(arguments)
limited = given(arguments, ("-m", "--memory"), SIZE) and given(arguments, ("--memory-swap",), SWAP)
return subcommand in STARTS_CONTAINER and not limited and not helped(arguments, subcommand)
limited = option_value(arguments, MEMORY_OPTIONS, memory_limit) and option_value(arguments, SWAP_OPTIONS, swap_limit)
return subcommand in STARTS_CONTAINER and not limited and not helped(arguments)
def given(arguments: list[str], options: tuple[str, ...], pattern: str) -> bool:
"""Whether the arguments give one of the options a value pattern matches, as its next word or attached, as in -m4g or --memory=4g."""
attached = re.compile("|".join(re.escape(option) + ("" if len(option) == 2 else "=") + f"(?:{pattern})" for option in options))
return any(attached.fullmatch(word) or (word in options and re.fullmatch(pattern, following)) for word, following in zip(arguments, [*arguments[1:], ""]))
def unlimited_container(words: list[str]) -> bool:
"""Whether the simple command, directly or through a launcher, starts a container that lacks a memory limit or a swap limit."""
docker = launched(words, {"docker"})
return docker is not None and unlimited(docker.arguments)
def helped(arguments: list[str], subcommand: list[str]) -> bool:
def helped(arguments: list[str]) -> bool:
"""Whether docker only prints its help: a --help before the subcommand or as the first word after it, not one the container's own command takes."""
after = arguments.index(subcommand[-1]) + 1
after = subcommand_at(arguments)[-1] + 1
return "--help" in arguments[:after + 1]
def capped(arguments: list[str], share: str) -> list[str]:
"""docker's arguments, with each limit a container they make lacks added right after the subcommand.
A container that sets neither limit gets share for both. One that sets one limit gets the other at the same size, since docker refuses less swap than memory. A --memory-swap of -1 or 0 is dropped; every other word stays. Arguments with a --memory of 0 anywhere come back unchanged.
"""
# A -m 0 asks docker for unlimited memory, and would override an added limit; it may also be the container's own, as in grep -m 0, so it is neither dropped nor capped.
if not unlimited(arguments) or option_value(arguments, MEMORY_OPTIONS, zero):
return arguments
memory = option_value(arguments, MEMORY_OPTIONS, memory_limit)
swap = option_value(arguments, SWAP_OPTIONS, swap_limit)
rest = without(arguments, SWAP_OPTIONS, unset_swap)
limits = ([] if memory else ["--memory", swap or share]) + ([] if swap else ["--memory-swap", memory or share])
after = subcommand_at(rest)[-1] + 1
return [*rest[:after], *limits, *rest[after:]]
def option_value(arguments: list[str], options: tuple[str, ...], fits: typing.Callable[[str], bool]) -> str | None:
"""The value the arguments give one of the options, where it fits, as its next word or attached, as in -m4g or --memory=4g; None where they give none."""
found = option_at(arguments, options, fits)
return found.value if found else None
def without(arguments: list[str], options: tuple[str, ...], fits: typing.Callable[[str], bool]) -> list[str]:
"""The arguments with each of the options removed, with its value, where the value fits."""
while found := option_at(arguments, options, fits):
arguments = [*arguments[:found.at], *arguments[found.at + found.length:]]
return arguments
def option_at(arguments: list[str], options: tuple[str, ...], fits: typing.Callable[[str], bool]) -> Option | None:
"""Where the arguments first give one of the options, with a value that fits."""
for at, (word, following) in enumerate(zip(arguments, [*arguments[1:], ""])):
for option in options:
attached = word.removeprefix(option if len(option) == 2 else option + "=")
if attached != word and fits(attached):
return Option(at, 1, attached)
if word == option and fits(following):
return Option(at, 2, following)
return None
+6 -2
View File
@@ -1,10 +1,10 @@
"""How much of the machine's memory is available, as /proc/meminfo's MemAvailable and MemTotal state it, and whether at least ROOM_SHARE of it is available, which leaves room for a worker."""
"""How much of the machine's memory is available, as /proc/meminfo's MemAvailable and MemTotal state it. A worker starts while at least ROOM_SHARE of it is available. The rest is split across the heavy slots, as the memory limit run-heavy gives each container."""
import dataclasses
import pathlib
import re
MEMINFO = pathlib.Path("/proc/meminfo")
# A worker starts only while at least this share of the machine's memory is available; the human chose it, as no standard sets one.
# A worker starts only while at least this share of the machine's memory is available; the human chose it, as no standard sets one. The rest is the heavy slots' share, so changing it also changes the memory limit run-heavy gives a container.
ROOM_SHARE = 0.25
@@ -17,6 +17,10 @@ class Memory:
def has_room(self) -> bool:
return self.available >= ROOM_SHARE * self.total
def slot_share(self, slots: int) -> int:
"""The memory limit, in MiB, that run-heavy gives each container a slot's command makes: what ROOM_SHARE leaves, split evenly across the slots."""
return int(self.total * (1 - ROOM_SHARE)) // slots // 1024
def parsed(meminfo: str) -> Memory | None:
"""The memory a /proc/meminfo text states; None where it lacks MemAvailable or MemTotal."""
+6
View File
@@ -39,6 +39,12 @@ class MemoryShare(unittest.TestCase):
self.assertIsNone(memory.read_memory(pathlib.Path(temp, "gone")))
class SlotShare(unittest.TestCase):
def test_splits_the_three_quarters_a_worker_leaves_evenly_across_the_slots_in_mib(self):
self.assertEqual(memory.Memory(available=0, total=32 * 1024 * 1024).slot_share(4), 6144)
self.assertEqual(memory.Memory(available=0, total=8000000).slot_share(2), 2929)
class SlotFolder(unittest.TestCase):
def test_every_session_shares_the_slots_under_the_users_state_folder(self):
self.assertEqual(slots.slot_folder({}), pathlib.Path.home() / ".local" / "state" / "run-heavy")
+19 -3
View File
@@ -6,9 +6,9 @@ import typing
from round_titles import CAP, lacks_counts, past_cap
from git_command import commits
from rule_hook.heavy_command import heavy
from shell_command import launched, Simple, tool_name
from review_folder import REPORTS
from shell_command import Simple
from docker_command import unlimited_container
from docker_command import unlimited
RuleName = typing.Literal["action-pin", "commit-one-line", "docker-run-memory", "ignorefile-sorted", "image-pin", "no-ai-attribution", "reviewer-report", "reviewer-rung", "round-cap", "round-title-counts", "run-heavy", "todo-rank-check"]
@@ -32,7 +32,7 @@ RULES: dict[RuleName, Rule] = {
),
"docker-run-memory": Rule(
"a container made with docker run or docker create has a memory limit and a swap limit, as large as its work needs, such as `--memory 4g --memory-swap 4g`, so a runaway container fails alone instead of starving the machine; a swap limit equal to the memory limit keeps it out of swap",
"docker run, docker create, docker container run and docker container create, whether direct or through a launcher such as nice or timeout. A container a script or docker compose starts is not checked",
"docker run, docker create, docker container run and docker container create, whether direct or through a launcher such as nice or timeout. One under run-heavy passes, as run-heavy's docker adds the limits on Linux, unless it names docker by its path, or changes or clears PATH, as env -i, sudo or doas do. A container a script or docker compose starts is not checked",
),
"ignorefile-sorted": Rule(
"each block of an ignore file is sorted in code-point order, as LC_ALL=C sort does, since its order carries no meaning; where order matters, such as a re-include after its exclude, split the block with a blank line or a comment",
@@ -151,6 +151,22 @@ def command_breaches(command: str, simples: list[Simple], home: str) -> list[Bre
return breaches
def unlimited_container(words: list[str]) -> bool:
"""Whether the simple command, directly or through a launcher, starts a container that lacks a memory limit or a swap limit."""
docker = launched(words, {"docker"})
if docker is None or not unlimited(docker.arguments):
return False
# On Linux, run-heavy's docker adds the limits a container lacks, where PATH finds it: docker named bare, with PATH left as run-heavy set it.
before = words[:len(words) - len(docker.arguments) - 1]
capped = "run-heavy" in docker.launchers and words[len(before)] == "docker" and not any(resets_path(word) for word in before)
return not capped
def resets_path(word: str) -> bool:
"""Whether a word before docker drops the PATH run-heavy set: a PATH= of its own, env's -i or -u, or sudo or doas, which reset it."""
return word.startswith(("PATH=", "--unset")) or word in ("-i", "--ignore-environment", "-u") or tool_name(word) in ("doas", "sudo")
def file_breaches(path: str, before: str, added: str, after: str) -> list[Breach]:
"""Breaches in an edit of path: added is the text the edit writes, after the whole file it leaves."""
breaches = [Breach("no-ai-attribution", f"{path} would carry an attribution", posixpath.dirname(path))] if ATTRIBUTION.search(added) else []
+2 -2
View File
@@ -117,12 +117,12 @@ class CommandBreaches(unittest.TestCase):
self.assertEqual(checked(command), [])
def test_a_docker_run_or_create_without_a_memory_limit_breaks_docker_run_memory(self):
for command in ["docker run --rm node:24.22.1-alpine3.24 node x.js", "cd /w && docker run -v /w:/w alpine:3.22.2 true", "docker create alpine:3.22.2", "docker container run alpine:3.22.2 true", "docker container create alpine:3.22.2", "nice -n 19 docker run alpine:3.22.2 true", "docker -H unix:///d.sock run alpine:3.22.2 true", "docker run --memory-swap 4g alpine:3.22.2 true", "docker run -m 4g alpine:3.22.2 true", "docker run --memory=4g alpine:3.22.2 sh -c 'x --memory-swap 4g'", "docker run -m 4g alpine:3.22.2 tool --memory-swap", "docker run -m 4g --memory-swap -1 alpine:3.22.2 true", "docker run -m 4g --memory-swap=0 alpine:3.22.2 true", "~/.claude/bin/run-heavy docker run alpine:3.22.2 true", "docker run --rm python:3.13.1 python -m pytest", "docker run alpine:3.22.2 git commit -m x", "timeout 60 docker run alpine:3.22.2 true", "docker run node:24.22.1-alpine3.24 node --help", "docker run alpine:3.22.2 --help", "docker run -m 4g alpine:3.22.2 sleep 60"]:
for command in ["docker run --rm node:24.22.1-alpine3.24 node x.js", "cd /w && docker run -v /w:/w alpine:3.22.2 true", "docker create alpine:3.22.2", "docker container run alpine:3.22.2 true", "docker container create alpine:3.22.2", "nice -n 19 docker run alpine:3.22.2 true", "docker -H unix:///d.sock run alpine:3.22.2 true", "docker run --memory-swap 4g alpine:3.22.2 true", "docker run -m 4g alpine:3.22.2 true", "docker run --memory=4g alpine:3.22.2 sh -c 'x --memory-swap 4g'", "docker run -m 4g alpine:3.22.2 tool --memory-swap", "docker run -m 4g --memory-swap -1 alpine:3.22.2 true", "docker run -m 4g --memory-swap=0 alpine:3.22.2 true", "docker run --rm python:3.13.1 python -m pytest", "docker run alpine:3.22.2 git commit -m x", "timeout 60 docker run alpine:3.22.2 true", "docker run node:24.22.1-alpine3.24 node --help", "docker run alpine:3.22.2 --help", "docker run -m 4g alpine:3.22.2 sleep 60", "~/.claude/bin/run-heavy /usr/bin/docker run alpine:3.22.2 true", "docker run --memory-swap 4g alpine:3.22.2 grep -m 1 x", "run-heavy env PATH=/usr/bin docker run alpine:3.22.2 true", "run-heavy sudo docker run alpine:3.22.2 true", "docker run alpine:3.22.2 git tag -m 1.2.3", "run-heavy env -i docker run alpine:3.22.2 true", "run-heavy env -u PATH docker run alpine:3.22.2 true", "run-heavy env --unset=PATH docker run alpine:3.22.2 true", "run-heavy env --ignore-environment docker run alpine:3.22.2 true", "run-heavy doas docker run alpine:3.22.2 true"]:
with self.subTest(command):
self.assertEqual(checked(command), ["docker-run-memory"])
def test_a_docker_run_with_a_memory_limit_or_another_docker_call_passes_docker_run_memory(self):
for command in ["docker run -m 4g --memory-swap 4g alpine:3.22.2 true", "docker run -m4g --memory-swap=4g alpine:3.22.2 true", "docker run --memory 512M --memory-swap 1g alpine:3.22.2 true", "docker run -m 1073741824 --memory-swap 2g alpine:3.22.2 true", "timeout 60 docker run -m 4g --memory-swap 4g alpine:3.22.2 true", "docker run --rm --memory=1.5GiB --memory-swap=1.5GiB alpine:3.22.2 true", "docker container create -m 1g --memory-swap 1g alpine:3.22.2", "docker run --help", "docker container run --help", "docker --help", "docker ps", "docker images", "docker container ls", "docker compose run --rm app go vet", "docker exec box true", "echo docker run alpine:3.22.2"]:
for command in ["docker run -m 4g --memory-swap 4g alpine:3.22.2 true", "docker run -m4g --memory-swap=4g alpine:3.22.2 true", "docker run --memory 512M --memory-swap 1g alpine:3.22.2 true", "docker run -m 1073741824 --memory-swap 2g alpine:3.22.2 true", "timeout 60 docker run -m 4g --memory-swap 4g alpine:3.22.2 true", "docker run --rm --memory=1.5GiB --memory-swap=1.5GiB alpine:3.22.2 true", "docker container create -m 1g --memory-swap 1g alpine:3.22.2", "docker run --help", "docker container run --help", "docker --context run run --help", "docker --help", "docker ps", "docker images", "docker container ls", "docker compose run --rm app go vet", "docker exec box true", "echo docker run alpine:3.22.2", "~/.claude/bin/run-heavy docker run alpine:3.22.2 true"]:
with self.subTest(command):
self.assertEqual(checked(command), [])
+3 -2
View File
@@ -5,7 +5,8 @@ import sys
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
from machine_load.slots import usable_cpus
from run_heavy import main
from machine_load.memory import read_memory
from machine_load.slots import usable_cpus
sys.exit(main.main(sys.argv[1:], os.environ, usable_cpus()))
sys.exit(main.main(sys.argv[1:], os.environ, usable_cpus(), read_memory()))
+35
View File
@@ -0,0 +1,35 @@
"""The docker that run-heavy puts first on its command's PATH. It adds the memory limits a container lacks, from the slot's share, then runs the real docker."""
import os
import pathlib
import shutil
import sys
import typing
from docker_command import capped
# The folder run-heavy puts first on its command's PATH, holding the docker that runs main.
PATH_ENTRY = pathlib.Path(__file__).resolve().parent / "path_entry"
# The environment variable that hands this docker the slot's memory share, in MiB.
SHARE_VARIABLE = "RUN_HEAVY_MEMORY"
CANNOT_RUN = 126
NOT_FOUND = 127
def main(argv: list[str], env: typing.Mapping[str, str]) -> int:
"""Replaces this process with the real docker; returns only where none is found or it cannot run."""
path = without_path_entry(env.get("PATH", ""))
docker = shutil.which("docker", path=path)
if docker is None:
print("run-heavy: docker: command not found", file=sys.stderr)
return NOT_FOUND
share = env.get(SHARE_VARIABLE)
try:
os.execve(docker, [docker, *(capped(argv, f"{share}m") if share else argv)], {**env, "PATH": path})
except OSError as failure:
print(f"run-heavy: cannot run {docker}: {failure.strerror}", file=sys.stderr)
return CANNOT_RUN
def without_path_entry(path: str) -> str:
"""path less PATH_ENTRY, so the real docker is the one found."""
return os.pathsep.join(entry for entry in path.split(os.pathsep) if pathlib.Path(entry).resolve() != PATH_ENTRY)
+26 -2
View File
@@ -9,6 +9,19 @@ $XDG_STATE_HOME/run-heavy (default ~/.local/state/run-heavy). While every slot i
says so once on stderr and waits. It then replaces itself with the command. The slot's lock stays held
until the command, and every process that inherited the lock, exits. Its exit code is the command's.
On Linux, run-heavy also caps the memory of each container the command makes with docker run or
docker create. The cap is the slot's share: three quarters of the machine's memory, split evenly
across the slots, handed to the command in RUN_HEAVY_MEMORY, in MiB. run-heavy puts its own docker
first on the command's PATH. That docker adds the limits a container lacks, then runs the real one:
- A container that sets neither limit gets a memory limit and a swap limit, both the share.
- A container that sets one of them keeps it, and gets the other at the same size.
- A --memory-swap of -1, unlimited swap, is dropped and replaced.
- A --memory of 0, unlimited memory, leaves the call as it is.
Every other docker call goes through unchanged. A docker compose service, and a docker named by its
full path, get no cap: give those containers their own limits.
A command it runs carries the slot's number in RUN_HEAVY_SLOT, and run-heavy called with that set
runs its command at once, so a gate that wraps its own steps cannot wait on itself.
@@ -17,10 +30,13 @@ folder or a slot file cannot be made or locked; 126 when the command is found bu
"""
import os
import pathlib
import shutil
import sys
import typing
from failure import Failure
from machine_load.memory import Memory
from run_heavy.capped_docker import PATH_ENTRY, SHARE_VARIABLE, without_path_entry
from machine_load.slots import slot_count, slot_folder, waited_slot
OWN_FAILURE = 125
@@ -30,7 +46,7 @@ HELD = "RUN_HEAVY_SLOT"
USAGE = "usage: run-heavy <command> [<arg>...]"
def main(argv: list[str], env: typing.Mapping[str, str], cpus: int | None) -> int:
def main(argv: list[str], env: typing.Mapping[str, str], cpus: int | None, memory: Memory | None) -> int:
if argv[:1] in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
@@ -42,10 +58,18 @@ def main(argv: list[str], env: typing.Mapping[str, str], cpus: int | None) -> in
if isinstance(slot, Failure):
print(f"run-heavy: {slot.reason}", file=sys.stderr)
return OWN_FAILURE
env = {**env, HELD: str(slot)}
env = {**env, HELD: str(slot), **capping(memory, slot_count(cpus), env)}
return run(argv, env)
def capping(memory: Memory | None, slots: int, env: typing.Mapping[str, str]) -> dict[str, str]:
"""What the command's environment needs for its docker to cap each container it makes at the slot's share of memory; nothing where the memory is unknown, as off Linux, or where PATH finds no docker to cap."""
path = env.get("PATH", "")
if memory is None or shutil.which("docker", path=without_path_entry(path)) is None:
return {}
return {SHARE_VARIABLE: str(memory.slot_share(slots)), "PATH": os.pathsep.join([str(PATH_ENTRY), path])}
def held_slot(folder: pathlib.Path, slots: int) -> int | Failure:
"""The number of the slot this call holds, its lock left for the command to inherit, or why no slot could be taken."""
try:
+10
View File
@@ -0,0 +1,10 @@
#!/usr/bin/env python3
import os
import pathlib
import sys
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))
from run_heavy import capped_docker
sys.exit(capped_docker.main(sys.argv[1:], os.environ))
+51
View File
@@ -10,6 +10,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from run_heavy import main
from machine_load.memory import read_memory
from machine_load.slots import slot_count, usable_cpus
TOOL = pathlib.Path(__file__).resolve().parents[1] / "run-heavy"
@@ -82,6 +83,56 @@ class RunHeavy(unittest.TestCase):
self.assertEqual((denied.returncode, denied.stdout), (126, ""))
self.assertIn(unrunnable.name, denied.stderr)
def fake_docker(self) -> dict[str, str]:
"""An environment whose PATH finds, ahead of any real one, a docker that prints the arguments it was given."""
folder = tempfile.TemporaryDirectory()
self.addCleanup(folder.cleanup)
docker = pathlib.Path(folder.name) / "docker"
docker.write_text("#!/bin/sh\necho \"$@\"\n")
docker.chmod(0o755)
return {**self.env, "PATH": f"{folder.name}:{self.env['PATH']}"}
def test_a_docker_run_without_limits_gets_three_quarters_of_the_memory_split_across_the_slots(self):
memory = read_memory()
if memory is None:
self.skipTest("no /proc/meminfo to read the share from")
share = f"{memory.total * 3 // 4 // slot_count(usable_cpus()) // 1024}m"
result = self.run_tool("docker", "run", "--rm", "img", "true", env=self.fake_docker())
self.assertEqual((result.returncode, result.stdout), (0, f"run --memory {share} --memory-swap {share} --rm img true\n"))
def test_a_docker_call_with_its_own_limits_or_that_starts_no_container_is_passed_on_unchanged(self):
env = self.fake_docker()
for args in [["run", "-m", "40g", "--memory-swap", "40g", "img"], ["ps", "-a"], ["build", "."]]:
with self.subTest(args):
result = self.run_tool("docker", *args, env=env)
self.assertEqual((result.returncode, result.stdout), (0, " ".join(args) + "\n"))
def test_a_command_on_a_machine_without_docker_finds_none(self):
folder = tempfile.TemporaryDirectory()
self.addCleanup(folder.cleanup)
(pathlib.Path(folder.name) / "python3").symlink_to(sys.executable)
(pathlib.Path(folder.name) / "sh").symlink_to("/bin/sh")
result = self.run_tool("sh", "-c", "command -v docker || echo none", env={**self.env, "PATH": folder.name})
self.assertEqual((result.returncode, result.stdout), (0, "none\n"))
def test_the_capped_docker_passes_a_call_on_unchanged_without_a_share(self):
env = self.fake_docker()
env.pop("RUN_HEAVY_MEMORY", None)
shim = pathlib.Path(TOOL).parent / "run_heavy" / "path_entry" / "docker"
result = subprocess.run([str(shim), "run", "img"], capture_output=True, text=True, env=env, timeout=30)
self.assertEqual((result.returncode, result.stdout), (0, "run img\n"))
def test_no_cap_where_the_memory_is_unknown(self):
self.assertEqual(main.capping(None, 4, self.fake_docker()), {})
def test_a_capped_docker_that_finds_no_docker_exits_127_saying_so(self):
folder = tempfile.TemporaryDirectory()
self.addCleanup(folder.cleanup)
(pathlib.Path(folder.name) / "python3").symlink_to(sys.executable)
result = self.run_tool("docker", "ps", env={**self.env, "PATH": folder.name})
self.assertEqual((result.returncode, result.stdout), (127, ""))
self.assertIn("docker", result.stderr)
def test_no_command_exits_125_with_the_usage_and_help_exits_0(self):
bare = self.run_tool()
self.assertEqual((bare.returncode, bare.stdout), (125, ""))
+43
View File
@@ -0,0 +1,43 @@
import unittest
from docker_command import capped
class Capped(unittest.TestCase):
def test_a_container_without_limits_gets_the_share_for_both(self):
for given, expected in [
(["run", "--rm", "img", "true"], ["run", "--memory", "6144m", "--memory-swap", "6144m", "--rm", "img", "true"]),
(["-H", "unix:///d.sock", "run", "img"], ["-H", "unix:///d.sock", "run", "--memory", "6144m", "--memory-swap", "6144m", "img"]),
(["container", "create", "img"], ["container", "create", "--memory", "6144m", "--memory-swap", "6144m", "img"]),
(["--context", "run", "run", "img"], ["--context", "run", "run", "--memory", "6144m", "--memory-swap", "6144m", "img"]),
(["run", "img", "python", "-m", "pytest"], ["run", "--memory", "6144m", "--memory-swap", "6144m", "img", "python", "-m", "pytest"]),
(["run", "img", "grep", "-m", "1", "x"], ["run", "--memory", "6144m", "--memory-swap", "6144m", "img", "grep", "-m", "1", "x"]),
(["run", "img", "git", "tag", "-m", "1.2.3"], ["run", "--memory", "6144m", "--memory-swap", "6144m", "img", "git", "tag", "-m", "1.2.3"]),
(["run", "-m", "6143k", "img"], ["run", "--memory", "6144m", "--memory-swap", "6144m", "-m", "6143k", "img"]),
(["run", "img", "tool", "-m", "6"], ["run", "--memory", "6144m", "--memory-swap", "6144m", "img", "tool", "-m", "6"]),
(["run", "img", "stress", "--memory", "2"], ["run", "--memory", "6144m", "--memory-swap", "6144m", "img", "stress", "--memory", "2"]),
]:
with self.subTest(given):
self.assertEqual(capped(given, "6144m"), expected)
def test_a_container_s_own_limit_is_kept_and_sets_the_limit_it_lacks(self):
for given, expected in [
(["run", "-m", "10g", "img"], ["run", "--memory-swap", "10g", "-m", "10g", "img"]),
(["run", "-m", "6m", "img"], ["run", "--memory-swap", "6m", "-m", "6m", "img"]),
(["run", "--memory=12g", "img"], ["run", "--memory-swap", "12g", "--memory=12g", "img"]),
(["run", "--memory-swap", "2g", "img"], ["run", "--memory", "2g", "--memory-swap", "2g", "img"]),
(["run", "-m", "4g", "--memory-swap", "-1", "img"], ["run", "--memory-swap", "4g", "-m", "4g", "img"]),
(["run", "-m4g", "--memory-swap=0", "img", "python", "-m", "pytest"], ["run", "--memory-swap", "4g", "-m4g", "img", "python", "-m", "pytest"]),
(["run", "img", "app", "-m", "512m"], ["run", "--memory-swap", "512m", "img", "app", "-m", "512m"]),
]:
with self.subTest(given):
self.assertEqual(capped(given, "6144m"), expected)
def test_a_container_with_both_limits_or_another_docker_call_is_left_alone(self):
for given in [["run", "-m", "0", "img"], ["run", "img", "grep", "-m", "0", "x"], ["run", "-m", "10g", "--memory-swap", "12g", "img"], ["ps"], ["build", "."], ["run", "--help"], ["compose", "run", "app"], ["exec", "box", "true"]]:
with self.subTest(given):
self.assertEqual(capped(given, "6144m"), given)
if __name__ == "__main__":
unittest.main()
+40
View File
@@ -2727,3 +2727,43 @@ Junior A, decided by:
- Shape, Locality: `bin/rule_hook/heavy_command.py:12` `heavy`: from 13 lines mixing three parsings to 8 with a clear docker-or-mutator branch
- Shape: `bin/docker_command.py:1` `docker_command`: a truthful name and docstring, though it sits at bin's root rather than beside rule_hook's rules
- Locality: `bin/rule_hook/rules.py:140` `command_breaches`: the new rule plugs in beside run-heavy as one parallel if
## 2026-10-24T09:53:49Z, PR #373 at 3ac8c79, against eb7b506
Ruling: same
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|---|---|---|---|---|---|
| Mid A | same | worse | same | better | same |
| Inherited architect | same | worse | worse | same | worse |
| Maintainability senior | same | worse | worse | same | worse |
| Junior A | same | worse | same | same | same |
Mid A, decided by:
- Locality: `bin/rule_hook/rules.py:154` `unlimited_container`: rule-hook now encodes how run-heavy's docker puts itself on PATH, joined to it by a one-line comment
- Locality: `bin/run_heavy/main.py:65` `capping`: a stand-in docker on PATH and RUN_HEAVY_MEMORY make a container's limits depend on the environment, though the help spells it out
- Self-sufficiency: `bin/docker_command.py:24` `size`: named predicates replace a negative-lookahead regex, and swap_limit says what -1 and 0 mean
- Self-sufficiency: `bin/docker_command.py:52` `subcommand_at`: positions replace a first-match lookup that took an option's value for the subcommand
- Shape: `bin/docker_command.py:84` `capped`: the module grows from 5 functions to 13, and one line packs four conditional limit lists
Inherited architect, decided by:
- Locality, Shape: `bin/rule_hook/rules.py:154` `unlimited_container`: index arithmetic finds the words before docker, and the rule encodes how another package's PATH shim works
- Locality: `bin/rule_hook/rules.py:165` `resets_path`: reads as a guess about launchers rather than a model of them
- Locality: `bin/run_heavy/main.py:65` `capping`: whether a docker run gets limits depends on PATH order and a variable an ancestor set
- Shape: `bin/docker_command.py:39` `unset_swap`: named unset though -1 is unlimited, beside a generic zero, in a module that now reads and rewrites commands
- Shape: `bin/docker_command.py:24` `size`: replaces a hard negative-lookahead regex, offsetting in part
Maintainability senior, decided by:
- Locality: `bin/rule_hook/rules.py:154` `unlimited_container`: repeats how run-heavy's PATH trick works, so a change to run-heavy silently changes the rule, and the index arithmetic takes a second read
- Locality: `bin/machine_load/memory.py:20` `Memory.slot_share`: tuning the worker threshold ROOM_SHARE now also changes every capped container's memory, while its comment names only the worker
- Locality: `bin/run_heavy/main.py:65` `capping`: the share reaches the docker shim through an environment variable and a PATH entry, hidden state between two processes
- Shape: `bin/docker_command.py:24` `size`: the module grows to 13 functions that read and rewrite commands, with predicates named as nouns
- Shape: `bin/docker_command.py:84` `capped`: one line crosses the two limits' values over and needs the docstring
Junior A, decided by:
- Locality: `bin/rule_hook/rules.py:154` `unlimited_container`: rule-hook copies run-heavy's PATH trick, and nothing in run_heavy points back to it
- Locality: `bin/run_heavy/main.py:65` `capping`: one process sets RUN_HEAVY_MEMORY and PATH, and another reads them, so a docker run spans two processes
+4 -2
View File
@@ -76,9 +76,11 @@ The cap is 5, `bin/todo_table.py`'s `BUNDLE_MAX_R`, from the same chunks: by the
2026-10-23, lilleman. Serves goal 1.5. On 2026-10-22 ai-sandbox, with 8 CPUs and 16 GiB, thrashed for hours: four to six loops ran mutation tests, full gates, `docker build`s and QEMU-booting e2e tests at once, and nothing told one loop how busy the machine was. lilleman chose both limits; no standard sets either, and GNU parallel's `--memfree`, which does the memory wait's job, has no default. A slot is a file lock, so a session that dies frees its slot. The memory wait reads `/proc/meminfo` only, and off Linux a worker starts at once. `bin/machine_load/` holds the slots and the memory share, `bin/run-heavy` takes a slot, `CLAUDE.md` → "Working with the codebase" has every session use it, and loop-claude's worker waits for the share. rule-hook's rule `run-heavy` blocks a `docker build`, and a run of a mutation tool stability-reviewer names, outside run-heavy, whether direct or inside a container. No program can tell a gate script from a light one, so only `CLAUDE.md` asks a session to run a gate under run-heavy. Valid while one machine runs several loops at once.
## machine load: every container a session starts has a memory limit and a swap limit as large as its work needs, which rule-hook's `docker-run-memory` enforces on `docker run` and `docker create`, and no daemon-wide cap limits all containers together
## machine load: every container a session starts has a memory limit and a swap limit as large as its work needs; rule-hook's `docker-run-memory` blocks a `docker run` or `docker create` without them outside run-heavy, under which a container that lacks them gets the slot's share of three quarters of the memory; and no daemon-wide cap limits all containers together
2026-10-24, lilleman. Serves goal 1.5. On 2026-10-23 ai-sandbox, then with 8 CPUs and 7.6 GiB of memory, hung until a hard reset, although its one heavy command held a slot. Beside that mutation run, a reviewer's stress probes ran in `docker run` with no memory limit, each to 2 GiB. A limit makes a runaway container fail alone instead of taking the machine with it. A swap limit is needed too: without one, docker lets a container swap as much again as its memory limit, and swapping is how the machine hung. The session sizes both limits, since lilleman wants a project to run heavier work where it needs to. rule-hook reads only the `docker run` and `docker create` in a session's Bash commands. A container a script starts is out of its sight, and so is a compose service, whose limits live in its compose file. `CLAUDE.md` → "Working with the codebase" asks a session for limits there, and todo item 227 caps the containers a heavy command starts under run-heavy.
2026-10-24, lilleman. Serves goal 1.5. On 2026-10-23 ai-sandbox, then with 8 CPUs and 7.6 GiB of memory, hung until a hard reset, although its one heavy command held a slot. Beside that mutation run, a reviewer's stress probes ran in `docker run` with no memory limit, each to 2 GiB. A limit makes a runaway container fail alone instead of taking the machine with it. A swap limit is needed too: without one, docker lets a container swap as much again as its memory limit, and swapping is how the machine hung. The session sizes both limits, since lilleman wants a project to run heavier work where it needs to. rule-hook reads only the `docker run` and `docker create` in a session's Bash commands. A container a script starts is out of its sight, and so is a compose service, whose limits live in its compose file. `CLAUDE.md` → "Working with the codebase" asks a session for limits there.
The heavy command in that hang started its container from the project's own script, out of rule-hook's sight. So run-heavy puts its own `docker`, `bin/run_heavy/path_entry/docker`, first on its command's `PATH`. That docker gives each `docker run` or `docker create` that lacks a limit the slot's share. The share is what a worker's quarter leaves: three quarters of MemTotal, split evenly across the slots. A container that sets one of the two limits keeps it, and gets the other as large, since docker refuses less swap than memory; an unlimited swap, `--memory-swap -1`, gives way. run-heavy cannot place the command in a cgroup instead: none is delegated to the user, and dockerd starts the containers outside the command's process tree. A compose service, and a docker named by its full path, keep no cap.
A daemon-wide cap would see every container: dockerd's `cgroup-parent`, given a memory limit. lilleman turned it down, since it is host config and would cap a project's heavy work too. Valid while sessions start their work in containers on a machine they share.
+6 -10
View File
@@ -6,7 +6,7 @@
`Bar = 0.1`
`Next ID = 229`
`Next ID = 230`
## Items
@@ -16,8 +16,8 @@
| 59 | 0.4.0 | | | **Bound a run of unfinished verdicts on one chunk, so a worker and judge that disagree cannot cycle unattended without end.** | 2 | 1 | 3 | 4 | 3 | 1.4 by 6 | 6.0 |
| 167 | 0.4.0 | | | **Refuse a `/security-review` or `/claude-security` Skill call below the project's rung, as rule-hook refuses such an Agent call.** | 3 | 2 | 3 | 6 | 2 | 1.1 by 4 | 5.6 |
| 6 | 0.4.0 | | decision | **Move what `loop-claude` writes out of `~/.claude.json`, and ask the human about each write that must stay.** | 3 | 3 | 3 | 7 | 3 | 1.1 by 5 | 5.3 |
| 227 | 0.4.0 | | | **Cap the memory of each container a heavy command starts under run-heavy at its slot's share, and have stability-reviewer size a mutation run's concurrency to fit that cap.** | 3 | 2 | 3 | 6 | 5 | 1.5 by 5 | 1.9 |
| 1 | 0.5.0 | | question | **Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.** | 1 | 2 | 1 | 2 | 1 | | 0.0 |
| 229 | 0.5.0 | | | **Keep the rule for which commands reach run-heavy's docker beside that docker in `bin/run_heavy/capped_docker.py`, so rule-hook's `docker-run-memory` asks it instead of repeating run-heavy's PATH rules.** | 2 | 1 | 3 | 4 | 2 | code health by 3 | 18.0 |
| 219 | 0.5.0 | | | **Name the project's rung `project` in `bin/judge_replay/main.py`, `bin/subagent_rung/main.py` and `bin/review_replay/main.py`, in place of `anchor`, as `bin/model_routing/ladder.py` and `bin/loop_claude` name it.** | 1 | 1 | 3 | 3 | 2 | code health by 2 | 12.0 |
| 224 | 0.5.0 | | | **Split `docs/decisions.md` → `todo.md: one table of items, …`'s 420-word scoring paragraph into one paragraph per choice, and drop the sentences that tell how the goal weights changed.** | 1 | 1 | 1 | 1 | 2 | code health by 2 | 12.0 |
| 123 | 0.5.0 | | | **Have `bin/comprehension_history.py` parse each history entry once into seats, votes and places, so `latest_places`, `worse_places` and `worse_votes` neither depend on table order nor split a label to find a seat.** | 2 | 1 | 2 | 3 | 5 | code health by 5, 1.4 by 5 | 11.0 |
@@ -87,14 +87,6 @@ rule-hook checks Agent calls (item 163) but no Skill calls. A worker that invoke
Claude Code owns that file and writes it. `trust` reads it, changes it and writes it back, so a write that lands in between is lost.
### 227. Cap the memory of each container a heavy command starts under run-heavy at its slot's share, and have stability-reviewer size a mutation run's concurrency to fit that cap.
On 2026-10-23 ai-sandbox, then with 8 CPUs and 7.6 GiB, hung in swap until a hard reset. One heavy command held its slot, as the decision `machine load: a heavy command waits for one of the machine's heavy slots, …` asks: adf-codec's stability reviewer ran Stryker with concurrency 4, each copy running the whole `node --test` suite, in one container that reached 4 GiB. The container was started by the project's own script, so rule-hook's `docker-run-memory` can't see one like it. The slots cap how many heavy commands run at once, not how much memory one takes.
run-heavy cannot place the command in a cgroup: none is delegated to the user, and dockerd starts the containers outside the command's process tree. So run-heavy puts first on the command's `PATH` a `docker` that adds `--memory` and `--memory-swap`, both at the slot's share, to each `docker run`, `docker create` and `docker container run|create` that leaves either without a limit, then runs the real docker. It tells such a call apart with `bin/docker_command.py`'s `unlimited`, which rule-hook's `docker-run-memory` reads too. A container that sets its own limits keeps them, so a project runs heavier work where it needs to (lilleman, 2026-10-24). A compose service, and a docker named by its full path, keep no cap.
The slot's share is a new choice, to record in the decision `machine load: every container a session starts has …`: that decision's elder, `machine load: a heavy command waits …`, starts a worker only while a quarter of the memory is available, so the share is the other three quarters of MemTotal, split evenly across the slots. Update both decisions, run-heavy's help and stability-reviewer's mutation step, which sizes Stryker's or mutmut's concurrency so the run fits the cap. Once run-heavy caps them, let `docker-run-memory` pass a `docker run` under run-heavy, which `shell_command.launched` reports among a call's launchers. Test first in `bin/run_heavy/test_run_heavy.py`.
### 1. Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.
It lives under `~/.claude`, which `.gitignore` keeps from the remote, so a lost disk loses every unattended run's record. Back it up only to a destination private to me and encrypted at rest: the worker runs with permissions bypassed, so the archived tool results can hold credentials it read.
@@ -103,6 +95,10 @@ It lives under `~/.claude`, which `.gitignore` keeps from the remote, so a lost
The README line covers the bench's transcripts in `workflow-bench/logs/` too (goal 3).
### 229. Keep the rule for which commands reach run-heavy's docker beside that docker in `bin/run_heavy/capped_docker.py`, so rule-hook's `docker-run-memory` asks it instead of repeating run-heavy's PATH rules.
The paired ruling of PR #373 found Locality worse with all four seats, and named `bin/rule_hook/rules.py` `unlimited_container` and `resets_path` first. rule-hook exempts a `docker run` under run-heavy only where run-heavy's docker will run it: docker named bare, with PATH left as run-heavy set it. That knowledge of how `run_heavy/main.py` `capping` puts `PATH_ENTRY` first lives in rule-hook, so a change to run-heavy silently changes what the rule lets through. Move the predicate, with its words-before-docker index arithmetic made plain, next to `PATH_ENTRY`, and have the rule call it. Make the two places easier to read, as the seats named them.
### 219. Name the project's rung `project` in `bin/judge_replay/main.py`, `bin/subagent_rung/main.py` and `bin/review_replay/main.py`, in place of `anchor`, as `bin/model_routing/ladder.py` and `bin/loop_claude` name it.
Item 172 renamed `anchor` to `project` across `bin/loop_claude`, after release 0.3.0's inherited architect named `bin/loop_claude/cycle/judge.py:68` `Reply.bundled`: "the project's rung is also called anchor". Three tools outside it still call the same rung `anchor`: `bin/judge_replay/main.py:54` (`anchor = arguments_or_exit(...)`, a `Rung` parsed from the model argument), `bin/subagent_rung/main.py:26` (`anchor = project_rung(model)`), and `bin/review_replay/main.py:74`, `:100` and `:180`, with `findings_found`'s docstring. While the name differs between tools, a reader works out each time that the two are one rung. The rename keeps behaviour. `bin/score_outcomes/anchors.py` uses `anchor` for score anchors, a different thing, and keeps the name.