Answer architecture round 1: 0 🔴, 3 🟡; keep the slots and the memory share in machine_load, exit 125/126/127 as GNU wrappers do, point --help at the module

This commit is contained in:
2026-10-23 10:47:01 +02:00
parent 7c05bf414c
commit 66af309e71
12 changed files with 113 additions and 67 deletions
+2
View File
@@ -39,6 +39,8 @@
!bin/loop_claude/
!bin/loop_claude/**/
!bin/loop_claude/**/*.py
!bin/machine_load/
!bin/machine_load/*.py
!bin/markdown_text.py
!bin/metric-bench
!bin/metric_bench/
+1 -1
View File
@@ -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. 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. `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/` holds the machine's heavy slots, which `run_heavy` takes, and the memory share 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
@@ -8,7 +8,7 @@ import typing
from failure import Failure
import git_repo
from loop_claude.memory import Memory, read_memory
from machine_load.memory import Memory, read_memory
# Seconds before a Python script loop-claude runs is stopped, so a hung one, such as chunk-preflight, cannot hold the loop.
PYTHON_TIMEOUT = 600
+2 -4
View File
@@ -44,10 +44,8 @@ copied into a folder per chunk under $LOOP_CLAUDE_TRANSCRIPTS/<key> (default roo
then each verdict, quoted answer, rejected judge reply, step-up and stop, each opened by its UTC
time. The layout, and when a copy is replaced, are in bin/transcript_archive/__init__.py.
Before each worker starts, loop-claude waits while less than a quarter of the machine's memory is
available, as /proc/meminfo's MemAvailable and MemTotal state, saying so once on stderr and reading
again each minute, so loops running at once do not push the machine into swap. Where the file cannot
be read, as off Linux, the worker starts at once.
Before each worker starts, loop-claude waits until a quarter of the machine's memory is available
(bin/machine_load/memory.py).
Every claude loop-claude starts runs the project's model, saved per <key> in
~/.claude/loop-claude-models.json and read each cycle, unless routing, below, puts the worker,
+2 -14
View File
@@ -22,7 +22,8 @@ from loop_claude.project import checkout, model_choice, records
from chunk_pick import DefaultPlan, LastCut
from loop_claude.effects import Effects, PYTHON_TIMEOUT, run_python
from claude_code import entries, reply, session
from loop_claude import escalation_mark, memory, paths, routing
from loop_claude import escalation_mark, paths, routing
from machine_load import memory
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished
from loop_claude.cycle import interrupt, judge, prompts, retry, run, states, worker
@@ -591,19 +592,6 @@ class Limits(unittest.TestCase):
class MemoryWait(unittest.TestCase):
def test_reads_available_and_total_memory_from_meminfo(self):
meminfo = "MemTotal: 16387072 kB\nMemFree: 981236 kB\nMemAvailable: 4096000 kB\n"
self.assertEqual(memory.parsed(meminfo), memory.Memory(available=4096000, total=16387072))
for unread in ("MemTotal: 16 kB\n", "MemTotal: x kB\nMemAvailable: 1 kB\n", ""):
self.assertIsNone(memory.parsed(unread), unread)
def test_reads_a_meminfo_file_and_none_where_it_cannot(self):
with tempfile.TemporaryDirectory() as temp:
meminfo = pathlib.Path(temp, "meminfo")
meminfo.write_text("MemTotal: 8 kB\nMemAvailable: 2 kB\n")
self.assertEqual(memory.read_memory(meminfo), memory.Memory(available=2, total=8))
self.assertIsNone(memory.read_memory(pathlib.Path(temp, "gone")))
def test_a_worker_starts_only_once_a_quarter_of_memory_is_available(self):
fake = FakeEffects(free_memory=[memory.Memory(available=3, total=16), memory.Memory(available=3, total=16), memory.Memory(available=4, total=16)], streams=[Streamed(0)])
with contextlib.redirect_stderr(io.StringIO()) as said:
View File
@@ -1,3 +1,10 @@
"""How much of the machine's memory is available, so loop-claude starts a worker only while a quarter is.
loop-claude reads MemAvailable and MemTotal from /proc/meminfo before each worker starts. While less
than a quarter is available, it says so once on stderr and reads again each minute, so loops running
at once do not push the machine into swap. Where the file cannot be read, as off Linux, the worker
starts at once.
"""
import dataclasses
import pathlib
import re
+29
View File
@@ -0,0 +1,29 @@
"""The machine's heavy slots: one per 4 CPUs, and at least one, each a file locked with flock that every session on the machine shares."""
import fcntl
import os
import pathlib
import typing
CPUS_PER_SLOT = 4
def slot_count(cpus: int | None) -> int:
return max(1, (cpus or 0) // CPUS_PER_SLOT)
def slot_folder(env: typing.Mapping[str, str]) -> pathlib.Path:
state = env.get("XDG_STATE_HOME") or str(pathlib.Path.home() / ".local" / "state")
return pathlib.Path(state) / "run-heavy"
def taken_slot(folder: pathlib.Path, slots: int) -> tuple[int, int] | None:
"""The number and open file of a slot this call locked; None while every slot is held."""
for slot in range(slots):
fd = os.open(folder / f"slot-{slot}", os.O_RDWR | os.O_CREAT, 0o644)
try:
fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
except BlockingIOError:
os.close(fd)
continue
return slot, fd
return None
+39
View File
@@ -0,0 +1,39 @@
import pathlib
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from machine_load import memory
from machine_load.slots import slot_count
class SlotCount(unittest.TestCase):
def test_one_slot_per_four_cpus_and_never_none(self):
for cpus, slots in ((16, 4), (8, 2), (7, 1), (4, 1), (1, 1), (None, 1)):
self.assertEqual(slot_count(cpus), slots, cpus)
class Memory(unittest.TestCase):
def test_has_room_from_a_quarter_of_memory_available(self):
self.assertFalse(memory.Memory(available=3, total=16).has_room())
self.assertTrue(memory.Memory(available=4, total=16).has_room())
def test_reads_available_and_total_memory_from_meminfo(self):
meminfo = "MemTotal: 16387072 kB\nMemFree: 981236 kB\nMemAvailable: 4096000 kB\n"
self.assertEqual(memory.parsed(meminfo), memory.Memory(available=4096000, total=16387072))
for unread in ("MemTotal: 16 kB\n", "MemTotal: x kB\nMemAvailable: 1 kB\n", ""):
self.assertIsNone(memory.parsed(unread), unread)
def test_reads_a_meminfo_file_and_none_where_it_cannot(self):
with tempfile.TemporaryDirectory() as temp:
meminfo = pathlib.Path(temp, "meminfo")
meminfo.write_text("MemTotal: 8 kB\nMemAvailable: 2 kB\n")
self.assertEqual(memory.read_memory(meminfo), memory.Memory(available=2, total=8))
self.assertIsNone(memory.read_memory(pathlib.Path(temp, "gone")))
if __name__ == "__main__":
unittest.main()
+14 -30
View File
@@ -12,17 +12,20 @@ it and every process that inherited the lock exit. Its exit code is the command'
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.
Exit 1, saying why, when no command is given or the slot folder cannot be made; exit 127 when the
command cannot start.
As GNU env, nice and timeout do, it exits 125, saying why, when no command is given or the slot
folder cannot be made; 126 when the command is found but cannot run; and 127 when it is not found.
"""
import fcntl
import os
import pathlib
import sys
import time
import typing
CPUS_PER_SLOT = 4
from machine_load.slots import slot_count, slot_folder, taken_slot
# Exit codes for a command run-heavy never ran, apart from any the command exits with, as GNU env, nice and timeout use them.
OWN_FAILURE = 125
CANNOT_RUN = 126
NOT_FOUND = 127
# Names the slot a command runs in, so a heavy command it runs does not wait for a second slot.
HELD = "RUN_HEAVY_SLOT"
# Seconds between tries while every slot is held; a slot frees as its command exits.
@@ -30,42 +33,20 @@ POLL_SECONDS = 1
USAGE = "usage: run-heavy <command> [<arg>...]"
def slot_count(cpus: int | None) -> int:
return max(1, (cpus or 0) // CPUS_PER_SLOT)
def slot_folder(env: typing.Mapping[str, str]) -> pathlib.Path:
state = env.get("XDG_STATE_HOME") or str(pathlib.Path.home() / ".local" / "state")
return pathlib.Path(state) / "run-heavy"
def taken_slot(folder: pathlib.Path, slots: int) -> tuple[int, int] | None:
"""The number and open file of a slot this call locked; None while every slot is held."""
for slot in range(slots):
fd = os.open(folder / f"slot-{slot}", os.O_RDWR | os.O_CREAT, 0o644)
try:
fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
except BlockingIOError:
os.close(fd)
continue
return slot, fd
return None
def main(argv: list[str], env: typing.Mapping[str, str]) -> int:
if argv[:1] in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
if not argv:
print(f"run-heavy: no command given; {USAGE}", file=sys.stderr)
return 1
return OWN_FAILURE
if HELD not in env:
folder = slot_folder(env)
try:
folder.mkdir(parents=True, exist_ok=True)
except OSError as failure:
print(f"run-heavy: cannot make the slot folder {folder}: {failure.strerror}", file=sys.stderr)
return 1
return OWN_FAILURE
slots = slot_count(os.cpu_count())
said = False
while (taken := taken_slot(folder, slots)) is None:
@@ -79,6 +60,9 @@ def main(argv: list[str], env: typing.Mapping[str, str]) -> int:
env = {**env, HELD: str(slot)}
try:
os.execvpe(argv[0], argv, env)
except FileNotFoundError:
print(f"run-heavy: {argv[0]}: command not found", file=sys.stderr)
return NOT_FOUND
except OSError as failure:
print(f"run-heavy: cannot run {argv[0]}: {failure.strerror}", file=sys.stderr)
return 127
return CANNOT_RUN
+15 -16
View File
@@ -10,17 +10,12 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from machine_load.slots import slot_count
from run_heavy import main
TOOL = pathlib.Path(__file__).resolve().parents[1] / "run-heavy"
class SlotCount(unittest.TestCase):
def test_one_slot_per_four_cpus_and_never_none(self):
for cpus, slots in ((16, 4), (8, 2), (7, 1), (4, 1), (1, 1), (None, 1)):
self.assertEqual(main.slot_count(cpus), slots, cpus)
class RunHeavy(unittest.TestCase):
def setUp(self):
state = tempfile.TemporaryDirectory()
@@ -41,14 +36,14 @@ class RunHeavy(unittest.TestCase):
def every_slot_held(self):
self.slots.mkdir(parents=True, exist_ok=True)
with contextlib.ExitStack() as held:
for slot in range(main.slot_count(os.cpu_count())):
for slot in range(slot_count(os.cpu_count())):
file = held.enter_context(open(self.slots / f"slot-{slot}", "a"))
fcntl.flock(file, fcntl.LOCK_EX | fcntl.LOCK_NB)
yield
def free_slots(self) -> int:
free = 0
for slot in range(main.slot_count(os.cpu_count())):
for slot in range(slot_count(os.cpu_count())):
with open(self.slots / f"slot-{slot}", "a") as file:
try:
fcntl.flock(file, fcntl.LOCK_EX | fcntl.LOCK_NB)
@@ -64,9 +59,9 @@ class RunHeavy(unittest.TestCase):
def test_holds_a_slot_while_the_command_runs_and_frees_it_after(self):
tool = self.start_tool("sh", "-c", "echo started; read line")
self.assertEqual(tool.stdout.readline(), "started\n")
self.assertEqual(self.free_slots(), main.slot_count(os.cpu_count()) - 1)
self.assertEqual(self.free_slots(), slot_count(os.cpu_count()) - 1)
tool.communicate("\n", timeout=30)
self.assertEqual(self.free_slots(), main.slot_count(os.cpu_count()))
self.assertEqual(self.free_slots(), slot_count(os.cpu_count()))
def test_waits_while_every_slot_is_held_and_says_so_once(self):
with self.every_slot_held():
@@ -82,14 +77,18 @@ class RunHeavy(unittest.TestCase):
result = self.run_tool("echo", "nested", env={**self.env, main.HELD: "0"})
self.assertEqual((result.returncode, result.stdout), (0, "nested\n"))
def test_a_command_that_cannot_start_exits_127_saying_why(self):
result = self.run_tool("no-such-command-anywhere")
self.assertEqual((result.returncode, result.stdout), (127, ""))
self.assertIn("no-such-command-anywhere", result.stderr)
def test_a_command_not_found_exits_127_and_one_that_cannot_run_126_saying_why(self):
missing = self.run_tool("no-such-command-anywhere")
self.assertEqual((missing.returncode, missing.stdout), (127, ""))
self.assertIn("no-such-command-anywhere", missing.stderr)
with tempfile.NamedTemporaryFile(suffix=".sh") as unrunnable:
denied = self.run_tool(unrunnable.name)
self.assertEqual((denied.returncode, denied.stdout), (126, ""))
self.assertIn(unrunnable.name, denied.stderr)
def test_no_command_exits_1_with_the_usage_and_help_exits_0(self):
def test_no_command_exits_125_with_the_usage_and_help_exits_0(self):
bare = self.run_tool()
self.assertEqual((bare.returncode, bare.stdout), (1, ""))
self.assertEqual((bare.returncode, bare.stdout), (125, ""))
self.assertIn("usage: run-heavy <command>", bare.stderr)
helped = self.run_tool("--help")
self.assertEqual(helped.returncode, 0)
+1 -1
View File
@@ -64,7 +64,7 @@ The cap is 5, `bin/todo_table.py`'s `BUNDLE_MAX_R`, from the same chunks: by the
## machine load: a heavy command waits for one of a slot per 4 CPUs that every session on the machine shares, and loop-claude starts a worker only while a quarter of the machine's memory is available
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. The human 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. A heavy command run inside a slot already held runs at once, so a gate that wraps its own steps cannot wait on itself. The memory wait reads `/proc/meminfo` only, and off Linux a worker starts at once. `bin/run_heavy/main.py` holds the slots, `CLAUDE.md` → "Working with the codebase" has every session use them, and `bin/loop_claude/memory.py` holds the memory share. Valid while one machine runs several loops at once.
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. The human 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. A heavy command run inside a slot already held runs at once, so a gate that wraps its own steps cannot wait on itself. 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. Valid while one machine runs several loops at once.
## 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