Run each chunk in its own tmux window, up to parallel-chunks at once, and mark a window that waits
CI / tests (pull_request) Failing after 2m56s

This commit is contained in:
2026-11-16 11:59:45 +01:00
parent 7fc64d860a
commit eecb0387ca
28 changed files with 883 additions and 209 deletions
+2 -2
View File
@@ -71,7 +71,7 @@ git config filter.settings.clean bin/settings_filter.py
Then pick a model with `/model`.
Link `loop-claude` onto `PATH`: `ln -s ~/.claude/bin/loop-claude ~/.local/bin/loop-claude`. Every claude it starts, the interactive ones included, skips every permission prompt.
Link `loop-claude` onto `PATH`: `ln -s ~/.claude/bin/loop-claude ~/.local/bin/loop-claude`. Every claude it starts, the interactive ones included, skips every permission prompt. It runs each chunk in its own window of a tmux session per project, so it needs tmux 3.2 or later.
To get loop-claude's questions and stops as DMs from a bot, write the bot's token, your username or member ID and, for Mattermost, the server into `~/.claude-projects/<key>.env`, in the keys `~/.claude/bin/notify --help` names, run `chmod 600` on it, and add `env-file = "~/.claude-projects/<key>.env"` and `notifier = "mattermost"` (or `"slack"`) to the project's config, as Install → "Set up a project" describes.
@@ -105,7 +105,7 @@ A project may also set `notifier` to `"mattermost"` or `"slack"`, the service th
A project's config may set four more things, each optional, as `project-config --help` describes. `language` names the language its owners write in, where that isn't English: the worker writes the project's prose in it, and the prose reviewer judges the prose in it. `commit-title`, `pull-request-title` and `branch` are templates for a project that titles and names these in another way than `CLAUDE.md` → "Git, commits, and PRs" says. `chunk-preflight` names the branch and the worktree by the `branch` template. On a branch that fits it, rule-hook refuses a commit, and `chunk-pr` a pull request, whose title doesn't fit its template; on any other branch, such as a release review's, a title is the summary alone. A tool that reads a commit title, such as a round's `Answer <pass> round <n>:`, reads the template's `{summary}`: it tries `commit-title`, then `pull-request-title`, since a squash merge titles the commit as the pull request, then takes the title whole. While a project's config holds a fault, rule-hook refuses every commit there, and the tools that read its titles fail naming the fault.
A legacy project with no container setup sets `tooling-on-host = true`, so the loop runs its language runtime, package manager, tests and task runner directly on the host. One whose code the comprehension panel scores low may lower `readability-floor` from 7.0: under it, the ranking weighs code health 4 times as much, and a scoring run asks for a floor item.
A legacy project with no container setup sets `tooling-on-host = true`, so the loop runs its language runtime, package manager, tests and task runner directly on the host. One whose code the comprehension panel scores low may lower `readability-floor` from 7.0: under it, the ranking weighs code health 4 times as much, and a scoring run asks for a floor item. To run more than one chunk at once, set `parallel-chunks` to how many; left out, it is 1.
A project whose pull requests need a human's approval sets `wait-for-approval = true` in its config. `chunk-pr merge` then waits, once the checks have passed, until GitHub reports the pull request approved as its branch protection requires, and merges it. It refuses on Gitea, where a reviewer requested changes and where the protection requires no review. While it waits, other chunks merge. It stops where a reviewer's comment waits for an answer, on an approved pull request too; answer it and run it again. It gives up after 90 minutes without an approval; run it again once the pull request is approved. Left out, the setting is false.
+7 -3
View File
@@ -25,8 +25,8 @@ def plan_name(default: str, outside: str | None) -> str:
return outside if outside else f"{default}'s todo.md"
def planned(todo: plan_stores.Plan | Failure, cut: LastCut, default: str, branch: str, outside: str | None = None) -> Plan | NoItem:
"""todo, which is the project's plan as its store read it and which plan_name names, with the item the next chunk takes first, release_standing.chunk_item's pick; else why there is none. branch is the project's `branch` template."""
def planned(todo: plan_stores.Plan | Failure, cut: LastCut, default: str, branch: str, outside: str | None = None, item_id: int | None = None) -> Plan | NoItem:
"""todo, which is the project's plan as its store read it and which plan_name names, with the item the next chunk takes first: the item of item_id where one is given, else release_standing.chunk_item's pick. Else why there is none. branch is the project's `branch` template."""
where = plan_name(default, outside)
if isinstance(todo, NoItemsTable):
return NoItem(f"{where} holds no items table.")
@@ -56,7 +56,11 @@ def planned(todo: plan_stores.Plan | Failure, cut: LastCut, default: str, branch
moved = [(was, now) for was, now in zip(found, held) if was.release != now.release]
# Every carried item takes one release, the next.
over = CarriedOver(moved[0][1].release, tuple(was.id for was, _ in moved)) if moved else None
return Plan(held, first, f"{first.tagline}\n\n{first.detail}".strip(), branch, over)
if item_id is not None:
first = next((item for item in held if item.id == item_id), None)
if first is None:
return NoItem(f"{where} holds no item {item_id}, the one --item names; it may have shipped.")
return Plan(held, first, f"{first.tagline}\n\n{first.detail}".strip(), branch, over, item_id is not None)
def worktree_on(porcelain: str, branch: str) -> pathlib.Path | None:
+1 -1
View File
@@ -45,7 +45,7 @@ def item_lines(plan: str, item: ItemFacts) -> list[str]:
first = item.plan.first
worktree = item.worktree.reason if isinstance(item.worktree, Failure) else f"{item.worktree.path}, {item.worktree.how}"
return [
f"- The {'next release, after the last cut, that ' + plan + ' names' if item.plan.carried else 'earliest release in ' + plan}: {version(first.release)}. Its first item that does not wait: item {first.id}, {levels(first)}.",
f"- The {'next release, after the last cut, that ' + plan + ' names' if item.plan.carried else 'earliest release in ' + plan}: {version(first.release)}. {'The item this chunk starts from, named with --item' if item.plan.named else 'Its first item that does not wait'}: item {first.id}, {levels(first)}.",
*carried_lines(item.plan),
f"- Worktree: {worktree}",
f"- Open pull requests from {item.plan.branch}: {pulls_text(item.pulls, item.plan.branch)}",
+2
View File
@@ -38,6 +38,8 @@ class Plan:
branch_template: str
# The items of a release already cut, which `items` and `first` hold as the next release's. None where every item's release is after the last cut.
carried: CarriedOver | None = None
# Whether --item named first, in place of the next release's first item that does not wait.
named: bool = False
@property
def branch(self) -> str:
+16 -11
View File
@@ -1,6 +1,6 @@
"""Find the mechanical facts a chunk starts from, so its worker starts from them; with --worktree, also make its worktree.
usage: chunk-preflight [--worktree]
usage: chunk-preflight [--worktree] [--item <ID>]
Run it inside a project checkout. It fetches origin, when the checkout has that remote, and takes
origin's default branch, or else the local main or master. Without --worktree, it still fetches,
@@ -10,7 +10,9 @@ and quotes what it prints in the worker's prompt. It leaves the checkout as it i
todo.md as the default branch holds it, the plan loop-claude routes on. Where the project's config
puts todo.md or CHANGELOG.md outside the checkout, it reads that file as it stands. Such a plan
no longer names a release whose last item has shipped, so chunk-preflight doesn't see that release,
and prints that the release reviews and the cuts are the human's to call. It prints:
and prints that the release reviews and the cuts are the human's to call. With --item, the item is
the plan item of that ID, in place of the next release's first item that does not wait: loop-claude
names the item of each chunk it starts beside another. It prints:
- the last version cut: the newest v* tag on the default branch, or on a branch with no tag the
newest version CHANGELOG.md heads `## X.Y.Z - YYYY-MM-DD`; an undated heading doesn't count.
@@ -65,7 +67,7 @@ running after {timeout} seconds, or after the seconds CHUNK_PREFLIGHT_TIMEOUT se
stopped fetch reads origin as last fetched. With no item, it makes no worktree and runs none of
those four tools, --worktree or not.
Exit 1, saying why, on any argument other than --worktree, -h or --help, on a
Exit 1, saying why, on any argument other than --worktree, --item with an ID, -h or --help, on a
CHUNK_PREFLIGHT_TIMEOUT that is no number of seconds above 0, when git cannot start or finds no
checkout or no default branch, or when no config names the checkout or its config cannot be read.
"""
@@ -92,16 +94,19 @@ TIMEOUT = 60
TIMEOUT_SETTING = "CHUNK_PREFLIGHT_TIMEOUT"
# The flag that makes the item's worktree and runs TOOLS in it. Three readers seated as the README's audience picked it 2-1 over --start.
WORKTREE = "--worktree"
# The flag that names the chunk's item. Three readers seated as the README's audience picked it 3-0 over --for, --start and a bare ID.
ITEM = "--item"
def main(argv: list[str], env: typing.Mapping[str, str]) -> int:
if argv in (["-h"], ["--help"]):
print(__doc__.strip().format(timeout=TIMEOUT, JOINING_DETAILS=JOINING_DETAILS))
return 0
if argv not in ([], [WORKTREE]):
print(f"unknown arguments {' '.join(argv)}; usage: chunk-preflight [{WORKTREE}]", file=sys.stderr)
rest = [arg for arg in argv if arg != WORKTREE]
if len(argv) - len(rest) > 1 or not (rest == [] or (len(rest) == 2 and rest[0] == ITEM and re.fullmatch(r"[0-9]+", rest[1], re.ASCII))):
print(f"unknown arguments {' '.join(argv)}; usage: chunk-preflight [{WORKTREE}] [{ITEM} <ID>]", file=sys.stderr)
return 1
printed = run(env.get(TIMEOUT_SETTING), argv == [WORKTREE])
printed = run(env.get(TIMEOUT_SETTING), WORKTREE in argv, int(rest[1]) if rest else None)
if isinstance(printed, Failure):
print(printed.reason, file=sys.stderr)
return 1
@@ -109,13 +114,13 @@ def main(argv: list[str], env: typing.Mapping[str, str]) -> int:
return 0
def run(setting: str | None, make: bool) -> list[str] | Failure:
"""The preflight's lines, given the setting TIMEOUT_SETTING holds and whether to make the item's worktree; a Failure where the setting is no number of seconds above 0, or git finds no checkout or no default branch."""
def run(setting: str | None, make: bool, item_id: int | None = None) -> list[str] | Failure:
"""The preflight's lines, given the setting TIMEOUT_SETTING holds, whether to make the item's worktree, and the ID --item names; a Failure where the setting is no number of seconds above 0, or git finds no checkout or no default branch."""
timeout = seconds(setting)
if isinstance(timeout, Failure):
return timeout
root = top()
return root if isinstance(root, Failure) else preflight(pathlib.Path(root), timeout, make)
return root if isinstance(root, Failure) else preflight(pathlib.Path(root), timeout, make, item_id)
def seconds(setting: str | None) -> float | Failure:
@@ -127,7 +132,7 @@ def seconds(setting: str | None) -> float | Failure:
return Failure(f"{TIMEOUT_SETTING}={setting!r} is no number of seconds above 0")
def preflight(root: pathlib.Path, timeout: float, make: bool) -> list[str] | Failure:
def preflight(root: pathlib.Path, timeout: float, make: bool, item_id: int | None) -> list[str] | Failure:
"""Gathers the facts step by step, each step taking what the ones before it found, and renders them; a Failure where the checkout has no default branch."""
default = default_branch(stale_ok=True, timeout=timeout)
if isinstance(default, Failure):
@@ -138,7 +143,7 @@ def preflight(root: pathlib.Path, timeout: float, make: bool) -> list[str] | Fai
return config
outside = None if config.tracked("plan") else config.plan_label
held = project_plan(config, ref, str(root))
plan = planned(held.todo, held.cut, ref, config.branch, outside)
plan = planned(held.todo, held.cut, ref, config.branch, outside, item_id)
item = plan if isinstance(plan, NoItem) else item_facts(root, ref, plan, timeout, make)
# A `checkout:` path lands in the worktree the chunk works in.
made = located(str(item.worktree.path), pathlib.Path.home()) if isinstance(item, ItemFacts) and isinstance(item.worktree, Worktree) else config
@@ -319,6 +319,29 @@ class ChunkPreflightTool(unittest.TestCase):
self.assertFalse((repo.temp / "proj-item-3").exists())
self.assertNotIn("item-3", repo.git(repo.root, "branch", "--list"))
def test_item_names_the_item_the_chunk_starts_from_in_place_of_the_plans_next(self):
repo = Repo(self)
for args in (["--item", "7"], ["--worktree", "--item", "7"], ["--item", "7", "--worktree"]):
with self.subTest(args):
done = repo.preflight(*args)
self.assertEqual((done.returncode, done.stderr), (0, ""))
self.assertIn("0.2.0. The item this chunk starts from, named with --item: item 7, L 1, E + I 2.", done.stdout)
self.assertNotIn("Its first item that does not wait", done.stdout)
self.assertTrue((repo.temp / "proj-item-7").is_dir())
self.assertFalse((repo.temp / "proj-item-3").exists())
def test_item_names_no_item_where_the_plan_no_longer_holds_it(self):
done = Repo(self).preflight("--worktree", "--item", "4")
self.assertEqual((done.returncode, done.stderr), (0, ""))
self.assertIn("- No plan item: origin/main's todo.md holds no item 4, the one --item names; it may have shipped. No worktree was made.", done.stdout)
def test_exits_1_on_an_item_that_is_no_id(self):
for args in (["--item"], ["--item", "x"], ["--item", "7", "8"]):
with self.subTest(args):
done = Repo(self).preflight(*args)
self.assertEqual((done.returncode, done.stdout), (1, ""))
self.assertIn(f"unknown arguments {' '.join(args)}; usage: chunk-preflight [--worktree] [--item <ID>]", done.stderr)
def test_exits_1_on_an_argument_other_than_worktree(self):
done = Repo(self).preflight("--start")
self.assertEqual(done.returncode, 1)
+1 -1
View File
@@ -126,7 +126,7 @@ class Main(unittest.TestCase):
result = reply(Rung(args[args.index("--model") + 1], args[args.index("--effort") + 1]), "said Verdict: interrupt" in prompt.rsplit("latest last:", 1)[-1])
return subprocess.CompletedProcess(args, 0, json.dumps(result), "")
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=unused, input=unused, local_time=unused, memory=unused, now=unused, on_terminal=unused, python=unused, sleep=unused, stream_claude=unused)
effects = Effects(claude=claude, claude_on_terminal=unused, tmux=unused, tmux_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=unused, input=unused, local_time=unused, memory=unused, now=unused, on_terminal=unused, python=unused, sleep=unused, stream_claude=unused)
out, err = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
code = main.main(argv, {}, self.home, effects)
+16 -6
View File
@@ -10,6 +10,7 @@ from claude_code.transcript import human_turns, read_transcript
from loop_claude.stop import needs_human, needs_terminal, Stop
from model_routing.ladder import Rung
from loop_claude.direct_message import tell
from loop_claude import tmux
ANSWER_QUESTION = "answer the question above"
# TALK, what the human types at loop-claude's terminal to open claude for the question, and ASK_ANSWER were picked on 2026-10-17 by a bench of three readers seated as the README's audience, as ~/.claude/CLAUDE.md → "Working loop" → "Bench a syntax with the people who write it." has it.
@@ -36,17 +37,26 @@ class Talked:
"""The human typed in the worker's claude session."""
def interrupt(question: str, answer_here: bool, session: WorkerSession, effects: Effects) -> str | Talked | Stop:
"""Prints question for the human and returns their answer: where answer_here, the first line typed at loop-claude's terminal, stripped, or Talked once they typed in the worker's claude session, which TALK opens; else Talked once they typed in that session, which opens at once on the terminal. A Stop where loop-claude is off a terminal, or they type no answer, or the input ends."""
say(f"\n{question}", effects)
def interrupt(question: str, answer_here: bool, session: WorkerSession, window: tmux.Window, effects: Effects) -> str | Talked | Stop:
"""Prints question for the human, in window, and returns their answer. While it waits, the window's name ends in tmux.WAITS, and the bell it rings shows in tmux's status bar. The answer: where answer_here, the first line typed at loop-claude's terminal, stripped, or Talked once they typed in the worker's claude session, which TALK opens; else Talked once they typed in that session, which opens at once on the terminal. A Stop where loop-claude is off a terminal, or they type no answer, or the input ends."""
# The bell ends the question's line, so it rings once the question can be read.
say(f"\n{question}{tmux.BELL}", effects)
on_terminal = effects.on_terminal()
if on_terminal:
# Keys typed while the worker ran wait on the terminal, and would answer a question no one has read, here or in claude's session, which reads them too. Of a pasted answer, the first line answers; the rest wait, and the next question drops them. A longer answer goes through TALK.
effects.discard_typed()
tmux.mark(window, True, effects.tmux)
# After the discard, so an answer typed while the DM sends counts; before the terminal check, so a loop that cannot ask still tells the human what it would have asked.
tell(f"loop-claude in {session.root} asks:\n\n{question}", effects)
if stop := needs_terminal(ANSWER_QUESTION, on_terminal):
return stop
tell(f"loop-claude in {session.root} asks, in the tmux window {window.target}:\n\n{question}", effects)
answer = needs_terminal(ANSWER_QUESTION, on_terminal) or answered(answer_here, session, effects)
# A loop that stops unanswered leaves the mark on its window.
if not isinstance(answer, Stop):
tmux.mark(window, False, effects.tmux)
return answer
def answered(answer_here: bool, session: WorkerSession, effects: Effects) -> str | Talked | Stop:
"""The human's answer, as interrupt returns it."""
answer = typed_answer(effects) if answer_here else TALK
if answer != TALK:
return answer
+5
View File
@@ -53,6 +53,11 @@ def preflight_facts(printed: str) -> str:
return f"loop-claude ran `~/.claude/bin/chunk-preflight` at the checkout root just before this run. Take what it printed as found rather than finding it again:\n\n{printed}"
def held_by_others(items: list[int]) -> str:
"""Keeps a fresh worker off the plan items the project's other running chunks hold."""
return f"\n\nOther chunks of this project run now, and hold {'items ' if len(items) > 1 else 'item '}{', '.join(map(str, items))}. Leave those out of this chunk, whatever else may join it."
def preflight_failed(reason: str) -> str:
"""Has the worker find the facts chunk-preflight would have, its worktree among them."""
return f"loop-claude could not run `~/.claude/bin/chunk-preflight`, so find the chunk's facts yourself. Why it could not run: {reason}"
+4 -1
View File
@@ -24,6 +24,7 @@ from loop_claude.cycle.retry import retried
from model_routing.route import Route
from loop_claude.cycle import spend
from loop_claude.stop import Stop
from loop_claude.tmux import Window
from model_routing import worker_rungs
@@ -54,6 +55,8 @@ class Cycle:
todo: Plan | Failure
# Empty when the previous cycle's verdict was not Unfinished.
unfinished_evidence: str
# The tmux window the loop runs in, which an interrupt marks.
window: Window
@dataclasses.dataclass(frozen=True)
@@ -198,7 +201,7 @@ def keep_rejection(cycle: Cycle, transcript_path: str, rejected: Rejected) -> St
def ask(cycle: Cycle, transcript_path: str, ruling: Interrupt | QuotedAnswer) -> HumanTyped | HumanTalked | Stop:
"""The human's answer to a ruling that rule archived as it ruled; the human's answer then grows the transcript."""
# Only the human may cut a release, so a release ready to cut opens claude's session at once.
answer = interrupt(question_for(ruling), not (isinstance(ruling, Interrupt) and ruling.release_ready), worker_session(cycle, transcript_path), cycle.effects)
answer = interrupt(question_for(ruling), not (isinstance(ruling, Interrupt) and ruling.release_ready), worker_session(cycle, transcript_path), cycle.window, cycle.effects)
match answer:
case Stop():
return answer
-46
View File
@@ -1,46 +0,0 @@
"""The slot a loop holds in its project, so that loops of one project, each on its own chunk, run side by side, each in a session named after its slot."""
import dataclasses
import os
import pathlib
from failure import Failure
from machine_load.slots import first_free_slot
from loop_claude.loop.reload import LoopRun
from loop_state.paths import Paths
from transcript_archive.project_key import project_key
from claude_code.session import Session, session_named, session_open
# Under the home folder, a folder per project key holds a file per slot, which a running loop keeps locked with flock.
SLOTS = ".local/state/loop-claude"
# A bound no project reaches. Once todo.md item 375 lands, the project's config sets how many loops run at once.
MOST = 64
def held_slot(home: pathlib.Path, key: str, claude_code_transcripts: pathlib.Path) -> int | Failure:
"""The slot this loop takes, or why it could take none: the lowest free slot whose session is open, so that a rerun resumes a chunk left open, or else the lowest free slot. The loop holds it until it exits; a reload's exec keeps the lock."""
folder = home / SLOTS / key
order = sorted(range(MOST), key=lambda slot: not session_open(session_named(session_name(key, slot), claude_code_transcripts)))
try:
folder.mkdir(parents=True, exist_ok=True)
taken = first_free_slot(folder, order)
except OSError as failure:
return Failure(f"cannot take a slot in {folder}: {failure.strerror}")
if taken is None:
return Failure(f"{MOST} loops of this project are running already; `fuser {folder}/slot-*` names them")
slot, fd = taken
os.set_inheritable(fd, True)
return slot
def session_name(key: str, slot: int) -> str:
""""A " is the human's cue in the session picker that the session is the loop's. Slot 0 keeps the name every loop had before slots, so a chunk left open before slots resumes in it."""
return f"A {key} loop-claude" if slot == 0 else f"A {key} loop-claude {slot + 1}"
def slotted(loop_run: LoopRun, paths: Paths) -> tuple[LoopRun, Session] | Failure:
"""loop_run holding its slot, and the worker's session, named after the slot. A reloaded script keeps the slot it is handed."""
key = project_key(loop_run.root, paths.home)
slot = held_slot(paths.home, key, paths.claude_code_transcripts) if loop_run.slot is None else loop_run.slot
if isinstance(slot, Failure):
return slot
return dataclasses.replace(loop_run, slot=slot), session_named(session_name(key, slot), paths.claude_code_transcripts)
+11 -7
View File
@@ -7,6 +7,8 @@ from release_plan.release_standing import DefaultPlan, project_plan, UNSEEN_RELE
from loop_effects.effects import Effects, say
from failure import Failure
from loop_claude.routing import first_route, kept, routed_item
from loop_claude.loop.chunk_windows import held_beside, item_of
from chunk_preflight.main import ITEM
from plan_store.stores import held_at, Plan, store as plan_store
from release_plan.todo_table import Item
from model_routing.ladder import Ladder, Rung
@@ -61,15 +63,17 @@ def archived_route(archive_folder: pathlib.Path, loop: Loop) -> Route | None:
def chunk_start(loop: Loop) -> tuple[str, typing.Callable[[], Item | None]]:
"""The facts for a fresh worker's prompt, empty where the session is open, and the reader of the item that routes the chunk. The reader reads the default branch as last fetched: for a fresh chunk, by the preflight that runs first; for an open session, which runs none, by whatever fetched last."""
facts = "" if session_open(loop.session) else chunk_facts(loop)
return facts, lambda: plan_item(fetched_plan(loop), loop.effects)
return facts, lambda: plan_item(fetched_plan(loop), item_of(loop.window.name), loop.effects)
def chunk_facts(loop: Loop) -> str:
"""What `chunk-preflight --worktree` printed at the checkout root, for a fresh worker's prompt, or why it could not run."""
done = loop.effects.python([str(loop.launcher.with_name("chunk-preflight")), "--worktree"], loop.root)
"""What `chunk-preflight --worktree` printed at the checkout root, for a fresh worker's prompt, or why it could not run. The chunk of a window named for an item starts from that item, and the facts end with the items the project's other running chunks hold."""
item = item_of(loop.window.name)
done = loop.effects.python([str(loop.launcher.with_name("chunk-preflight")), "--worktree", *([] if item is None else [ITEM, str(item)])], loop.root)
if done.returncode:
return prompts.preflight_failed(done.stderr.strip() or f"it exited {done.returncode}")
return prompts.preflight_facts(done.stdout.strip())
held = held_beside(loop.window.name, loop.root, loop.paths, loop.effects)
return prompts.preflight_facts(done.stdout.strip()) + (prompts.held_by_others(held) if held else "")
def fetched_plan(loop: Loop) -> DefaultPlan | Failure:
@@ -83,13 +87,13 @@ def fetched_plan(loop: Loop) -> DefaultPlan | Failure:
return ref if isinstance(ref, Failure) else project_plan(config, ref, loop.root, loop.effects.git)
def plan_item(plan: DefaultPlan | Failure, effects: Effects) -> Item | None:
"""The item that routes a chunk, release_standing.chunk_item's pick from the default branch; None without one, so the chunk runs on the project's rung."""
def plan_item(plan: DefaultPlan | Failure, window_item: int | None, effects: Effects) -> Item | None:
"""The item that routes a chunk: the one its window is named for, or else release_standing.chunk_item's pick from the default branch; None without one, so the chunk runs on the project's rung."""
# It prints the reason itself, through effects, like the other loop-claude functions that print. todo.md item 51 moves them all to one injected effect, so changing this one alone would be undone.
if isinstance(plan, Failure):
item: Item | Failure | None = plan
else:
item = routed_item(plan.todo, plan.cut)
item = routed_item(plan.todo, plan.cut, window_item)
if isinstance(item, Failure):
say(f"routing on the project's rung: {item.reason}", effects)
return None
+138
View File
@@ -0,0 +1,138 @@
"""The chunks of one project that run at once, each in its own tmux window: which may start now, and how each starts (docs/decisions.md → `loop-claude: each chunk runs in its own tmux window`)."""
import contextlib
import fcntl
import pathlib
import re
import typing
from chunk_preflight.choices import planned
from chunk_preflight.gathered import NoItem, Plan
from claude_code.session import Session, session_named, transcript_file
from claude_code.transcript import read_transcript
from failure import Failure
from git_cli.git_repo import default_ref
from loop_claude import tmux
from loop_claude.cycle import chunk_items
from loop_claude.loop.reload import LoopRun
from loop_effects.effects import Effects, say
from loop_state.paths import Paths
from project_config.main import located
from release_plan.release_standing import project_plan
from touch_predictions.beside import Beside, chunks_beside
from transcript_archive.project_key import project_key
# Under the home folder, a folder per project key holds LOCK.
STATE = ".local/state/loop-claude"
# The file a loop keeps locked with flock while it lists the project's windows and starts new ones, so two loops whose chunks finish together start no chunk twice.
LOCK = "starting"
# loop-claude's own flag: the loop it starts in a window is told its chunk by it, as `--chunk item-372`. Nobody types it, so no panel picked it.
CHUNK_FLAG = "--chunk"
# The chunk of a plan that names no item for the next chunk: a release to plan, a release review, or a task outside the plan.
NO_ITEM = "no-item"
# Seconds a fetch of origin may take before a chunk starts; past them, the plan reads as last fetched.
FETCH_TIMEOUT = 60
# The variables loop-claude reads. A window gets the tmux server's environment, not the starting terminal's, so they are handed to each window by name.
HANDED = "LOOP_CLAUDE_"
def window_name(item_id: int) -> str:
return f"item-{item_id}"
def item_of(chunk: str) -> int | None:
"""The ID of the plan item a chunk starts from; None for NO_ITEM."""
named = re.fullmatch(r"item-([0-9]+)", chunk, re.ASCII)
return int(named[1]) if named else None
def chunk_session(key: str, chunk: str, claude_code_transcripts: pathlib.Path) -> Session:
"""The worker's session for a chunk. A rerun finds a chunk left open by this name. "A " is the human's cue in the session picker that the session is the loop's."""
return session_named(f"A {key} loop-claude {chunk}", claude_code_transcripts)
@contextlib.contextmanager
def starting(home: pathlib.Path, key: str) -> typing.Iterator[None]:
"""Holds the project's LOCK. Raises OSError where the file cannot be opened or locked."""
folder = home / STATE / key
folder.mkdir(parents=True, exist_ok=True)
with open(folder / LOCK, "a") as lock:
fcntl.flock(lock, fcntl.LOCK_EX)
yield
def held_items(chunks: typing.Iterable[str], key: str, claude_code_transcripts: pathlib.Path) -> set[int]:
"""The plan items these chunks hold: the one each started from, and those its worker names on its latest `Chunk items:` line so far. A chunk whose transcript cannot be read holds the item it started from."""
held = set()
for chunk in chunks:
held.update(filter(None, [item_of(chunk)]))
transcript = transcript_file(chunk_session(key, chunk, claude_code_transcripts))
entries = read_transcript(transcript) if transcript else []
held.update([] if isinstance(entries, Failure) else chunk_items.named(entries))
return held
def may_start(plan: Plan | NoItem, running: list[str], held: set[int], limit: int) -> list[str]:
"""The chunks to start now, beside those running, whose items are held: the plan's next item and the items touch_predictions picks to run beside it, in the plan's order, less each a running chunk holds, up to limit chunks at once. A plan without an item starts NO_ITEM, and only alone."""
if isinstance(plan, NoItem):
return [] if running else [NO_ITEM]
beside = chunks_beside(plan.items, plan.first)
picked = [plan.first.id, *(beside.picked if isinstance(beside, Beside) else [])]
return [window_name(item_id) for item_id in picked if item_id not in held][: max(limit - len(running), 0)]
def next_plan(root: str, home: pathlib.Path, effects: Effects) -> Plan | NoItem | Failure:
"""The plan on the default branch, fetched now where origin answers, with its next item, as chunk-preflight reads it."""
config = located(root, home)
if isinstance(config, Failure):
return config
# A chunk that just merged left the plan on origin. A fetch that fails leaves the plan as last fetched, which chunk-preflight then reads too.
effects.git("fetch", "--quiet", "origin", cwd=root, timeout=FETCH_TIMEOUT)
ref = default_ref(root, FETCH_TIMEOUT, run=effects.git)
if isinstance(ref, Failure):
return ref
held = project_plan(config, ref, root, effects.git)
return planned(held.todo, held.cut, ref, config.branch, None if config.tracked("plan") else config.plan_label)
def start_chunks(loop_run: LoopRun, leaving: bool, paths: Paths, env: typing.Mapping[str, str], launcher: pathlib.Path, effects: Effects) -> list[str] | Failure:
"""Starts a loop-claude in a new window for each chunk of loop_run's project that may start now, and returns the chunks started. leaving says that loop_run's own chunk finished, so its window no longer counts as running. A plan that cannot be read starts NO_ITEM, as a plan without an item does. A Failure says why none could start."""
config = located(loop_run.root, paths.home)
if isinstance(config, Failure):
return config
key = project_key(loop_run.root, paths.home)
session = tmux.session_name(key)
handed = {name: value for name, value in env.items() if name.startswith(HANDED)}
try:
with starting(paths.home, key):
windows = tmux.listed(session, effects.tmux)
running = [window.name for window in windows if not window.dead and not (leaving and window.name == loop_run.chunk)]
if len(running) >= config.parallel_chunks:
return []
plan = next_plan(loop_run.root, paths.home, effects)
if isinstance(plan, Failure):
# As in a checkout without a default branch. The chunk's worker is told why its preflight failed, and finds the facts itself.
say(f"starting a chunk without a plan item, since the plan cannot be read: {plan.reason}", effects)
plan = NoItem(plan.reason)
chunks = may_start(plan, running, held_items(running, key, paths.claude_code_transcripts), config.parallel_chunks)
for chunk in chunks:
# The window of a loop that failed stays, dead, until its chunk starts again.
stale = [window for window in windows if window.name == chunk and window.dead]
for window in stale:
tmux.close(window, effects.tmux)
windows = [window for window in windows if window not in stale]
command = [str(launcher), CHUNK_FLAG, chunk, loop_run.task]
if failed := tmux.start_window(tmux.Window(session, chunk, ""), loop_run.root, handed, command, not windows, effects.tmux):
return failed
windows.append(tmux.Listed(chunk, "", False))
return chunks
except OSError as failure:
return Failure(f"cannot lock {paths.home / STATE / key / LOCK}: {failure.strerror}")
def held_beside(chunk: str, root: str, paths: Paths, effects: Effects) -> list[int]:
"""The plan items that the project's other running chunks hold now, which a chunk starting as `chunk` leaves to them. It waits for a loop that is starting windows, so chunks started together see each other. Where the lock cannot be taken, it reads the windows without it."""
key = project_key(root, paths.home)
with contextlib.suppress(OSError), starting(paths.home, key):
pass
others = [window.name for window in tmux.listed(tmux.session_name(key), effects.tmux) if not window.dead and window.name != chunk]
return sorted(held_items(others, key, paths.claude_code_transcripts))
+45 -11
View File
@@ -20,7 +20,9 @@ from transcript_archive.project_key import project_key
from model_routing.ladder_file import project_ladder_file, read_ladder, SHIPPED
from loop_claude.project.premises import read_premises
from loop_claude.project.records import read_records
from loop_claude.loop.chunk_slot import slotted
from loop_claude.loop.chunk_windows import CHUNK_FLAG, chunk_session, start_chunks
from loop_claude import tmux
from loop_claude.verdicts import Finished
from loop_claude.stop import Stop
from loop_claude.direct_message import tell
@@ -35,8 +37,8 @@ def main(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher:
raise
if stop.reason:
say(stop.reason, effects, stdout=not stop.code)
# Every stop but the human's own Ctrl-C and the help is DMed where the project's config can be read and sets `env-file`, so a loop left overnight never ends unseen. A loop given no task prints the help.
if stop.code != 130 and stop.reason != HELP:
# Every stop with a reason, but the human's own Ctrl-C and the help, is DMed where the project's config can be read and sets `env-file`, so a loop left overnight never ends unseen. A loop given no task prints the help. One that started the project's windows, or whose chunk finished and handed on to the next, stops without a reason: the project's chunks go on.
if stop.code != 130 and stop.reason not in ("", HELP):
tell(f"loop-claude in {cwd} stopped: {stop.reason}", effects)
return stop.code
@@ -45,12 +47,18 @@ def run_loop(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launc
loop_run = loop_run_from(argv, cwd, effects)
if isinstance(loop_run, Stop):
return loop_run
# Before anything starts: a worktree, a session or a window.
if reason := tmux.unusable(effects.tmux):
return Stop(1, reason)
if loop_run.chunk is None:
return windows_opened(loop_run, env, paths, launcher, effects)
pane = env.get("TMUX_PANE")
if not pane:
return Stop(1, f"{CHUNK_FLAG} is how loop-claude starts itself in a tmux window; run loop-claude <task>")
baseline = fingerprint(launcher)
held = slotted(loop_run, paths)
if isinstance(held, Failure):
return Stop(1, held.reason)
loop_run, session = held
loop = Loop(root=loop_run.root, session=session, paths=paths, env=env, launcher=launcher, effects=effects)
key = project_key(loop_run.root, paths.home)
window = tmux.Window(tmux.session_name(key), loop_run.chunk, pane)
loop = Loop(root=loop_run.root, session=chunk_session(key, loop_run.chunk, paths.claude_code_transcripts), window=window, paths=paths, env=env, launcher=launcher, effects=effects)
while True:
if stop := exec_if_edited(loop, baseline, loop_run):
return stop
@@ -68,6 +76,31 @@ def run_loop(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launc
# Off the ladder the worker runs on the project's model itself, which its route names.
if stop := check_routing(archive_root(paths.home, env), cycle.project or cycle.route.rung, loop):
return stop
if isinstance(concluded.verdict, Finished):
return handed_on(loop_run, loop)
def windows_opened(loop_run: LoopRun, env: typing.Mapping[str, str], paths: Paths, launcher: pathlib.Path, effects: Effects) -> Stop:
"""What the loop-claude the human runs does: starts each chunk that may start now in a window of the project's tmux session, then puts that session on the terminal until the human detaches."""
started = start_chunks(loop_run, False, paths, env, launcher, effects)
if isinstance(started, Failure):
return Stop(1, started.reason)
session = tmux.session_name(project_key(loop_run.root, paths.home))
say(f"started {', '.join(started)} in the tmux session {session}" if started else f"the tmux session {session} runs every chunk that may run now", effects, stdout=True)
if not effects.on_terminal():
say(f"not on a terminal; see the chunks with `tmux attach -t ={session}`", effects, stdout=True)
return Stop(0, "")
shown = tmux.show(session, "TMUX" in env)
return Stop(1, f"`tmux {' '.join(shown)}` failed; the chunks go on in the session") if effects.tmux_on_terminal(shown) else Stop(0, "")
def handed_on(loop_run: LoopRun, loop: Loop) -> Stop:
"""The stop of a loop whose chunk finished, once it has started each chunk that may start now. Its window closes as it exits."""
started = start_chunks(loop_run, True, loop.paths, loop.env, loop.launcher, loop.effects)
if isinstance(started, Failure):
return Stop(1, f"the chunk finished, but the next could not start: {started.reason}")
say(f"the chunk finished; started {', '.join(started) or 'no other, since the chunks running fill what may run now'}", loop.effects, stdout=True)
return Stop(0, "")
def next_cycle(loop_run: LoopRun, loop: Loop) -> Cycle | Stop:
@@ -96,7 +129,7 @@ def next_cycle(loop_run: LoopRun, loop: Loop) -> Cycle | Stop:
if ladder_file != SHIPPED:
say(own_ladder(ladder_file, models.worker, project is None), loop.effects)
todo = fetched_todo(loop)
return Cycle(config=setup_version(loop.paths.claude_dir, loop.effects.git), effects=loop.effects, facts=facts, judge_model=models.judge, ladder=ladder, premises=premises, project=project, project_archive=archive_folder, records=records, root=loop.root, route=route, session=loop.session, task=loop_run.task, todo=todo, unfinished_evidence=loop_run.unfinished_evidence)
return Cycle(config=setup_version(loop.paths.claude_dir, loop.effects.git), effects=loop.effects, facts=facts, judge_model=models.judge, ladder=ladder, premises=premises, project=project, project_archive=archive_folder, records=records, root=loop.root, route=route, session=loop.session, task=loop_run.task, window=loop.window, todo=todo, unfinished_evidence=loop_run.unfinished_evidence)
def own_ladder(file: pathlib.Path, model: str, unrouted: bool) -> str:
@@ -107,11 +140,12 @@ def own_ladder(file: pathlib.Path, model: str, unrouted: bool) -> str:
def loop_run_from(argv: list[str], cwd: pathlib.Path, effects: Effects) -> LoopRun | Stop:
if argv[:1] != [RELOAD_FLAG]:
task = " ".join(argv)
chunk, words = (argv[1], argv[2:]) if len(argv) > 2 and argv[0] == CHUNK_FLAG else (None, argv)
task = " ".join(words)
if task in ("", "-h", "--help"):
return Stop(0 if task else 1, HELP)
root = checkout_root(cwd, effects)
return root if isinstance(root, Stop) else LoopRun(0, root, task, "")
return root if isinstance(root, Stop) else LoopRun(0, root, task, "", chunk=chunk)
loop_run = decode_handed(argv[1]) if len(argv) == 2 else None
if not (loop_run and loop_run.root and loop_run.task):
return Stop(1, f"the edited loop-claude cannot read the state the running one handed it, likely because the edit changed that handover; rerun loop-claude <task>. Handed: {' '.join(argv[1:])}")
+5 -3
View File
@@ -25,8 +25,8 @@ class LoopRun:
route: Route | None = None
# How many unfinished verdicts the chunk has had running; a finished chunk and a rerun each set it to 0. It stays apart from route and unfinished_evidence, though all three change together at each verdict: merging or renaming a field stops a running loop at its next reload.
unfinished_run: int = 0
# The project's slot this loop holds (chunk_slot.py); None until it takes one. A loop started before slots reloads with None, and so takes a slot then.
slot: int | None = None
# The chunk this loop runs in its tmux window, as chunk_windows names it: `item-372`, or `no-item`. None for the loop-claude the human started, which starts the windows; a loop started before chunks ran in windows reloads with None too, and so moves its chunk into one.
chunk: str | None = None
class Unreadable(Exception):
@@ -40,8 +40,10 @@ def decode_handed(handed: str) -> LoopRun | None:
except ValueError:
return None
# A loop started before 0.11.0 hands the items loop-inbox listed; dropping them keeps it running across its reload.
# One started before chunks ran in tmux windows hands the slot it held.
if isinstance(fields, dict):
fields.pop("items_taken_in", None)
fields.pop("slot", None)
try:
return LoopRun(**decoded_fields(fields, LOOP_RUN_FIELDS, "cycle_number", "root", "task", "unfinished_evidence"))
except Unreadable:
@@ -77,7 +79,7 @@ def decoded_route(value: object) -> Route | None:
# One decoder per field of LoopRun, which a test holds to the dataclass's fields: a field missing here stops a loop at the reload after it joined.
LOOP_RUN_FIELDS = {"cycle_number": exactly(int), "root": exactly(str), "task": exactly(str), "unfinished_evidence": exactly(str), "route": decoded_route, "unfinished_run": exactly(int), "slot": lambda value: None if value is None else exactly(int)(value)}
LOOP_RUN_FIELDS = {"cycle_number": exactly(int), "root": exactly(str), "task": exactly(str), "unfinished_evidence": exactly(str), "route": decoded_route, "unfinished_run": exactly(int), "chunk": lambda value: None if value is None else exactly(str)(value)}
def fingerprint(launcher: pathlib.Path) -> str:
+3
View File
@@ -5,6 +5,7 @@ import typing
from loop_effects.effects import Effects
from loop_state.paths import Paths
from claude_code.session import Session
from loop_claude.tmux import Window
@dataclasses.dataclass(frozen=True)
@@ -14,6 +15,8 @@ class Loop:
root: str
# The worker's session.
session: Session
# The tmux window the loop runs in.
window: Window
paths: Paths
env: typing.Mapping[str, str]
# The loop-claude script, whose edits reload the loop and beside which chunk-preflight lies.
+29 -11
View File
@@ -26,7 +26,9 @@ remaining. The next chunk starts a fresh session. Cycles continue until an exit
Words: ~/.claude/CLAUDE.md → "Vocabulary".
A question only the human can answer is an interrupt (bin/loop_claude/cycle/interrupt.py).
loop-claude prints the question on its terminal, where the human answers it:
loop-claude prints the question in the chunk's window and rings its bell. Until it is answered the
window's name ends in " ?", as in "item-372 ?", which tmux's status bar shows. The human answers
it there:
- A line of text: the worker resumes headless with it. The judge reads it as the human's, so the
chunk stays unfinished until the answer is recorded.
- /talk: opens the worker's session with `claude --resume` on the terminal, to read the diff or
@@ -34,20 +36,33 @@ loop-claude prints the question on its terminal, where the human answers it:
- Enter alone: stops the loop.
A release ready to cut opens that session on the terminal at once, since only the human may cut it.
While claude is open, Ctrl-C reaches it alone, and the loop goes on.
Where the project's config sets notifier, loop-claude also sends the human each question, each
release ready to cut and each stop as a DM, as bin/notify sends it. Two stops are
left out: Ctrl-C, and printing this help. A DM that fails is said on stderr, and the loop goes on.
Where the project's config sets notifier, loop-claude also sends the human each question, naming
its window as <session>:<window>, each release ready to cut and each stop as a DM, as bin/notify
sends it. Four stops are left out: Ctrl-C, printing this help, the loop-claude that started the
windows, and a loop whose chunk finished. A DM that fails is said on stderr, and the loop goes on.
As a chunk starts, before it is routed, loop-claude runs bin/chunk-preflight --worktree and quotes
what it prints in the first prompt (prompts.preflight_facts in bin/loop_claude/cycle/prompts.py);
chunk-preflight --help says what it finds and makes. A preflight that fails, or is still running
chunk-preflight --help says what it finds and makes. For a window named for an item it adds
--item <ID>. A preflight that fails, or is still running
after 600 s and is stopped, leaves the worker to find the facts itself.
Loops of one project run side by side, each on one chunk at a time. Each holds a slot of the
project, the file slot-<n> under ~/.local/state/loop-claude/<key>/, locked while the loop runs.
<key> is the checkout's path relative to ~/code, or to / outside it. A loop takes the lowest free
slot whose session is open, so a rerun resumes a chunk left open, or else the lowest free slot.
slot-0's session is named "A <key> loop-claude", and slot-<n>'s "A <key> loop-claude <n+1>".
Each chunk runs in its own window of one tmux session per project, named loop-<key>, such as
loop-claude-config. <key> is the checkout's path relative to ~/code, or to / outside it, with a
dash for each character tmux reads as a separator. loop-claude <task> starts the chunks that may
start now, then attaches to the session, or switches to it inside tmux; detaching leaves the chunks
running. Off a terminal it prints the command that attaches. Up to parallel-chunks chunks run at
once, a whole number the project's config sets, 1 by default. The first starts from the plan's next
item, and each other from an item whose `Touches:` prediction overlaps none before it
(touch-predictions --help). A window is named for the item its chunk starts from, as item-372; a
chunk without a plan item, such as planning a release or its release review, runs alone in the
window no-item. Each window runs a loop-claude for that one chunk, started with --chunk <window>,
which nobody types. As a chunk finishes, its loop starts each chunk that may start then and exits,
which closes its window. The window of a loop that failed stays, with its last lines, until its
chunk starts again. A chunk's session is named "A <key> loop-claude <window>", so a rerun resumes a
chunk left open. A fresh worker is told the items the other running chunks hold, each chunk's own
and those on its latest `Chunk items:` line, and leaves them out. loop-claude needs tmux 3.2 or
later, and checks it before it starts anything.
The session is deleted when its chunk finishes. At every
interrupt, and as every cycle ends, Ctrl-C and a failure included, the session's transcript is
copied into a folder per chunk under $LOOP_CLAUDE_TRANSCRIPTS/<key> (default root
@@ -116,7 +131,10 @@ loop-claude --help succeeds: the loop reloads into the edited script.
Exit 1, saying why, when:
- no task is given
- git cannot start or finds no checkout
- its slot in the project cannot be taken
- tmux is missing or older than 3.2
- --chunk is given outside a tmux window
- a chunk's window cannot be started, as when the plan or the project's config cannot be read
- the tmux session cannot be put on the terminal
- the goals file, or AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/*.md or
the project's review standards where they exist, cannot be read or is not UTF-8
- no config names the checkout, its config cannot be read, or the goals file holds no premises
+7 -4
View File
@@ -45,14 +45,17 @@ ESCALATION_CAP = 2
JUDGE_REPLAYED = ("claude-opus-5-5",)
def routed_item(plan: Plan | Failure, cut: LastCut) -> Item | Failure | None:
"""The item release_standing.chunk_item picks from plan, weighed against the last cut; None when there is none, or it lacks L, E or I."""
def routed_item(plan: Plan | Failure, cut: LastCut, item_id: int | None = None) -> Item | Failure | None:
"""The plan's item item_id, or without one the item release_standing.chunk_item picks from plan, weighed against the last cut; None when there is none, or it lacks L, E or I."""
if isinstance(plan, NoItemsTable):
return None
if isinstance(plan, Failure):
return plan
pick = chunk_item(plan.items, cut)
takes = pick.item if isinstance(pick, Next) else None
if item_id is None:
pick = chunk_item(plan.items, cut)
takes = pick.item if isinstance(pick, Next) else None
else:
takes = next((item for item in plan.items if item.id == item_id), None)
return takes if takes and takes.likelihood and takes.escape_and_impact else None
+147 -21
View File
@@ -31,6 +31,24 @@ OFF_LADDER_ROUTE = {"rung": {"model": "worker-model", "effort": ""}, "item": 0,
# Plays claude from FAKE_CLAUDE_SCENARIO, one step per call, logging each call; a step for another role,
# or none left, is Ctrl-C to loop-claude, which otherwise loops forever.
# A tmux that logs each command. It prints $FAKE_TMUX_VERSION for -V and the file $FAKE_TMUX_WINDOWS for list-windows, where it finds no session without the file, and for any other command the ID of a new window.
FAKE_TMUX = """#!{python}
import json, os, pathlib, sys
argv = sys.argv[1:]
with open(os.environ["FAKE_TMUX_LOG"], "a") as log:
log.write(json.dumps(argv) + "\\n")
windows = pathlib.Path(os.environ["FAKE_TMUX_WINDOWS"])
if argv[0] == "-V":
print(os.environ.get("FAKE_TMUX_VERSION", "tmux 3.2"))
elif argv[0] == "list-windows":
if not windows.exists():
sys.exit("no server running")
print(windows.read_text(), end="")
else:
print("@7")
"""
FAKE_CLAUDE = """#!{python}
import json, os, pathlib, signal, sys, time
@@ -166,9 +184,11 @@ class Run:
code: int
sleeps: list
starts: list
# stderr and stdout are without the local time that opens each message loop-claude prints; raw_stderr and raw_stdout keep it.
# stderr and stdout are without the local time that opens each message loop-claude prints, and stderr without the bell an interrupt rings; raw_stderr and raw_stdout keep them.
stderr: str
stdout: str
# Each tmux command run, as its arguments.
tmux: list
raw_stderr: str
raw_stdout: str
@@ -195,6 +215,8 @@ class Checkout:
fake.mkdir()
(fake / "claude").write_text(FAKE_CLAUDE.format(python=sys.executable))
(fake / "claude").chmod(0o755)
(fake / "tmux").write_text(FAKE_TMUX.format(python=sys.executable))
(fake / "tmux").chmod(0o755)
(fake / "git").symlink_to(shutil.which("git"))
site = self.temp / "site"
site.mkdir()
@@ -203,6 +225,10 @@ class Checkout:
self.env.update({
"FAKE_CLAUDE_LOG": str(self.temp / "calls.jsonl"),
"FAKE_MEMINFO": str(self.temp / "meminfo"),
"FAKE_TMUX_LOG": str(self.temp / "tmux.jsonl"),
"FAKE_TMUX_WINDOWS": str(self.temp / "tmux-windows"),
# The pane of the window the loop under test runs in.
"TMUX_PANE": "%3",
"FAKE_CLAUDE_SCENARIO": str(self.temp / "scenario.json"),
"GIT_CONFIG_GLOBAL": os.devnull,
"GIT_CONFIG_NOSYSTEM": "1",
@@ -224,15 +250,20 @@ class Checkout:
self.git("add", "todo.md")
self.git("commit", "--quiet", "-m", "plan")
def run(self, steps, argv=(TASK,), cwd=None, terminal_input=None, stdout_on_terminal=True, before_typing=None, typed_early=""):
for name in ("FAKE_CLAUDE_LOG", "LOOP_TEST_LOG"):
def run(self, steps, argv=None, cwd=None, terminal_input=None, stdout_on_terminal=True, before_typing=None, typed_early="", chunk="no-item"):
"""Runs loop-claude with argv, or without one as the loop of the window `chunk`, on TASK. Off a terminal, a window's loop whose chunk finished is run again while steps remain, as the window it starts for the next chunk would."""
for name in ("FAKE_CLAUDE_LOG", "LOOP_TEST_LOG", "FAKE_TMUX_LOG"):
pathlib.Path(self.env[name]).unlink(missing_ok=True)
pathlib.Path(self.env["FAKE_CLAUDE_SCENARIO"]).write_text(json.dumps(steps))
command = [sys.executable, str(self.script), *argv]
command = [sys.executable, str(self.script), *(("--chunk", chunk, TASK) if argv is None else argv)]
cwd = cwd or self.root
if terminal_input is None:
done = subprocess.run(command, capture_output=True, cwd=cwd, env=self.env, stdin=subprocess.DEVNULL, text=True, timeout=60)
code, stdout, stderr = done.returncode, done.stdout, done.stderr
code, stdout, stderr = 0, "", ""
runs = 0
while code == 0 and (runs == 0 or (argv is None and json.loads(pathlib.Path(self.env["FAKE_CLAUDE_SCENARIO"]).read_text()))):
runs += 1
done = subprocess.run(command, capture_output=True, cwd=cwd, env=self.env, stdin=subprocess.DEVNULL, text=True, timeout=60)
code, stdout, stderr = done.returncode, stdout + done.stdout, stderr + done.stderr
else:
code, stdout, stderr = self.run_on_terminal(command, cwd, terminal_input, stdout_on_terminal, before_typing, typed_early)
started = lines(pathlib.Path(self.env["LOOP_TEST_LOG"]))
@@ -241,8 +272,9 @@ class Checkout:
code=code,
sleeps=[event["sleep"] for event in started if "sleep" in event],
starts=[event["argv"] for event in started if "argv" in event],
stderr=unstamped(stderr),
stderr=unstamped(stderr).replace("\a", ""),
stdout=unstamped(stdout),
tmux=lines(pathlib.Path(self.env["FAKE_TMUX_LOG"])),
raw_stderr=stderr,
raw_stdout=stdout,
)
@@ -394,7 +426,7 @@ class Premises(unittest.TestCase):
write_config(checkout.home, root)
checkout.git("init", "--quiet", str(root))
run = checkout.run([worker()], cwd=root)
self.assertEqual(argument(run.calls[0], "--name"), f"A {str(root).lstrip('/')} loop-claude")
self.assertEqual(argument(run.calls[0], "--name"), f"A {str(root).lstrip('/')} loop-claude no-item")
class Cycles(unittest.TestCase):
@@ -414,7 +446,7 @@ class Cycles(unittest.TestCase):
self.assertEqual(run.roles(), ["worker", "judge", "worker", "judge", "worker", "judge"])
workers = [call for call in run.calls if call["role"] == "worker"]
session = argument(workers[0], "--session-id")
self.assertEqual(argument(workers[0], "--name"), "A proj loop-claude")
self.assertEqual(argument(workers[0], "--name"), "A proj loop-claude no-item")
self.assertEqual(argument(workers[1], "--resume"), session)
self.assertIsNone(argument(workers[1], "--session-id"))
self.assertIsNone(argument(workers[1], "--name"))
@@ -433,8 +465,10 @@ class Cycles(unittest.TestCase):
self.assertIn("landed-it", run.calls[3]["stdin"])
self.assertNotIn("landed-it", run.calls[5]["stdin"])
self.assertEqual([path.name for path in checkout.transcripts()[0].parent.iterdir()], [checkout.transcripts()[0].name])
self.assertIn("=== cycle 3, worker on worker-model ===", run.stdout)
self.assertEqual(len(re.findall(rf"(?m)^{STAMP} === cycle 3, worker on worker-model ===$", run.raw_stdout)), 1)
self.assertIn("=== cycle 2, worker on worker-model ===", run.stdout)
self.assertEqual(len(re.findall(rf"(?m)^{STAMP} === cycle 2, worker on worker-model ===$", run.raw_stdout)), 1)
# The finished chunk's loop started the next chunk's window and ended; the checkout has no default branch to read a plan from.
self.assertIn("landed-it\nthe chunk finished; started no-item\n\n=== cycle 1, worker on worker-model ===\nnext chunk\n", run.stdout)
copies = {verdict.removeprefix(f"Task: {TASK}\n\n"): copy for copy, verdict in checkout.archived().items()}
self.assertEqual(sorted(copies), [f"<UTC> Stopped: Ctrl-C\n\nWorker: {OFF_LADDER}\n", f"<UTC> Verdict: finished\n\nEvidence:\n> landed-it\n\nConfig: <config>\nJudge: judge-model\nWorker: {OFF_LADDER}\n", f"<UTC> Verdict: unfinished\n\nEvidence:\n> started\n\nConfig: <config>\nJudge: judge-model\nWorker: {OFF_LADDER}\n"])
self.assertIn('"text": "landed-it"', copies[f"<UTC> Verdict: finished\n\nEvidence:\n> landed-it\n\nConfig: <config>\nJudge: judge-model\nWorker: {OFF_LADDER}\n"])
@@ -608,19 +642,15 @@ class Cycles(unittest.TestCase):
self.assertIsNotNone(argument(run.calls[0], "--resume"))
self.assertEqual((argument(run.calls[0], "--model"), argument(run.calls[0], "--effort")), ("claude-fable-5-2", "medium"))
def test_a_second_loop_in_the_project_runs_its_own_session_and_leaves_the_first_loops_open_chunk_alone(self):
def test_a_second_window_of_the_project_runs_its_own_session_and_leaves_the_first_ones_open_chunk_alone(self):
checkout = Checkout(self)
first = checkout.run([worker(say="first chunk"), judge(evidence="first chunk")])
session = argument(first.calls[0], "--session-id")
transcript = checkout.transcripts()[0]
kept, archived = transcript.read_bytes(), checkout.archived()
slot = checkout.home / ".local" / "state" / "loop-claude" / "proj" / "slot-0"
slot.parent.mkdir(parents=True, exist_ok=True)
# The test holds the first loop's slot, as the first loop does while it runs.
with open(slot, "a") as running:
fcntl.flock(running, fcntl.LOCK_EX | fcntl.LOCK_NB)
second = checkout.run([worker(say="second chunk"), judge(evidence="second chunk")])
self.assertEqual(argument(second.calls[0], "--name"), "A proj loop-claude 2")
self.assertEqual(argument(first.calls[0], "--name"), "A proj loop-claude no-item")
second = checkout.run([worker(say="second chunk"), judge(evidence="second chunk")], chunk="item-2")
self.assertEqual(argument(second.calls[0], "--name"), "A proj loop-claude item-2")
self.assertNotIn(session, [argument(call, "--session-id") or argument(call, "--resume") for call in second.calls if call["role"] == "worker"])
self.assertNotIn("first chunk", second.calls[1]["stdin"])
self.assertEqual(transcript.read_bytes(), kept)
@@ -771,6 +801,91 @@ class Cycles(unittest.TestCase):
self.assertEqual((run.code, run.roles()), (130, ["worker", "judge"] * 12))
# Items 4 and 9 with predictions that do not overlap, so both may run at once, and item 12, which overlaps item 4.
BESIDE = TAKEN_IN_AT_L_4 + "| 12 | 0.1.0 | | **Do most.** | 2 | 1 | 2 | 3 | 2 | 1 by 9 | 10 |\n\n## Details\n\n### 4. Do it.\n\nTouches:\n\n- `a.py`\n\n### 9. Do more.\n\nTouches:\n\n- `b.py`\n\n### 12. Do most.\n\nTouches:\n\n- `a.py`\n"
class Windows(unittest.TestCase):
def checkout(self, parallel=None):
"""A checkout whose plan is BESIDE, with parallel-chunks set where given."""
checkout = Checkout(self)
checkout.commit_plan(BESIDE)
if parallel:
config = checkout.home / ".claude-projects" / "proj" / "config.toml"
config.write_text(f"parallel-chunks = {parallel}\n" + config.read_text())
return checkout
def started(self, run):
"""The window each new-session or new-window made, with the command it runs."""
return [(command[0], command[command.index("-n") + 1], command[command.index("--") + 1:]) for command in run.tmux if command[0] in ("new-session", "new-window")]
def test_starts_one_chunk_in_a_window_of_the_projects_session_by_default(self):
checkout = self.checkout()
run = checkout.run([], argv=["ship", "it"])
self.assertEqual((run.code, run.calls, run.stderr), (0, [], ""))
self.assertEqual(run.tmux, [
["-V"],
["list-windows", "-t", "=loop-proj", "-F", "#{window_name}\t#{pane_dead}\t#{window_id}"],
["new-session", "-d", "-s", "loop-proj", "-n", "item-4", "-c", str(checkout.root), "-e", "LOOP_CLAUDE_JUDGE_MODEL=judge-model", "-e", "LOOP_CLAUDE_WORKER_MODEL=worker-model", "-P", "-F", "#{window_id}", "--", str(checkout.script), "--chunk", "item-4", "ship it"],
["set-option", "-w", "-t", "@7", "remain-on-exit", "failed"],
])
self.assertEqual(run.stdout, "started item-4 in the tmux session loop-proj\nnot on a terminal; see the chunks with `tmux attach -t =loop-proj`\n")
def test_starts_up_to_the_configured_number_of_chunks_whose_predictions_do_not_overlap(self):
run = self.checkout(parallel=3).run([], argv=[TASK])
self.assertEqual([(made, window) for made, window, _ in self.started(run)], [("new-session", "item-4"), ("new-window", "item-9")])
self.assertIn("started item-4, item-9 in the tmux session loop-proj\n", run.stdout)
def test_starts_only_what_the_running_windows_leave_room_for(self):
checkout = self.checkout(parallel=2)
# Item 4's chunk runs and waits for the human; item 9's loop failed, so its window stays, dead.
pathlib.Path(checkout.env["FAKE_TMUX_WINDOWS"]).write_text("item-4 ?\t0\t@1\nitem-9\t1\t@2\n")
run = checkout.run([], argv=[TASK])
self.assertEqual([command for command in run.tmux if command[0] == "kill-window"], [["kill-window", "-t", "@2"]])
self.assertEqual([(made, window) for made, window, _ in self.started(run)], [("new-window", "item-9")])
pathlib.Path(checkout.env["FAKE_TMUX_WINDOWS"]).write_text("item-4\t0\t@1\nitem-9\t0\t@2\n")
run = checkout.run([], argv=[TASK])
self.assertEqual((self.started(run), run.code), ([], 0))
self.assertIn("the tmux session loop-proj runs every chunk that may run now\n", run.stdout)
def test_a_finished_chunk_starts_the_next_one_its_window_leaves_room_for(self):
checkout = self.checkout(parallel=2)
pathlib.Path(checkout.env["FAKE_TMUX_WINDOWS"]).write_text("item-4\t0\t@1\nitem-9\t0\t@2\n")
run = checkout.run([worker(say="merged"), judge(finished=True, evidence="merged")], chunk="item-9")
self.assertEqual((run.code, run.roles()), (0, ["worker", "judge"]))
# Item 9 is still in the checkout's plan, since nothing merged here; the window that leaves holds it no longer, and item 4's chunk still runs.
self.assertEqual(self.started(run), [("new-window", "item-9", [str(checkout.script), "--chunk", "item-9", TASK])])
self.assertIn("the chunk finished; started item-9\n", run.stdout)
def test_tells_a_fresh_worker_the_items_the_other_running_chunks_hold_and_starts_from_its_windows_item(self):
checkout = self.checkout(parallel=2)
checkout.env["LOOP_CLAUDE_WORKER_MODEL"] = "claude-opus-5-5"
pathlib.Path(checkout.env["FAKE_TMUX_WINDOWS"]).write_text("item-4\t0\t@1\nitem-9\t0\t@2\n")
run = checkout.run([worker()], chunk="item-9")
prompt = argument(run.calls[0], "-p")
self.assertIn("The item this chunk starts from, named with --item: item 9, L 4, E + I 3.", prompt)
self.assertIn("Other chunks of this project run now, and hold item 4. Leave those out of this chunk, whatever else may join it.", prompt)
self.assertIn("routed by item 9's L of 4", prompt)
def test_refuses_to_start_on_a_tmux_older_than_needed_or_without_one(self):
checkout = self.checkout()
checkout.env["FAKE_TMUX_VERSION"] = "tmux 3.1c"
run = checkout.run([], argv=[TASK])
self.assertEqual((run.code, run.stderr, run.tmux), (1, "loop-claude runs each chunk in a tmux window, and needs tmux 3.2 or later; it found tmux 3.1c\n", [["-V"]]))
(pathlib.Path(checkout.env["PATH"]) / "tmux").unlink()
run = checkout.run([], argv=[TASK])
self.assertEqual((run.code, run.stderr), (1, "loop-claude runs each chunk in a tmux window, and needs tmux 3.2 or later; it found no tmux\n"))
def test_marks_the_window_while_an_interrupt_waits_and_rings_its_bell(self):
checkout = self.checkout()
run = checkout.run([worker(say="A or B?"), judge(interrupt=True, question="A or B?")], chunk="item-4")
self.assertEqual(run.code, 2)
self.assertEqual([command for command in run.tmux if command[0] == "rename-window"], [["rename-window", "-t", "%3", "item-4 ?"]])
self.assertEqual(run.raw_stderr.count("\a"), 1)
run = checkout.run([worker(say="A or B?"), judge(interrupt=True, question="A or B?"), worker()], chunk="item-4", terminal_input="B\n", before_typing=ANSWERING)
self.assertEqual([command for command in run.tmux if command[0] == "rename-window"], [["rename-window", "-t", "%3", "item-4 ?"], ["rename-window", "-t", "%3", "item-4"]])
class Interrupt(unittest.TestCase):
def test_exits_2_off_a_terminal_and_resumes_on_the_next_run(self):
checkout = Checkout(self)
@@ -971,17 +1086,28 @@ class Reload(unittest.TestCase):
self.assertEqual(run.roles(), ["worker", "judge"] * 5)
self.assertIn("keeping the running script", run.stderr)
reloads = [json.loads(argv[1]) for argv in run.starts if argv[:1] == ["--reloaded"]]
self.assertEqual(reloads, [{"cycle_number": cycle, "root": str(checkout.root), "task": TASK, "unfinished_evidence": "working", "route": OFF_LADDER_ROUTE, "unfinished_run": cycle, "slot": 0} for cycle in (2, 3, 4)])
self.assertEqual(reloads, [{"cycle_number": cycle, "root": str(checkout.root), "task": TASK, "unfinished_evidence": "working", "route": OFF_LADDER_ROUTE, "unfinished_run": cycle, "chunk": "no-item"} for cycle in (2, 3, 4)])
self.assertIn("=== cycle 5,", run.stdout)
outside = checkout.temp / "outside"
outside.mkdir()
state = {"cycle_number": 3, "root": str(checkout.root), "task": TASK, "unfinished_evidence": "", "route": None}
state = {"cycle_number": 3, "root": str(checkout.root), "task": TASK, "unfinished_evidence": "", "route": None, "chunk": "no-item"}
run = checkout.run([worker()], argv=["--reloaded", json.dumps(state)], cwd=outside)
self.assertEqual((run.code, run.roles()), (130, ["worker", "judge"]))
self.assertEqual(run.calls[0]["cwd"], str(checkout.root))
self.assertIn("=== cycle 4,", run.stdout)
def test_a_loop_started_before_chunks_ran_in_windows_reloads_by_moving_its_chunk_into_one(self):
checkout = Checkout(self)
state = {"cycle_number": 3, "root": str(checkout.root), "task": TASK, "unfinished_evidence": "", "route": None, "slot": 0}
run = checkout.run([worker()], argv=["--reloaded", json.dumps(state)])
self.assertEqual((run.code, run.calls), (0, []))
self.assertEqual([command[0] for command in run.tmux], ["-V", "list-windows", "new-session", "set-option"])
self.assertIn("started no-item in the tmux session loop-proj\n", run.stdout)
def test_stops_where_a_reload_hands_no_state(self):
checkout = Checkout(self)
run = checkout.run([], argv=["--reloaded", "{}"])
self.assertEqual((run.code, run.calls), (1, []))
self.assertIn("rerun loop-claude <task>", run.stderr)
+235 -67
View File
@@ -21,7 +21,10 @@ from routing_figures import archive, state
from routing_figures.calls import Call
from loop_claude.project import checkout, model_choice, records
from loop_claude.cycle import chunk_items
from loop_claude.loop import chunk_slot, chunk_start, close
from loop_claude.loop import chunk_start, chunk_windows, close
from loop_claude import tmux
from chunk_preflight import gathered
from touch_predictions.test_touch_predictions import plan as touch_plan
from project_config.test_project_config import configured
from release_plan.release_standing import DefaultPlan, LastCut, UNSEEN_RELEASES
from loop_effects.effects import Effects, PYTHON_TIMEOUT
@@ -76,18 +79,26 @@ def human(content):
return {"type": "user", "message": {"content": content}}
# The window the loops under test run in.
WINDOW = tmux.Window("loop-proj", "item-7", "%4")
def a_loop(effects, **fields):
"""A loop in /r on effects, with fields in place of its defaults."""
home = pathlib.Path("/h")
defaults = {"root": "/r", "session": session.session_named("A proj loop-claude", home / ".claude" / "projects"), "paths": paths.paths_from(home), "env": {}, "launcher": pathlib.Path("/b/loop-claude")}
defaults = {"root": "/r", "session": session.session_named("A proj loop-claude", home / ".claude" / "projects"), "paths": paths.paths_from(home), "env": {}, "launcher": pathlib.Path("/b/loop-claude"), "window": WINDOW}
return this_loop.Loop(**{**defaults, **fields}, effects=effects)
class FakeEffects:
"""Effects that record each call and answer from a script, one answer per call."""
def __init__(self, claude=(), on_terminal_claude=(), git=(), inputs=(), python=(), streams=(), on_terminal=True, free_memory=(), dm_failures=()):
def __init__(self, claude=(), on_terminal_claude=(), git=(), inputs=(), python=(), streams=(), on_terminal=True, free_memory=(), dm_failures=(), tmux_version="tmux 3.2", windows=None):
self.calls = []
# Each tmux command run. They stay out of self.calls, as the DMs do. tmux prints `windows` for list-windows, or without them finds no session.
self.tmux_calls = []
self.tmux_version = tmux_version
self.windows = windows
# Each direct message sent. They stay out of self.calls, so a test that lists every call doesn't list them. Without a script, each is sent.
self.dms = []
self.dm_failures = list(dm_failures)
@@ -115,8 +126,16 @@ class FakeEffects:
python=lambda args, cwd: self.answer("python", (args, cwd)),
sleep=lambda seconds: self.calls.append(("sleep", seconds)),
stream_claude=self.stream,
tmux=self.tmux,
tmux_on_terminal=lambda args: self.tmux(args).returncode,
)
def tmux(self, args):
self.tmux_calls.append(args)
if args[0] == "list-windows":
return subprocess.CompletedProcess(args, 1 if self.windows is None else 0, self.windows or "", "no server")
return subprocess.CompletedProcess(args, 0, {"-V": self.tmux_version + "\n"}.get(args[0], "@9\n"), "")
def dm(self, text):
self.dms.append(text)
return self.dm_failures.pop(0) if self.dm_failures else None
@@ -265,7 +284,7 @@ class Cycles(unittest.TestCase):
self.archive = project_archive(str(self.home / "code" / "proj"), self.home, {})
def cycle(self, fake, records="", unfinished_evidence="", facts="- A preflight fact."):
return run.Cycle(config=CONFIG, effects=fake.effects(), facts=facts, judge_model="judge-model", ladder=LADDER, premises="## Goals", project=None, project_archive=self.archive, records=records, root=str(self.home), route=Route(Rung("worker-model")), session=self.session, task="Do it.", todo=plan_of(""), unfinished_evidence=unfinished_evidence)
return run.Cycle(config=CONFIG, window=WINDOW, effects=fake.effects(), facts=facts, judge_model="judge-model", ladder=LADDER, premises="## Goals", project=None, project_archive=self.archive, records=records, root=str(self.home), route=Route(Rung("worker-model")), session=self.session, task="Do it.", todo=plan_of(""), unfinished_evidence=unfinished_evidence)
def archived_outcomes(self):
return sorted(path.read_text() for path in self.archive.glob("*/*.outcomes.md"))
@@ -560,7 +579,7 @@ Spent since 2026-09-21T14:13:20Z, in tokens of input, cache write 5m, cache writ
fake = FakeEffects(streams=[worker, worker], claude=[judged("interrupt"), judged("unfinished")], inputs=["Use B."])
with contextlib.redirect_stderr(io.StringIO()) as said:
self.assertEqual(run.run_cycle(self.cycle(fake)).verdict, Unfinished("working", entries_read=6))
self.assertIn(f"\n{STAMP} Which one?\n", said.getvalue())
self.assertIn(f"\n{STAMP} Which one?\a\n", said.getvalue())
self.assertEqual(fake.made("claude_on_terminal"), [])
resumed = fake.made("stream_claude")[1]
self.assertEqual(resumed[resumed.index("--resume") + 1], str(self.session.id))
@@ -627,7 +646,7 @@ Spent since 2026-09-21T14:13:20Z, in tokens of input, cache write 5m, cache writ
with contextlib.redirect_stderr(io.StringIO()) as said:
self.assertEqual(run.run_cycle(self.cycle(fake, records="From AGENTS.md:\nUse B. Use A.")), Stop(2, "the human is needed to answer the question above, but nothing was typed"))
self.assertEqual(len(fake.made("stream_claude")), 1)
self.assertIn(f"\n{STAMP} Which one?\n", said.getvalue())
self.assertIn(f"\n{STAMP} Which one?\a\n", said.getvalue())
self.assertNotIn("Use ... A.", said.getvalue())
@unittest.skipIf(os.geteuid() == 0, "root writes into a read-only directory")
@@ -733,10 +752,11 @@ class Interrupts(unittest.TestCase):
self.session = interrupt.WorkerSession(str(self.home), uuid.uuid7(), Rung("m", "high"), str(self.transcript), {"LOOP_CLAUDE_WORKER_RUNG": "m at high effort"})
def put(self, fake, answer_here=True, effects=None, question="Which one?"):
"""interrupt's answer and what it said."""
"""interrupt's answer and what it said, without the bell it rang, which self.bells counts."""
with contextlib.redirect_stderr(io.StringIO()) as said:
answer = interrupt.interrupt(question, answer_here, self.session, effects or fake.effects())
return answer, said.getvalue()
answer = interrupt.interrupt(question, answer_here, self.session, WINDOW, effects or fake.effects())
self.bells = said.getvalue().count(tmux.BELL)
return answer, said.getvalue().replace(tmux.BELL, "")
def typed_there(self, args):
"""The claude opened on the terminal: the human types a line in the worker's session, and it ends."""
@@ -754,7 +774,19 @@ class Interrupts(unittest.TestCase):
with self.subTest(on_terminal=on_terminal):
fake = FakeEffects(inputs=["Use B."], on_terminal=on_terminal)
self.put(fake)
self.assertEqual(fake.dms, [f"loop-claude in {self.home} asks:\n\nWhich one?"])
self.assertEqual(fake.dms, [f"loop-claude in {self.home} asks, in the tmux window loop-proj:item-7:\n\nWhich one?"])
def test_marks_its_window_and_rings_the_bell_while_it_waits_and_clears_the_mark_once_answered(self):
fake = FakeEffects(inputs=["Use B."])
answer, said = self.put(fake)
self.assertEqual(answer, "Use B.")
self.assertEqual(self.bells, 1)
self.assertEqual(fake.tmux_calls, [["rename-window", "-t", "%4", "item-7 ?"], ["rename-window", "-t", "%4", "item-7"]])
def test_a_loop_that_stops_unanswered_leaves_its_window_marked(self):
fake = FakeEffects(on_terminal=False)
self.put(fake)
self.assertEqual(fake.tmux_calls, [["rename-window", "-t", "%4", "item-7 ?"]])
def test_drops_the_keys_typed_before_the_question_ahead_of_the_dm_so_an_answer_typed_while_it_sends_counts(self):
fake = FakeEffects(inputs=["Use B."])
@@ -1125,14 +1157,21 @@ class Routing(unittest.TestCase):
class RouteSources(unittest.TestCase):
def test_routes_on_the_plan_item_and_says_why_it_routes_on_the_projects_rung(self):
self.assertIsNone(chunk_start.plan_item(DefaultPlan(plan_of(""), NO_CUT), FakeEffects().effects()))
self.assertEqual(chunk_start.plan_item(DefaultPlan(plan_of(TODO), LastCut("v0.1.0", "", 3, [TODO])), FakeEffects().effects()).id, 3)
self.assertIsNone(chunk_start.plan_item(DefaultPlan(plan_of(TODO), LastCut("v0.3.0", "", 3, [TODO])), FakeEffects().effects()))
self.assertIsNone(chunk_start.plan_item(DefaultPlan(plan_of(""), NO_CUT), None, FakeEffects().effects()))
self.assertEqual(chunk_start.plan_item(DefaultPlan(plan_of(TODO), LastCut("v0.1.0", "", 3, [TODO])), None, FakeEffects().effects()).id, 3)
self.assertIsNone(chunk_start.plan_item(DefaultPlan(plan_of(TODO), LastCut("v0.3.0", "", 3, [TODO])), None, FakeEffects().effects()))
def test_routes_a_window_named_for_an_item_on_that_item_whatever_the_plan_takes_next(self):
plan = DefaultPlan(plan_of(TODO), LastCut("v0.1.0", "", 3, [TODO]))
later = next(item.id for item in plan.todo.items if item.id != 3)
self.assertEqual(chunk_start.plan_item(plan, later, FakeEffects().effects()).id, later)
# An item that left the plan, as once it shipped.
self.assertIsNone(chunk_start.plan_item(plan, 999, FakeEffects().effects()))
unreadable = Failure("git show origin/main:todo.md printed text that is not UTF-8")
for plan, said in ((DefaultPlan(plan_of(TODO.replace("| 4 | 2 | 3 |", "| x | 2 | 3 |")), NO_CUT), "routing on the project's rung: item 3's L 'x' is not a whole number from 1 to 4\n"), (DefaultPlan(unreadable, NO_CUT), f"routing on the project's rung: {unreadable.reason}\n"), (Failure("no origin remote"), "routing on the project's rung: no origin remote\n")):
with self.subTest(said=said):
with contextlib.redirect_stderr(io.StringIO()) as stderr:
self.assertIsNone(chunk_start.plan_item(plan, FakeEffects().effects()))
self.assertIsNone(chunk_start.plan_item(plan, None, FakeEffects().effects()))
self.assertTrue(stderr.getvalue().startswith(f"{STAMP} {said}"), stderr.getvalue())
def test_says_why_the_items_the_worker_names_lift_no_rung(self):
@@ -1210,61 +1249,99 @@ class RouteSources(unittest.TestCase):
self.assertTrue(stderr.getvalue().startswith(f"{STAMP} routing the chunk afresh: could not read the archive"), stderr.getvalue())
class ChunkSlots(unittest.TestCase):
def setUp(self):
temp = tempfile.TemporaryDirectory()
self.addCleanup(temp.cleanup)
self.home = pathlib.Path(temp.name)
self.paths = paths.paths_from(self.home)
self.addCleanup(self.release)
class TmuxCommands(unittest.TestCase):
def test_refuses_a_tmux_older_than_needed_naming_both_versions(self):
for found, reason in (("tmux 3.2", None), ("tmux 3.8", None), ("tmux next-3.4", None), ("tmux 10.0", None),
("tmux 3.1c", "loop-claude runs each chunk in a tmux window, and needs tmux 3.2 or later; it found tmux 3.1c"),
("tmux 2.9a", "loop-claude runs each chunk in a tmux window, and needs tmux 3.2 or later; it found tmux 2.9a"),
("", "loop-claude runs each chunk in a tmux window, and needs tmux 3.2 or later; it found no tmux")):
with self.subTest(found=found):
fake = FakeEffects(tmux_version=found)
self.assertEqual(tmux.unusable(fake.tmux), reason)
self.assertEqual(fake.tmux_calls, [["-V"]])
def held(self):
"""This process's open files on a slot, each with whether an exec keeps it."""
folder = self.home / chunk_slot.SLOTS
found = {}
for fd in os.listdir("/proc/self/fd"):
with contextlib.suppress(OSError):
if pathlib.Path(os.readlink(f"/proc/self/fd/{fd}")).is_relative_to(folder):
found[os.readlink(f"/proc/self/fd/{fd}")] = os.get_inheritable(int(fd))
return found
def test_names_the_session_for_the_project(self):
self.assertEqual(tmux.session_name("claude-config"), "loop-claude-config")
# tmux reads `.` and `:` in a target as separators.
self.assertEqual(tmux.session_name("my.site:2 x"), "loop-my-site-2-x")
def release(self):
folder = str(self.home / chunk_slot.SLOTS)
for fd in os.listdir("/proc/self/fd"):
with contextlib.suppress(OSError):
if os.readlink(f"/proc/self/fd/{fd}").startswith(folder):
os.close(int(fd))
def test_lists_the_windows_without_the_waiting_mark(self):
fake = FakeEffects(windows="item-372 ?\t0\t@1\nitem-380\t1\t@2\nno-item\t0\t@5\n")
self.assertEqual(tmux.listed("loop-proj", fake.tmux), [tmux.Listed("item-372", "@1", False), tmux.Listed("item-380", "@2", True), tmux.Listed("no-item", "@5", False)])
self.assertEqual(fake.tmux_calls, [["list-windows", "-t", "=loop-proj", "-F", "#{window_name}\t#{pane_dead}\t#{window_id}"]])
self.assertEqual(tmux.listed("loop-proj", FakeEffects().tmux), [])
def test_each_loop_takes_the_lowest_free_slot_and_names_its_session_after_it(self):
loop_run = main.LoopRun(cycle_number=0, root=str(self.home / "code" / "proj"), task="do it", unfinished_evidence="")
first, second = chunk_slot.slotted(loop_run, self.paths), chunk_slot.slotted(loop_run, self.paths)
self.assertEqual((first[0], first[1].name), (dataclasses.replace(loop_run, slot=0), "A proj loop-claude"))
self.assertEqual((second[0].slot, second[1].name), (1, "A proj loop-claude 2"))
self.assertEqual(second[1], session.session_named("A proj loop-claude 2", self.paths.claude_code_transcripts))
folder = self.home / ".local" / "state" / "loop-claude" / "proj"
self.assertEqual(self.held(), {str(folder / "slot-0"): True, str(folder / "slot-1"): True})
def test_the_first_window_makes_the_session_and_each_later_one_joins_it(self):
fake = FakeEffects()
window = tmux.Window("loop-proj", "item-7", "")
self.assertIsNone(tmux.start_window(window, "/r", {"LOOP_CLAUDE_X": "1"}, ["/b/loop-claude", "--chunk", "item-7", "ship it;"], True, fake.tmux))
self.assertIsNone(tmux.start_window(window, "/r", {}, ["/b/loop-claude"], False, fake.tmux))
self.assertEqual(fake.tmux_calls, [
["new-session", "-d", "-s", "loop-proj", "-n", "item-7", "-c", "/r", "-e", "LOOP_CLAUDE_X=1", "-P", "-F", "#{window_id}", "--", "/b/loop-claude", "--chunk", "item-7", "ship it\;"],
["set-option", "-w", "-t", "@9", "remain-on-exit", "failed"],
["new-window", "-d", "-t", "=loop-proj:", "-n", "item-7", "-c", "/r", "-P", "-F", "#{window_id}", "--", "/b/loop-claude"],
["set-option", "-w", "-t", "@9", "remain-on-exit", "failed"],
])
def test_a_rerun_takes_the_lowest_free_slot_whose_session_is_open_before_a_lower_closed_one(self):
loop_run = main.LoopRun(cycle_number=0, root=str(self.home / "code" / "proj"), task="do it", unfinished_evidence="")
for name in ("A proj loop-claude 3", "A proj loop-claude 4"):
transcript = self.paths.claude_code_transcripts / "-home-proj" / f"{session.session_named(name, self.paths.claude_code_transcripts).id}.jsonl"
transcript.parent.mkdir(parents=True, exist_ok=True)
transcript.write_text("")
self.assertEqual([chunk_slot.slotted(loop_run, self.paths)[0].slot for _ in range(4)], [2, 3, 0, 1])
def test_says_why_tmux_started_no_window(self):
failed = lambda args: subprocess.CompletedProcess(args, 1, "", "duplicate session: loop-proj\n")
silent = lambda args: subprocess.CompletedProcess(args, 2, "", "")
window = tmux.Window("loop-proj", "item-7", "")
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, failed), Failure("tmux could not start the window loop-proj:item-7: duplicate session: loop-proj"))
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, silent), Failure("tmux could not start the window loop-proj:item-7: it exited 2"))
def test_a_reload_keeps_the_slot_it_is_handed_and_takes_no_other(self):
loop_run = main.LoopRun(cycle_number=3, root="/srv/proj", task="do it", unfinished_evidence="", slot=2)
self.assertEqual(chunk_slot.slotted(loop_run, self.paths), (loop_run, session.session_named("A srv/proj loop-claude 3", self.paths.claude_code_transcripts)))
self.assertEqual(self.held(), {})
def test_marks_a_waiting_window_by_its_pane_and_clears_the_mark(self):
fake = FakeEffects()
tmux.mark(WINDOW, True, fake.tmux)
tmux.mark(WINDOW, False, fake.tmux)
tmux.close(tmux.Listed("item-7", "@3", True), fake.tmux)
self.assertEqual(fake.tmux_calls, [["rename-window", "-t", "%4", "item-7 ?"], ["rename-window", "-t", "%4", "item-7"], ["kill-window", "-t", "@3"]])
self.assertEqual(WINDOW.target, "loop-proj:item-7")
def test_says_why_it_takes_no_slot(self):
loop_run = main.LoopRun(cycle_number=0, root="/srv/proj", task="do it", unfinished_evidence="")
with unittest.mock.patch.object(chunk_slot, "MOST", 1):
chunk_slot.slotted(loop_run, self.paths)
self.assertEqual(chunk_slot.slotted(loop_run, self.paths), Failure(f"1 loops of this project are running already; `fuser {self.home}/.local/state/loop-claude/srv/proj/slot-*` names them"))
(self.home / ".local" / "state" / "loop-claude").mkdir(parents=True, exist_ok=True)
(self.home / ".local" / "state" / "loop-claude" / "other").write_text("")
self.assertEqual(chunk_slot.slotted(dataclasses.replace(loop_run, root="/other"), self.paths), Failure(f"cannot take a slot in {self.home}/.local/state/loop-claude/other: File exists"))
def test_shows_the_session_by_attaching_or_inside_tmux_by_switching(self):
self.assertEqual(tmux.show("loop-proj", False), ["attach-session", "-t", "=loop-proj"])
self.assertEqual(tmux.show("loop-proj", True), ["switch-client", "-t", "=loop-proj"])
class ChunkWindows(unittest.TestCase):
def plan(self, *touched):
"""A plan of items 1, 2 and on, each predicted to touch the path given for it."""
items = touch_plan(*((number, "1.0.0", "", f"- `{path}`") for number, path in enumerate(touched, 1)))
return gathered.Plan(items=items, first=items[0], text="", branch_template="")
def test_starts_the_next_item_and_those_picked_beside_it_up_to_the_limit(self):
# Item 2 overlaps item 1, so it waits for it; items 3 and 4 run beside it.
plan = self.plan("a.py", "a.py", "c.py", "d.py")
self.assertEqual(chunk_windows.may_start(plan, [], set(), 1), ["item-1"])
self.assertEqual(chunk_windows.may_start(plan, [], set(), 2), ["item-1", "item-3"])
self.assertEqual(chunk_windows.may_start(plan, [], set(), 9), ["item-1", "item-3", "item-4"])
def test_leaves_the_items_running_chunks_hold_and_counts_them_against_the_limit(self):
plan = self.plan("a.py", "a.py", "c.py", "d.py")
self.assertEqual(chunk_windows.may_start(plan, ["item-1"], {1, 3}, 2), ["item-4"])
self.assertEqual(chunk_windows.may_start(plan, ["item-1"], {1}, 3), ["item-3", "item-4"])
self.assertEqual(chunk_windows.may_start(plan, ["item-1", "item-3"], {1, 3}, 2), [])
self.assertEqual(chunk_windows.may_start(plan, ["item-1", "item-3", "item-4"], {1, 3, 4}, 2), [])
def test_a_plan_without_an_item_starts_one_chunk_and_only_alone(self):
none = gathered.NoItem("release 1.0.0 has no items")
self.assertEqual(chunk_windows.may_start(none, [], set(), 3), ["no-item"])
self.assertEqual(chunk_windows.may_start(none, ["item-1"], {1}, 3), [])
def test_names_a_window_for_its_item_and_reads_the_item_back(self):
self.assertEqual(chunk_windows.window_name(372), "item-372")
self.assertEqual([chunk_windows.item_of(chunk) for chunk in ("item-372", "no-item", "item-", "item-3x", "xitem-3")], [372, None, None, None, None])
def test_a_chunk_holds_its_own_item_and_those_on_its_latest_chunk_items_line(self):
with tempfile.TemporaryDirectory() as temp:
transcripts = pathlib.Path(temp)
opened = chunk_windows.chunk_session("proj", "item-7", transcripts)
self.assertEqual(opened.name, "A proj loop-claude item-7")
folder = transcripts / "-r"
folder.mkdir()
lines = [assistant({"type": "text", "text": "Chunk items: 7 (L 1, E + I 2)"}), assistant({"type": "text", "text": "Chunk items: 7 (L 1, E + I 2), 9 (L 2, E + I 3)"})]
(folder / f"{opened.id}.jsonl").write_text("".join(json.dumps(line) + "\n" for line in lines))
self.assertEqual(chunk_windows.held_items(["item-7", "item-8", "no-item"], "proj", transcripts), {7, 8, 9})
class Steps(unittest.TestCase):
@@ -1337,10 +1414,22 @@ class ChunkFacts(unittest.TestCase):
def test_runs_the_preflight_at_the_checkout_root_and_quotes_what_it_printed(self):
fake = FakeEffects(python=[ran("- A fact.\n")])
said = chunk_start.chunk_facts(a_loop(fake.effects(), launcher=self.LAUNCHER))
self.assertEqual(fake.made("python"), [(["/b/chunk-preflight", "--worktree"], "/r")])
self.assertIn("\n\n- A fact.", said)
self.assertEqual(fake.made("python"), [(["/b/chunk-preflight", "--worktree", "--item", "7"], "/r")])
self.assertTrue(said.endswith("\n\n- A fact."), said)
self.assertNotIn("yourself", said)
def test_a_chunk_without_an_item_runs_the_preflight_without_naming_one(self):
fake = FakeEffects(python=[ran("- A fact.\n")])
chunk_start.chunk_facts(a_loop(fake.effects(), launcher=self.LAUNCHER, window=tmux.Window("loop-proj", "no-item", "%4")))
self.assertEqual(fake.made("python"), [(["/b/chunk-preflight", "--worktree"], "/r")])
def test_the_facts_end_with_the_items_the_projects_other_running_chunks_hold(self):
# The loop's own window, a dead one and two that run, one of them waiting for the human.
fake = FakeEffects(python=[ran("- A fact.\n")], windows="item-7\t0\t@1\nitem-5\t1\t@2\nitem-12 ?\t0\t@3\nitem-9\t0\t@4\n")
said = chunk_start.chunk_facts(a_loop(fake.effects(), launcher=self.LAUNCHER))
self.assertTrue(said.endswith("- A fact.\n\nOther chunks of this project run now, and hold items 9, 12. Leave those out of this chunk, whatever else may join it."), said)
self.assertEqual(prompts.held_by_others([9]), "\n\nOther chunks of this project run now, and hold item 9. Leave those out of this chunk, whatever else may join it.")
def test_has_the_worker_find_the_facts_itself_where_the_preflight_failed(self):
for failed, why in ((ran(code=1, stderr="git could not start\n"), "git could not start"), (ran(code=1), "exited 1")):
with self.subTest(why=why):
@@ -1353,7 +1442,7 @@ class ChunkFacts(unittest.TestCase):
opened = session.session_named("A proj loop-claude", pathlib.Path(home, "projects"))
fresh = FakeEffects(python=[ran("- A fact.\n")])
facts, _ = chunk_start.chunk_start(a_loop(fresh.effects(), session=opened, launcher=self.LAUNCHER))
self.assertEqual((fresh.made("python"), "- A fact." in facts), ([(["/b/chunk-preflight", "--worktree"], "/r")], True))
self.assertEqual((fresh.made("python"), "- A fact." in facts), ([(["/b/chunk-preflight", "--worktree", "--item", "7"], "/r")], True))
transcript = pathlib.Path(home, "projects", "-fake", f"{opened.id}.jsonl")
transcript.parent.mkdir(parents=True)
transcript.write_text("")
@@ -1932,6 +2021,75 @@ class LoopRuns(unittest.TestCase):
self.assertEqual(reload.exec_if_edited(a_loop(fake.effects(), launcher=launcher), "stale", main.LoopRun(cycle_number=1, root="/r", task="do it", unfinished_evidence="")), Stop(1, "could not reload loop-claude: No such file or directory; rerun loop-claude <task>"))
class WindowStarts(unittest.TestCase):
"""The loop-claude the human runs, which starts the windows, and the stop of a window's loop whose chunk finished."""
HOME = pathlib.Path("/h")
def run_loop(self, argv, fake, env=None, started=("item-3", "item-4")):
"""run_loop's stop and what it said on stdout, with start_chunks answering `started`; self.asked holds what start_chunks was asked."""
with unittest.mock.patch.object(main, "start_chunks", return_value=list(started) if isinstance(started, tuple) else started) as start, contextlib.redirect_stdout(io.StringIO()) as said:
stop = main.run_loop(argv, env or {}, paths.paths_from(self.HOME), pathlib.Path("/b/loop-claude"), CWD, fake.effects())
self.asked = [call.args[:2] for call in start.call_args_list]
return stop, said.getvalue()
def test_refuses_to_start_anything_on_a_tmux_older_than_needed(self):
fake = FakeEffects(git=["/r\n"], tmux_version="tmux 3.1c")
self.assertEqual(self.run_loop(["do it"], fake), (Stop(1, "loop-claude runs each chunk in a tmux window, and needs tmux 3.2 or later; it found tmux 3.1c"), ""))
self.assertEqual((fake.tmux_calls, self.asked), ([["-V"]], []))
def test_prints_the_help_without_tmux(self):
fake = FakeEffects(tmux_version="")
self.assertEqual(self.run_loop(["--help"], fake)[0], Stop(0, usage.HELP))
self.assertEqual(fake.tmux_calls, [])
def test_starts_the_chunks_then_attaches_to_the_session_or_inside_tmux_switches_to_it(self):
for env, shown in (({}, ["attach-session", "-t", "=loop-r"]), ({"TMUX": "/tmp/tmux-1000/default,1,0"}, ["switch-client", "-t", "=loop-r"])):
with self.subTest(shown=shown):
fake = FakeEffects(git=["/r\n"])
stop, said = self.run_loop(["do", "it"], fake, env)
self.assertEqual((stop, said), (Stop(0, ""), f"{STAMP} started item-3, item-4 in the tmux session loop-r\n"))
self.assertEqual(fake.tmux_calls, [["-V"], shown])
self.assertEqual(self.asked, [(main.LoopRun(0, "/r", "do it", ""), False)])
def test_says_that_nothing_started_where_the_session_already_runs_every_chunk_that_may(self):
self.assertEqual(self.run_loop(["do it"], FakeEffects(git=["/r\n"]), started=())[1], f"{STAMP} the tmux session loop-r runs every chunk that may run now\n")
def test_off_a_terminal_it_prints_how_to_attach(self):
fake = FakeEffects(git=["/r\n"], on_terminal=False)
stop, said = self.run_loop(["do it"], fake)
self.assertEqual(stop, Stop(0, ""))
self.assertTrue(said.endswith(f"{STAMP} not on a terminal; see the chunks with `tmux attach -t =loop-r`\n"), said)
self.assertEqual(fake.tmux_calls, [["-V"]])
def test_stops_where_no_chunk_could_start(self):
self.assertEqual(self.run_loop(["do it"], FakeEffects(git=["/r\n"]), started=Failure("no plan"))[0], Stop(1, "no plan"))
def test_stops_where_tmux_cannot_show_the_session(self):
fake = FakeEffects(git=["/r\n"])
effects = dataclasses.replace(fake.effects(), tmux_on_terminal=lambda args: 1)
with unittest.mock.patch.object(main, "start_chunks", return_value=["item-3"]), contextlib.redirect_stdout(io.StringIO()):
stop = main.run_loop(["do it"], {}, paths.paths_from(self.HOME), pathlib.Path("/b/loop-claude"), CWD, effects)
self.assertEqual(stop, Stop(1, "`tmux attach-session -t =loop-r` failed; the chunks go on in the session"))
def test_a_window_loop_outside_tmux_stops(self):
fake = FakeEffects(git=["/r\n"])
self.assertEqual(self.run_loop(["--chunk", "item-3", "do it"], fake)[0], Stop(1, "--chunk is how loop-claude starts itself in a tmux window; run loop-claude <task>"))
self.assertEqual(self.asked, [])
def test_reads_the_chunk_a_window_loop_is_started_with(self):
self.assertEqual(main.loop_run_from(["--chunk", "item-3", "do", "it"], CWD, FakeEffects(git=["/r\n"]).effects()), main.LoopRun(0, "/r", "do it", "", chunk="item-3"))
self.assertEqual(main.loop_run_from(["do", "it"], CWD, FakeEffects(git=["/r\n"]).effects()), main.LoopRun(0, "/r", "do it", ""))
def test_a_finished_chunk_starts_each_chunk_that_may_start_and_stops_without_a_reason(self):
loop_run = main.LoopRun(4, "/r", "do it", "", chunk="item-7")
for started, said, stop in ((["item-9"], "the chunk finished; started item-9", Stop(0, "")), ([], "the chunk finished; started no other, since the chunks running fill what may run now", Stop(0, "")),
(Failure("no plan"), "", Stop(1, "the chunk finished, but the next could not start: no plan"))):
with self.subTest(started=started), unittest.mock.patch.object(main, "start_chunks", return_value=started) as start, contextlib.redirect_stdout(io.StringIO()) as printed:
self.assertEqual(main.handed_on(loop_run, a_loop(FakeEffects().effects())), stop)
self.assertEqual(printed.getvalue(), f"{STAMP} {said}\n" if said else "")
self.assertEqual(start.call_args.args[:2], (loop_run, True))
class StopDms(unittest.TestCase):
def run_main(self, argv, fake):
with tempfile.TemporaryDirectory() as home, contextlib.redirect_stderr(io.StringIO()) as said, contextlib.redirect_stdout(io.StringIO()):
@@ -1944,6 +2102,12 @@ class StopDms(unittest.TestCase):
self.assertEqual(self.run_main(["do it"], fake)[0], 2)
self.assertEqual(fake.dms, [f"loop-claude in {CWD} stopped: the human is needed to look at the chunk, but it stayed unfinished"])
def test_skips_the_dm_of_a_stop_without_a_reason_as_once_the_windows_started(self):
fake = FakeEffects()
with unittest.mock.patch.object(main, "run_loop", return_value=Stop(0, "")):
self.assertEqual(self.run_main(["do it"], fake), (0, ""))
self.assertEqual(fake.dms, [])
def test_skips_the_dm_where_ctrl_c_stopped_the_loop(self):
fake = FakeEffects()
with unittest.mock.patch.object(main, "run_loop", side_effect=KeyboardInterrupt):
@@ -2021,7 +2185,11 @@ class ExitContract(unittest.TestCase):
("cycle/run.py", "close", "1", "failure.reason", read),
("cycle/run.py", "close", "1", "failure.reason", "a finished chunk's session cannot be deleted"),
("loop/close.py", "closed_cycle", "1", "failure.reason", read),
("loop/main.py", "run_loop", "1", "held.reason", "its slot in the project cannot be taken"),
("loop/main.py", "run_loop", "1", "reason", "tmux is missing or older than 3.2"),
("loop/main.py", "run_loop", "1", "f'{CHUNK_FLAG} is how loop-claude starts itself", "--chunk is given outside a tmux window"),
("loop/main.py", "windows_opened", "1", "started.reason", "a chunk's window cannot be started"),
("loop/main.py", "windows_opened", "1", "f\"`tmux {' '.join(shown)}` failed", "the tmux session cannot be put on the terminal"),
("loop/main.py", "handed_on", "1", "f'the chunk finished, but the next could not start", "a chunk's window cannot be started"),
("loop/main.py", "next_cycle", "1", "premises.reason", premises_),
("loop/main.py", "next_cycle", "1", "records.reason", unreadable),
("loop/main.py", "next_cycle", "1", "ladder_file.reason", premises_),
+91
View File
@@ -0,0 +1,91 @@
"""The tmux commands loop-claude runs: each chunk's loop runs in its own window of one tmux session named for the project (docs/decisions.md → `loop-claude: each chunk runs in its own tmux window`)."""
import dataclasses
import re
import subprocess
import typing
from failure import Failure
# Runs tmux with these arguments and returns what it printed; exit 127 where tmux cannot start.
Tmux = typing.Callable[[list[str]], subprocess.CompletedProcess[str]]
# The oldest tmux that has every command and option used here. Its CHANGES file dates the newest two to 3.2: `remain-on-exit failed` and `new-session -e`.
NEEDED = (3, 2)
# What a window's name ends in while its chunk waits for the human. tmux's status bar shows the name, and `!` after it once the bell rang.
WAITS = " ?"
BELL = "\a"
@dataclasses.dataclass(frozen=True)
class Window:
"""The tmux window a chunk's loop runs in."""
session: str
# Without WAITS.
name: str
# The ID of the loop's pane, which $TMUX_PANE holds. It targets the window whatever its name is.
pane: str
@property
def target(self) -> str:
"""What `tmux attach -t` and `tmux select-window -t` take to reach the window."""
return f"{self.session}:{self.name}"
@dataclasses.dataclass(frozen=True)
class Listed:
"""A window of the project's session, as tmux lists it."""
# Without WAITS.
name: str
# tmux's ID of the window, such as `@3`.
id: str
# Whether its loop has exited: `remain-on-exit failed` keeps the window of a loop that failed, so its last lines stay readable.
dead: bool
def unusable(run: Tmux) -> str | None:
"""Why loop-claude cannot use this machine's tmux, naming the version found and the one needed; None where it is NEEDED or later."""
found = run(["-V"]).stdout.strip()
version = re.search(r"([0-9]+)\.([0-9]+)", found)
if version and (int(version[1]), int(version[2])) >= NEEDED:
return None
return f"loop-claude runs each chunk in a tmux window, and needs tmux {NEEDED[0]}.{NEEDED[1]} or later; it found {found or 'no tmux'}"
def session_name(key: str) -> str:
"""The tmux session of the project with this key, such as `loop-claude-config`. tmux reads `.` and `:` in a target as separators, so every character but a letter, a digit, `_` and `-` becomes a dash."""
return "loop-" + re.sub(r"[^A-Za-z0-9_-]", "-", key)
def listed(session: str, run: Tmux) -> list[Listed]:
"""The windows of session; none where tmux lists none, as while the session doesn't exist or no tmux server runs."""
done = run(["list-windows", "-t", f"={session}", "-F", "#{window_name}\t#{pane_dead}\t#{window_id}"])
rows = [line.split("\t") for line in done.stdout.splitlines()] if done.returncode == 0 else []
return [Listed(row[0].removesuffix(WAITS), row[2], row[1] == "1") for row in rows if len(row) == 3]
def start_window(window: Window, cwd: str, env: typing.Mapping[str, str], command: list[str], first: bool, run: Tmux) -> Failure | None:
"""Starts command in a new window of window's session, in cwd with env added to its environment, and leaves the client where it is. first makes the session too. A Failure says why tmux started none."""
make = ["new-session", "-d", "-s", window.session] if first else ["new-window", "-d", "-t", f"={window.session}:"]
variables = [flag for name, value in env.items() for flag in ("-e", f"{name}={value}")]
# tmux reads a `;` that ends an argument as the end of the command, unless a backslash precedes it.
words = [re.sub(r";$", r"\\;", word) for word in command]
done = run([*make, "-n", window.name, "-c", cwd, *variables, "-P", "-F", "#{window_id}", "--", *words])
if done.returncode:
return Failure(f"tmux could not start the window {window.target}: {done.stderr.strip() or f'it exited {done.returncode}'}")
# By the ID, since a window of the same name may still be closing. A loop that fails before this lands closes its window, and its stop is still sent as a DM.
run(["set-option", "-w", "-t", done.stdout.strip(), "remain-on-exit", "failed"])
return None
def close(window: Listed, run: Tmux) -> None:
run(["kill-window", "-t", window.id])
def mark(window: Window, waits: bool, run: Tmux) -> None:
"""Renames window to end in WAITS while its chunk waits for the human, and back once it doesn't."""
run(["rename-window", "-t", window.pane, window.name + (WAITS if waits else "")])
def show(session: str, inside: bool) -> list[str]:
"""The tmux arguments that put session on the human's terminal: inside tmux the client switches to it, and outside a new client attaches."""
return ["switch-client" if inside else "attach-session", "-t", f"={session}"]
+15
View File
@@ -51,6 +51,10 @@ class Effects:
python: typing.Callable[[list[str], str], subprocess.CompletedProcess[str]]
sleep: typing.Callable[[float], None]
stream_claude: typing.Callable[[list[str], str, dict[str, str]], Streaming]
# Runs tmux with these arguments, as run_tmux does.
tmux: typing.Callable[[list[str]], subprocess.CompletedProcess[str]]
# Runs tmux on the terminal, as to attach a session, and returns its exit code once the human detaches.
tmux_on_terminal: typing.Callable[[list[str]], int]
class StreamingClaude:
@@ -82,6 +86,8 @@ def system_effects(backends: typing.Mapping[Notifier, Backend[typing.Any]] = BAC
python=lambda args, cwd: run_python(args, cwd, PYTHON_TIMEOUT),
sleep=time.sleep,
stream_claude=StreamingClaude,
tmux=run_tmux,
tmux_on_terminal=lambda args: subprocess.run(["tmux", *args]).returncode,
)
@@ -106,6 +112,15 @@ def run_python(args: list[str], cwd: str, timeout: float) -> subprocess.Complete
return subprocess.CompletedProcess(command, 1, "", f"stopped after {timeout} s")
def run_tmux(args: list[str]) -> subprocess.CompletedProcess[str]:
"""Runs tmux and returns what it printed. A tmux that cannot start, as where none is installed, reads as exit 127, saying why on stderr."""
command = ["tmux", *args]
try:
return subprocess.run(command, capture_output=True, encoding="utf-8", errors="replace", stdin=subprocess.DEVNULL)
except OSError as failure:
return subprocess.CompletedProcess(command, 127, "", f"could not start: {failure}")
def say(text: str, effects: Effects, *, stdout: bool = False) -> None:
"""Prints text on stderr, or on stdout where stdout, opening the first line of words with the machine's local time. Blank lines before those words stay blank, and later lines get no time."""
body = text.lstrip("\n")
+13 -6
View File
@@ -91,8 +91,12 @@ aims for. While the panel's overall score is under it, code health weighs 4 time
ranking, and a scoring run with a mean under it asks for a floor item. A legacy project, whose code
scores low, may lower it. Left out, it is 7.0.
`project-config tooling-on-host` and `project-config readability-floor` print their values; the full
listing shows each only where the config changes it from what it is when left out.
`parallel-chunks` is an optional setting, a whole number of 1 or more: how many chunks of the project
loop-claude runs at once, each in its own tmux window. Left out, it is 1.
`project-config tooling-on-host`, `project-config readability-floor` and `project-config parallel-chunks`
print their values; the full listing shows each only where the config changes it from what it is when
left out.
Four optional settings say how the project writes, for a project whose owners don't write as
~/.claude/CLAUDE.md does:
@@ -130,13 +134,13 @@ setting, names an unknown one, misspells a path, a language or a template, sets
without `env-file`, sets `jira-finish-transition` or `jira-finish-status` to anything but a name, without the other or
without a `plan` in Jira, names a Jira `plan` and leaves out `jira-score-formula` or `jira-score-bar`, sets
one of those two without a `plan` in Jira, sets the formula to one that doesn't parse or the bar to anything
but a number, or sets `readability-floor` to anything but a number
from 1 to 10, and where `env-file`, `jira-finish-transition`, `jira-finish-status`, `notifier` or `touch-predictions` is asked for and not set. No path setting has a default.
but a number, sets `readability-floor` to anything but a number
from 1 to 10, or sets `parallel-chunks` to anything but a whole number of 1 or more, and where `env-file`, `jira-finish-transition`, `jira-finish-status`, `notifier` or `touch-predictions` is asked for and not set. No path setting has a default.
"""
import pathlib
import sys
from project_config.settings import CONFIG, DEFAULT_FLOOR, ENV_FILE, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION, JIRA_SCORE_BAR, JIRA_SCORE_FORMULA, load, NOTIFIER, OPTIONAL, ProjectConfig, READABILITY_FLOOR, SETTINGS, TOOLING_ON_HOST, Unnamed, WAIT_FOR_APPROVAL
from project_config.settings import CONFIG, DEFAULT_FLOOR, ENV_FILE, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION, JIRA_SCORE_BAR, JIRA_SCORE_FORMULA, load, NOTIFIER, OPTIONAL, PARALLEL_CHUNKS, ProjectConfig, READABILITY_FLOOR, SETTINGS, TOOLING_ON_HOST, Unnamed, WAIT_FOR_APPROVAL
from failure import Failure
from git_cli.git_repo import git, Git
from project_config import templates
@@ -160,6 +164,9 @@ def main(argv: list[str]) -> int:
if argv == [READABILITY_FLOOR]:
print(config.readability_floor)
return 0
if argv == [PARALLEL_CHUNKS]:
print(config.parallel_chunks)
return 0
if argv and argv[0] in config.texts:
print(config.texts[argv[0]])
return 0
@@ -168,7 +175,7 @@ def main(argv: list[str]) -> int:
print(f"{config.folder / CONFIG} sets no `{argv[0]}`", file=sys.stderr)
return 1
defaults = ProjectConfig(config.key, config.folder, config.top, {}).texts
listed = [f"{name}: {path}" for name, path in paths.items()] + [f"{name}: true" for name, on in switches.items() if on] + ([f"{READABILITY_FLOOR}: {config.readability_floor}"] if config.readability_floor != DEFAULT_FLOOR else []) + [f"{name}: {text}" for name, text in config.texts.items() if text != defaults[name]]
listed = [f"{name}: {path}" for name, path in paths.items()] + [f"{name}: true" for name, on in switches.items() if on] + ([f"{READABILITY_FLOOR}: {config.readability_floor}"] if config.readability_floor != DEFAULT_FLOOR else []) + ([f"{PARALLEL_CHUNKS}: {config.parallel_chunks}"] if config.parallel_chunks != 1 else []) + [f"{name}: {text}" for name, text in config.texts.items() if text != defaults[name]]
print(paths[argv[0]] if argv else "\n".join(listed))
return 0
+7 -2
View File
@@ -35,6 +35,8 @@ TOOLING_ON_HOST = "tooling-on-host"
READABILITY_FLOOR = "readability-floor"
# The floor where the config leaves it out, which every dimension and the overall should reach; docs/decisions.md → "comprehension floor" says it doesn't block anything.
DEFAULT_FLOOR = decimal.Decimal("7.0")
# How many chunks of the project loop-claude runs at once, each in its own tmux window; 1 where left out. Three readers seated as the README's audience picked the spelling 2-1 over concurrent-chunks.
PARALLEL_CHUNKS = "parallel-chunks"
# The optional text settings. `language` is the language the project's prose is written in, by its English name. The others are templates, as `templates` says.
LANGUAGE = "language"
COMMIT_TITLE = "commit-title"
@@ -50,7 +52,7 @@ JIRA_FINISH = (JIRA_FINISH_TRANSITION, JIRA_FINISH_STATUS)
JIRA_SCORE_FORMULA = "jira-score-formula"
JIRA_SCORE_BAR = "jira-score-bar"
JIRA_SCORE = (JIRA_SCORE_FORMULA, JIRA_SCORE_BAR)
OPTIONAL = (BRANCH, COMMIT_TITLE, ENV_FILE, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION, JIRA_SCORE_BAR, JIRA_SCORE_FORMULA, LANGUAGE, NOTIFIER, PULL_REQUEST_TITLE, READABILITY_FLOOR, TOOLING_ON_HOST, TOUCH_PREDICTIONS, WAIT_FOR_APPROVAL)
OPTIONAL = (BRANCH, COMMIT_TITLE, ENV_FILE, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION, JIRA_SCORE_BAR, JIRA_SCORE_FORMULA, LANGUAGE, NOTIFIER, PARALLEL_CHUNKS, PULL_REQUEST_TITLE, READABILITY_FLOOR, TOOLING_ON_HOST, TOUCH_PREDICTIONS, WAIT_FOR_APPROVAL)
# What opens a setting that names a Jira Cloud epic in place of a path: `jira:`, then the epic's address as the browser shows it. The settings below may name an epic; each reads its own part of it.
JIRA = "jira:"
EPIC_SPELLINGS = {
@@ -117,6 +119,7 @@ class ProjectConfig:
wait_for_approval: bool = False
tooling_on_host: bool = False
readability_floor: decimal.Decimal = DEFAULT_FLOOR
parallel_chunks: int = 1
language: str = "English"
commit_title: str = templates.TITLE
pull_request_title: str = templates.TITLE
@@ -194,6 +197,7 @@ def load(top: pathlib.Path, main: pathlib.Path, home: pathlib.Path) -> ProjectCo
waits = values.get(WAIT_FOR_APPROVAL, False)
on_host = values.get(TOOLING_ON_HOST, False)
floor = floor_of(values[READABILITY_FLOOR]) if READABILITY_FLOOR in values else DEFAULT_FLOOR
parallel = values.get(PARALLEL_CHUNKS, 1)
finish = [name for setting in JIRA_FINISH if (name := name_of(values.get(setting)))]
formula, bar = values.get(JIRA_SCORE_FORMULA), values.get(JIRA_SCORE_BAR)
scoring = JiraScoring(formula, bar_value) if isinstance(formula, str) and (bar_value := bar_of(bar)) is not None else None
@@ -221,6 +225,7 @@ def load(top: pathlib.Path, main: pathlib.Path, home: pathlib.Path) -> ProjectCo
*([f"`{JIRA_SCORE_BAR}` is {bar!r}, not a bare number, such as `{JIRA_SCORE_BAR} = 1`"] if JIRA_SCORE_BAR in values and bar_of(bar) is None else []),
*(f"`{name}` is {value!r}, not true or false" for name, value in ((WAIT_FOR_APPROVAL, waits), (TOOLING_ON_HOST, on_host)) if not isinstance(value, bool)),
*([f"`{READABILITY_FLOOR}` is {values[READABILITY_FLOOR]!r}, not a number from 1 to 10; write a bare number, such as `{READABILITY_FLOOR} = 7.0`"] if floor is None else []),
*([f"`{PARALLEL_CHUNKS}` is {parallel!r}, not a whole number of 1 or more, such as `{PARALLEL_CHUNKS} = 2`"] if type(parallel) is not int or parallel < 1 else []),
*(f"`{name}` is {values[name]!r}, {fault}" for name, check in checks.items() if name in values and (fault := check(values[name]))),
]
if faults:
@@ -228,7 +233,7 @@ def load(top: pathlib.Path, main: pathlib.Path, home: pathlib.Path) -> ProjectCo
# faults names a floor the config misspells, and a formula or bar a plan in Jira lacks or misspells.
assert floor is not None
assert scoring is not None or not epics["plan"]
return ProjectConfig(file.parent.name, file.parent, top, {name: path for name, path in paths.items() if path}, env_file, waits is True, on_host is True, floor, **{name.replace("-", "_"): str(values[name]) for name in checks if name in values}, epic=epics["plan"], goals_epic=epics["goals-and-audience"], notifier=notifier, jira_finish=Finish(*finish) if finish else None, jira_scoring=scoring, pages=pages)
return ProjectConfig(file.parent.name, file.parent, top, {name: path for name, path in paths.items() if path}, env_file, waits is True, on_host is True, floor, parallel, **{name.replace("-", "_"): str(values[name]) for name in checks if name in values}, epic=epics["plan"], goals_epic=epics["goals-and-audience"], notifier=notifier, jira_finish=Finish(*finish) if finish else None, jira_scoring=scoring, pages=pages)
def formula_fault(value: object) -> str | None:
+31 -1
View File
@@ -462,6 +462,28 @@ class LoadTest(ConfigCase):
self.assertIn("`readability-floor` is ", found.reason)
self.assertIn(", not a number from 1 to 10; write a bare number, such as `readability-floor = 7.0`", found.reason)
def test_parallel_chunks_is_an_optional_whole_number_from_1_that_is_1_where_left_out(self) -> None:
folder = self.write("acme", CLIENT)
left_out = load(self.checkout, self.checkout, self.home)
assert isinstance(left_out, ProjectConfig), left_out
self.assertEqual(left_out.parallel_chunks, 1)
for spelled in (1, 3, 12):
with self.subTest(spelled):
(folder / "config.toml").write_text(CLIENT + f"parallel-chunks = {spelled}\n")
found = load(self.checkout, self.checkout, self.home)
assert isinstance(found, ProjectConfig), found
self.assertEqual(found.parallel_chunks, spelled)
def test_parallel_chunks_that_is_no_whole_number_from_1_fails_naming_it(self) -> None:
folder = self.write("acme", CLIENT)
for spelled in ('"2"', "0", "-1", "2.0", "true", "inf"):
with self.subTest(spelled):
(folder / "config.toml").write_text(CLIENT + f"parallel-chunks = {spelled}\n")
found = load(self.checkout, self.checkout, self.home)
assert isinstance(found, Failure), found
self.assertIn("`parallel-chunks` is ", found.reason)
self.assertIn(", not a whole number of 1 or more, such as `parallel-chunks = 2`", found.reason)
def test_the_language_and_the_templates_are_optional_and_default_to_english_bare_summaries_and_item_branches(self) -> None:
folder = self.write("acme", CLIENT)
left_out = load(self.checkout, self.checkout, self.home)
@@ -497,7 +519,7 @@ class LoadTest(ConfigCase):
def test_the_failure_for_a_misplaced_env_file_and_a_missing_setting_names_both_and_lists_every_setting(self) -> None:
folder = self.write("acme", "".join(line + "\n" for line in CLIENT.splitlines() if not line.startswith("plan")) + 'env-file = "checkout:.env"\n')
self.assertEqual(self.failure(), f"{folder / 'config.toml'}: `plan` is missing; `env-file` is 'checkout:.env', not {OUTSIDE}. The settings are {', '.join(SETTINGS)}, and optionally branch, commit-title, env-file, jira-finish-status, jira-finish-transition, jira-score-bar, jira-score-formula, language, notifier, pull-request-title, readability-floor, tooling-on-host, touch-predictions and wait-for-approval.")
self.assertEqual(self.failure(), f"{folder / 'config.toml'}: `plan` is missing; `env-file` is 'checkout:.env', not {OUTSIDE}. The settings are {', '.join(SETTINGS)}, and optionally branch, commit-title, env-file, jira-finish-status, jira-finish-transition, jira-score-bar, jira-score-formula, language, notifier, parallel-chunks, pull-request-title, readability-floor, tooling-on-host, touch-predictions and wait-for-approval.")
def test_two_configs_naming_one_checkout_fail_naming_both(self) -> None:
self.write("acme", CLIENT)
@@ -652,6 +674,14 @@ class ToolTest(ConfigCase):
self.assertEqual((self.run_tool("tooling-on-host").stdout, self.run_tool("readability-floor").stdout), ("true\n", "5\n"))
self.assertEqual(self.run_tool().stdout.splitlines()[-2:], ["tooling-on-host: true", "readability-floor: 5"])
def test_prints_parallel_chunks_and_lists_it_only_where_the_config_changes_it(self) -> None:
folder = self.write("acme", CLIENT)
self.assertEqual(self.run_tool("parallel-chunks").stdout, "1\n")
self.assertNotIn("parallel-chunks", self.run_tool().stdout)
(folder / "config.toml").write_text(CLIENT + "parallel-chunks = 3\n")
self.assertEqual(self.run_tool("parallel-chunks").stdout, "3\n")
self.assertIn("parallel-chunks: 3", self.run_tool().stdout.splitlines())
def test_prints_the_language_and_each_template_and_lists_them_only_where_the_config_sets_them(self) -> None:
folder = self.write("acme", CLIENT)
defaults = {"language": "English", "commit-title": "{summary}", "pull-request-title": "{summary}", "branch": "item-{id}"}
+1 -1
View File
@@ -267,7 +267,7 @@ class Main(unittest.TestCase):
result = result if "api_error_status" in result else {"type": "result", "structured_output": {"found": [n + 1 for n in result["found"]]}}
return subprocess.CompletedProcess(args, 0, json.dumps(result), "")
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=system_effects().git, input=unused, local_time=unused, memory=unused, now=unused, on_terminal=unused, python=unused, sleep=unused, stream_claude=unused)
effects = Effects(claude=claude, claude_on_terminal=unused, tmux=unused, tmux_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=system_effects().git, input=unused, local_time=unused, memory=unused, now=unused, on_terminal=unused, python=unused, sleep=unused, stream_claude=unused)
out, err = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
code = main.main(argv, {}, self.home, effects)
+11 -4
View File
@@ -18,7 +18,7 @@ Each project principle states one rule that the decisions below apply; their ent
- chunk-pr: the chunks of a project merge one at a time on a machine, each finishing its plan items in its turn, and a pull request that waits for an approval leaves the queue while it waits
- deploy: this repo keeps no `AGENTS.md`, since `~/.claude` is its checkout; its principles and decision titles head `docs/decisions.md`, its working rules follow them there, and its `.claude/settings.json` excludes every `.claude/CLAUDE.md`, so a session in the clone loads only the clone's `CLAUDE.md`
- loop-claude: each verdict records the claude-config release and commit that ran it, the raw tokens each thread spent by model and kind since the previous outcome that recorded a spend, and the human's typed answer the judge quotes as reversing a choice the worker took on its own recommendation
- loop-claude: one session per running loop of a project, named after the slot the loop holds, its id derived from that name; a chunk's commit in the config's folder takes only the file it changed
- loop-claude: each chunk runs in its own tmux window, of one tmux session per project, up to `parallel-chunks` at once, and needs tmux 3.2; its claude session is named after its window, its id derived from that name; a chunk's commit in the config's folder takes only the file it changed
- 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
- 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
- project config: a record may name a Confluence Cloud page as `confluence:` and its address, the loop reads and writes it as markdown, and a write never overwrites a save made since the loop's read
@@ -157,17 +157,24 @@ Valid while `~/.claude` is a checkout of this repo.
2026-09-30, lilleman. Applies "Always grant explicit access to data": the sandbox `loop-claude` runs in is where access is granted, so the worker and the claude an interrupt opens run with `bypassPermissions`. The worker may read `~/.claude/.credentials.json`: it holds Claude Code's own credentials, which claude reads to run anyway. Its one seam to production is the forge: what it pushes or merges can publish through CI. Valid while `loop-claude` runs only in the sandbox README → Install names.
## loop-claude: one session per running loop of a project, named after the slot the loop holds, its id derived from that name; a chunk's commit in the config's folder takes only the file it changed
## loop-claude: each chunk runs in its own tmux window, of one tmux session per project, up to `parallel-chunks` at once, and needs tmux 3.2; its claude session is named after its window, its id derived from that name; a chunk's commit in the config's folder takes only the file it changed
2026-09-21, lilleman; revised 2026-09-30 by lilleman. Serves goal 1. Ids derived from names keep the session picker at one entry per running loop and make any transcript under those ids loop-claude's own to delete. A checkout outside `~/code` mirroring a path inside it shares that id, and a second loop on it is not refused. Once `todo.md` item 5 lands, the id comes from the full path, so no two checkouts share one, and `loop-claude` refuses to start while another session on that id is active. Moving the checkout orphans its open sessions, archive folder and models entry: sessions stay in the picker until the human deletes them, migration code not being worth a one-human audience.
2026-11-15, lilleman's call of 2026-11-13 in item 372, which split item 361: loops of one project, each on its own chunk, run side by side without touching each other's state. The worker's choices, for what the call left open:
- **A slot, not the chunk, names the session.** A loop names its session before it knows its chunk, since a rerun resumes the open session in place of running `chunk-preflight`. So each loop holds a slot, a file it keeps locked with flock under `~/.local/state/loop-claude/<key>/` (`bin/loop_claude/loop/chunk_slot.py`): the lowest free slot whose session is open, so a rerun resumes a chunk left open, or else the lowest free slot. A session lives one chunk, so one slot holds one chunk at a time. Slot 0 keeps the name every loop had before slots, so a chunk left open before slots still resumes. A reload's exec keeps the lock and hands on the slot.
- **The archive and the route needed no change.** The archive keys each chunk by its own transcript's first line, and a rerun's route comes from the latest verdict on that transcript, so both follow the session. The routing figures are measured across all projects, under their own lock.
- **git's own lock serializes the config folder's commits, in place of the file lock the item asked for.** `git commit` holds `.git/index.lock`, so of two commits at once the second fails, and the worker tries again. A wrapper lock would only make it wait, and a command spelled `flock … git commit` would pass rule-hook unchecked, since it reads only a command that starts with `git`. What two chunks could still break is one committing the file the other staged, so each commits only its own file, as `git commit -m <title> -- <file>` (`CLAUDE.md` → "Git, commits, and PRs").
Valid while claude takes `--session-id` and resumes by it, and a loop names its session before it knows its chunk.
2026-11-16, lilleman's call of 2026-11-13 in item 375, which split item 361: lilleman knows tmux and prefers it. Each chunk runs in its own window of one tmux session per project, `loop-<key>`, up to the number the config's `parallel-chunks` sets, 1 by default. tmux runs even at 1, so every project runs the same workflow (goal 1.3). A window waiting for the human ends its name in ` ?` and rings the bell, and the DM names `<session>:<window>`. The worker's choices, for what the call left open (`bin/loop_claude/tmux.py`, `bin/loop_claude/loop/chunk_windows.py`):
- **The window, not a slot, names the claude session**, as `A <key> loop-claude item-372`, which replaces item 372's slots. The loop-claude the human runs starts the windows and attaches; each window runs `loop-claude --chunk <window>`, so a loop knows its chunk before it names its session, and a rerun still resumes the chunk left open.
- **A finishing chunk starts the next.** As its chunk finishes, a window's loop starts each chunk that may start then and exits, so its window closes. `remain-on-exit failed` keeps the window of a loop that failed, with its last lines, until its chunk starts again. One flock under `~/.local/state/loop-claude/<key>/` serializes the starts, so two chunks finishing together don't start one chunk twice.
- **The other chunks' items are told, not locked.** A fresh worker is told the items each other running chunk holds, its window's item and those on its latest `Chunk items:` line, and leaves them out.
- **tmux 3.2 is the oldest that has every command and option used.** tmux's `CHANGES` dates the newest two to "CHANGES FROM 3.1c TO 3.2": `new-session -e`, and the `remain-on-exit` value that keeps only a failed program's pane. loop-claude checks `tmux -V` before it starts a worktree, a session or a window.
- **The config key is `parallel-chunks`**, which three readers seated as the README's audience picked 2–1.
Valid while claude takes `--session-id` and resumes by it, and the human runs loop-claude where tmux is installed.
## loop-claude: the archive keeps the raw transcript, and a failed archive stops the loop
+17
View File
@@ -2328,3 +2328,20 @@ Read most (opens and searches):
- `docs/decisions.md` 4
- `bin/plan_store/contract.py` 3
- `bin/plan_store/fakes.py` 3
## Reading cost, chunk 956d742d7ba4, finished 2026-11-16T02:13:55Z
276709 new input tokens before the first commit.
Read most (opens and searches):
- `bin/plan_store/jira_epic.py` 14
- `bin/project_config/test_project_config.py` 8
- `bin/plan_store/test_jira_epic.py` 7
- `bin/project_config/settings.py` 7
- `bin/plan_store/stores.py` 6
- `bin/release_plan/ranking.py` 4
- `README.md` 3
- `bin/larv_review/test_larv_review.py` 3
- `bin/project_config/main.py` 3
- `bin/release_plan/formula.py` 3