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:
@@ -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/
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user