Merge pull request 'List every running loop in loop-inbox, with the items its chunk takes' (#397) from item-255 into main

This commit was merged in pull request #397.
This commit is contained in:
2026-10-29 21:03:44 +01:00
21 changed files with 694 additions and 175 deletions
+1 -1
View File
@@ -16,7 +16,7 @@ Decisions live in `docs/decisions.md`:
- loop-claude: one session per project, its id derived from the checkout's path relative to `~/code`, or to `/` outside it
- loop-claude: the archive keeps the raw transcript, and a failed archive stops the loop
- loop-claude: the worker's claude compacts its context before it fills a 200k window, at about 170k tokens, and `CLAUDE.md` → "Compact instructions" says what the summary keeps
- loop-inbox: a waiting loop-claude lists its question as one file per session under `~/.local/state/loop-claude/`, and takes the first answer, from its terminal or from loop-inbox, that names that question
- loop-inbox: a loop-claude lists itself while it runs, and its waiting question, as files per session under `~/.local/state/loop-claude/`, and takes the first answer, from its terminal or from loop-inbox, that names that question
- machine load: a heavy command waits for one of the machine's heavy slots, one for every 4 CPUs, which every session shares, and loop-claude starts a worker only while at least a quarter of the machine's memory is available
- machine load: every container a session starts has a memory limit and a swap limit as large as its work needs; rule-hook's `docker-run-memory` blocks a `docker run` or `docker create` without them outside run-heavy, under which a container that lacks them gets the slot's share of three quarters of the memory; and no daemon-wide cap limits all containers together
- principles: about seven things per level, four or five where they act on each other, more where a reader finds them by name; crossing a limit asks for a grouping or a recorded reason
+1 -1
View File
@@ -13,7 +13,7 @@
- A branch that changes only other Markdown, such as `README.md`, `docs/` and `todo.md`, runs the prose pass, and the product-owner pass where an outside reader lands on the change. Its reviewers run on the project's rung, whatever its items' E + I. loop-claude's prompt says so, and rule-hook's `reviewer-rung` allows it.
- A `todo.md` row or detail that a chunk files from a finding, re-scores or moves between releases is no longer reviewed. The chunk that ships the item reads it.
- New tool `loop-inbox` lists the interrupts of every loop-claude on the machine, oldest first, in one terminal. Each entry shows the loop's checkout, how long it has waited and the question's first lines. Pick one to answer the question as on the loop's terminal, except that Enter alone goes back; `/talk` opens claude in loop-inbox's terminal. Of a pasted answer, only the first line is sent, and the rest is dropped. The loop takes the first answer, from its terminal or loop-inbox, so it works as before with no loop-inbox running. A loop that ends drops off the list, even one killed outright. A loop whose claude is already open, such as for a release ready to cut or the routing calls, is listed but answered in that claude. A loop asking for its project's model, as on a project's first run, asks on its own terminal only. Link it onto `PATH` as README → Install shows.
- New tool `loop-inbox` lists the interrupts of every loop-claude on the machine, oldest first, in one terminal. Each entry shows the loop's checkout, how long it has waited and the question's first lines. Pick one to answer the question as on the loop's terminal, except that Enter alone goes back; `/talk` opens claude in loop-inbox's terminal. Of a pasted answer, only the first line is sent, and the rest is dropped. The loop takes the first answer, from its terminal or loop-inbox, so it works as before with no loop-inbox running. A loop that ends drops off the list, even one killed outright. A loop whose claude is already open, such as for a release ready to cut or the routing calls, is listed but answered in that claude. A loop asking for its project's model, as on a project's first run, asks on its own terminal only. Below the questions, loop-inbox lists every running loop, with the ID and tagline of each `todo.md` item its chunk takes. Link it onto `PATH` as README → Install shows.
- Ctrl-C in a claude that `loop-claude` opens on its terminal, for `/talk`, a release ready to cut or the routing calls, now reaches only that claude. Before, it also stopped `loop-claude`, which closed that claude a quarter second later.
- `reading-cost` now lists the files a chunk read in the worktree `chunk-preflight` made, `<checkout>-item-<ID>`. It listed none, since no transcript command names that worktree.
- `larv-review ruling-base` now finds the last measured commit when run in a subfolder of a checkout. Before, it found no change to the comprehension history there and fell back to the merge base.
+1 -1
View File
@@ -99,7 +99,7 @@ Install puts only `loop-claude` and `loop-inbox` on `PATH`; call the others by t
- `judge-replay <model>` replays loop-claude's judge on archived verdicts of the projects run on the model, and prints the lowest rung that, like each rung above it, returns them; `judge-replay --help` states the replay.
- `larv-review <command>` holds larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's round count, the scoring run's trigger, and the comprehension history's format and latest places, and its count of how often seats agree; `larv-review --help` states them.
- `loop-claude <task>` runs a project's next chunk cycle after cycle; `loop-claude --help` states its contract.
- `loop-inbox` shows the interrupts of every loop-claude on the machine, oldest first, and takes each one's answer, `/talk` included; `loop-inbox --help` states how.
- `loop-inbox` shows the interrupts of every loop-claude on the machine, oldest first, takes each one's answer, `/talk` included, and lists every running loop with the `todo.md` items its chunk takes; `loop-inbox --help` states how.
- `metric-bench [history]` benches cheap static metrics of a project's Python against the places its comprehension history names as hardest; `metric-bench --help` states the metrics and the scores.
- `rank_todo.py [--check] [todo.md]` scores and ranks a project's `todo.md`; `rank_todo.py --help` states the format.
- `reading-cost [--reset] [record]` appends a figure for each chunk `loop-claude` finished to a project's `docs/reading-cost.md`, and says whether the figures rise; `reading-cost --help` states the measure.
+1 -1
View File
@@ -122,7 +122,7 @@ class Main(unittest.TestCase):
@staticmethod
def verdict(interrupt, evidence):
output = {"answer": "", "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "evidence": evidence, "finished": not interrupt, "interrupt": interrupt, "question": "Which?" if interrupt else "", "release_ready": False}
output = {"items_taken_in": [], "answer": "", "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "evidence": evidence, "finished": not interrupt, "interrupt": interrupt, "question": "Which?" if interrupt else "", "release_ready": False}
return {"type": "result", "structured_output": output}
def test_replays_the_models_projects_on_the_reference_then_from_the_projects_rung_down_and_prints_the_lowest_that_returns_all(self):
+34 -13
View File
@@ -8,7 +8,7 @@ from claude_code.reply import claude_reply, Limited
from loop_claude.effects import Effects
from loop_claude import escalation_mark
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, TakenIn, Unfinished, Verdict
from todo_table import LEVELS
from model_routing.route import on_its_scale
from claude_code.transcript import plain, verbatim
@@ -67,6 +67,8 @@ class Reply:
highest_likelihood_taken_in: int = dataclasses.field(metadata={"description": "The highest L the worker states for a todo.md item it took into this chunk; 0 when it states none."})
# Routes the next cycle's judge and reviewers, as highest_likelihood_taken_in routes the worker.
highest_escape_and_impact_taken_in: int = dataclasses.field(metadata={"description": "The highest E + I the worker states for a todo.md item it took into this chunk; 0 when it states none."})
# Lists the chunk's items in loop-inbox: running_loops.py.
items_taken_in: list[int] = dataclasses.field(metadata={"description": "The IDs of the todo.md items the worker states this chunk takes, the item the chunk was routed on included, never an item it only filed in todo.md for later; empty when it states none."})
# Routes the worker one rung up, as the judge interrupts or quotes an answer, or on the next cycle: loop_claude/escalation_mark.py.
escalation: str = dataclasses.field(metadata={"description": "Empty unless the chunk is unfinished, interrupt is true or answer quotes a passage, and the worker's run ends asking loop-claude for a higher rung, citing an escalation trigger. Then: a verbatim quote, without elisions, of the transcript passage where the trigger fired, such as a review round's commit title or the worker's report of the finding or failing test. " + escalation_mark.QUOTE_AFTER_STEP + " Never a later mention of the trigger, and never the request itself."})
evidence: str = dataclasses.field(metadata={"description": "A verbatim quote of the one transcript passage the verdict rests on, without elisions: what triggers the interrupt; for a quoted answer, the worker's question; else what shows the chunk finished or the work remaining."})
@@ -78,10 +80,10 @@ class Reply:
REPLY_TYPES = typing.get_type_hints(Reply)
JSON_TYPES = {bool: "boolean", int: "integer", str: "string"}
JSON_TYPES: dict[object, dict[str, typing.Any]] = {bool: {"type": "boolean"}, int: {"type": "integer"}, str: {"type": "string"}, list[int]: {"type": "array", "items": {"type": "integer"}}}
HIGHEST_L = LEVELS["L"]
JUDGE_SCHEMA = {
"properties": {field.name: {**field.metadata, "type": JSON_TYPES[REPLY_TYPES[field.name]]} for field in dataclasses.fields(Reply)},
"properties": {field.name: {**field.metadata, **JSON_TYPES[REPLY_TYPES[field.name]]} for field in dataclasses.fields(Reply)},
"required": list(REPLY_TYPES),
"type": "object",
}
@@ -107,23 +109,42 @@ def verdict_from(output: object) -> Verdict | Failure:
if not isinstance(output, dict):
return Failure("the judge returned no reply")
for name, kind in REPLY_TYPES.items():
# type(), not isinstance(): JSON true is no integer.
if type(output.get(name)) is not kind:
return Failure(f"the judge's reply has no {name} of type {JSON_TYPES[kind]}")
# An L taken in off its scale counts as none: holding the rung is safe, and three failures would stop an unattended loop.
likelihood = output["highest_likelihood_taken_in"] if 0 <= output["highest_likelihood_taken_in"] <= HIGHEST_L else 0
if not fits(output.get(name), kind):
return Failure(f"the judge's reply has no {name} of type {type_name(JSON_TYPES[kind])}")
taken_in = taken_in_from(output)
if output["interrupt"]:
if not output["question"].strip():
return Failure("the judge interrupted without a question")
return Interrupt(output["evidence"], output["question"], escalation=output["escalation"], highest_likelihood_taken_in=likelihood, release_ready=output["release_ready"])
return Interrupt(output["evidence"], output["question"], escalation=output["escalation"], taken_in=taken_in, release_ready=output["release_ready"])
if output["answer"].strip():
if not output["question"].strip():
return Failure("the judge quoted an answer without a question")
return QuotedAnswer(output["evidence"], output["question"], output["answer"], escalation=output["escalation"], highest_likelihood_taken_in=likelihood)
return QuotedAnswer(output["evidence"], output["question"], output["answer"], escalation=output["escalation"], taken_in=taken_in)
if output["finished"]:
return Finished(output["evidence"])
escape_and_impact = output["highest_escape_and_impact_taken_in"] if on_its_scale(output["highest_escape_and_impact_taken_in"]) else 0
return Unfinished(output["evidence"], escalation=output["escalation"], highest_likelihood_taken_in=likelihood, highest_escape_and_impact_taken_in=escape_and_impact)
return Unfinished(output["evidence"], escalation=output["escalation"], taken_in=taken_in)
def type_name(schema: dict[str, typing.Any]) -> str:
return f"array of {schema['items']['type']}s" if schema["type"] == "array" else schema["type"]
def fits(value: object, kind: object) -> bool:
"""Whether value, read from the judge's JSON, is of kind. type(), not isinstance(): JSON true is no integer."""
if typing.get_origin(kind) is list:
return type(value) is list and all(fits(each, typing.get_args(kind)[0]) for each in value)
return type(value) is kind
def taken_in_from(output: dict) -> TakenIn:
"""The reply's readings of the items taken in. An ID below 1 is left out, and an L or E + I off its scale counts as 0. Neither fails the reply: three failures would stop an unattended loop, and holding the rung is safe."""
likelihood = output["highest_likelihood_taken_in"]
escape_and_impact = output["highest_escape_and_impact_taken_in"]
return TakenIn(
tuple(item for item in output["items_taken_in"] if item > 0),
likelihood if 0 <= likelihood <= HIGHEST_L else 0,
escape_and_impact if on_its_scale(escape_and_impact) else 0,
)
def judge(root: str, task: str, premises: str, records: str, entries: list[dict], escalated_at: int, rung: Rung, effects: Effects, keep: typing.Callable[[Rejected], Stop | None]) -> Verdict | Stop:
@@ -164,7 +185,7 @@ def run_judge(root: str, args: list[str], prompt: str, grounds: Grounds, effects
def quotes_checked(verdict: Verdict, grounds: Grounds) -> Verdict:
"""The verdict with its quoted answer and its escalation checked. A quoted answer that neither README.md's premises nor the records hold goes to the human as an interrupt, which keeps the escalation the answer carried. Neither misquote is a Failure, which would otherwise exit an unattended loop."""
if isinstance(verdict, QuotedAnswer) and not verbatim(verdict.answer, grounds.quotable):
verdict = Interrupt(verdict.evidence, verdict.question, escalation=verdict.escalation, highest_likelihood_taken_in=verdict.highest_likelihood_taken_in)
verdict = Interrupt(verdict.evidence, verdict.question, escalation=verdict.escalation, taken_in=verdict.taken_in)
return escalation_mark.checked(verdict, since=grounds.since_step, shown=grounds.shown)
+4
View File
@@ -42,6 +42,8 @@ class Cycle:
project: Rung | None
# Empty when the previous cycle's verdict was not Unfinished.
unfinished_evidence: str
# Lists in loop-inbox the items the chunk takes, given the IDs an unfinished ruling found taken in.
show_taken_in: typing.Callable[[tuple[int, ...]], None]
@dataclasses.dataclass(frozen=True)
@@ -61,6 +63,8 @@ def run_cycle(cycle: Cycle) -> Stop | Concluded:
# Only a ruling's step-up changes the route within a cycle. No transition reads the current route, so Cycle holds it, not the states.
if isinstance(event, Ruled) and event.step_up:
cycle = dataclasses.replace(cycle, route=event.step_up.after)
if isinstance(event, Ruled) and not isinstance(event.verdict, Finished):
cycle.show_taken_in(event.verdict.taken_in.items)
state = transition(state, event)
except KeyboardInterrupt:
return stopped(cycle, Stop(130, ""), "Ctrl-C")
+51 -31
View File
@@ -33,6 +33,9 @@ A release ready to cut opens that session on the terminal at once, since only th
loop-inbox lists it too. Before claude opens, the checkout and each of its worktrees are marked
trusted in ~/.claude.json. While claude is open, Ctrl-C reaches it alone, and the loop goes on.
While it runs, loop-claude also lists itself in loop-inbox, with the todo.md items its chunk takes,
as bin/loop_claude/running_loops.py describes.
As a chunk starts, before it is routed, loop-claude runs bin/chunk-preflight (bin/chunk_preflight/),
which finds the chunk's facts and makes its worktree; chunk-preflight --help lists them, and
prompts.preflight_facts in bin/loop_claude/cycle/prompts.py quotes them in the first prompt. A
@@ -132,7 +135,7 @@ from loop_claude.loop.routing_check import check_routing
from loop_claude.project.checkout import checkout_root
from loop_claude.loop.reload import decode_handed, exec_if_edited, fingerprint, LoopRun, RELOAD_FLAG
from chunk_pick import default_plan, DefaultPlan
from git_repo import default_ref
from git_repo import default_ref, file_at
from loop_claude.effects import Effects, say
from failure import Failure
from loop_claude.verdicts import Finished, Unfinished
@@ -149,6 +152,7 @@ from loop_claude.project.premises import read_premises
from loop_claude.project.records import read_records
from model_routing.route import Route, route_from
from claude_code.session import Session, session_named, session_open, transcript_file
from loop_claude.running_loops import Show, shown_running, taken_items
# Seconds routing waits for origin to name its default branch, asked only where the checkout records none; past them, the chunk runs on the project's rung.
ORIGIN_TIMEOUT = 60
@@ -175,33 +179,49 @@ def run_loop(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launc
archive_folder = project_archive(loop_run.root, paths.home, env)
# "A " is the human's cue in the session picker that the session is the loop's.
session = session_named(f"A {key} loop-claude", paths.claude_code_transcripts)
while True:
if stop := exec_if_edited(launcher, baseline, loop_run, effects):
return stop
loop_run = dataclasses.replace(loop_run, cycle_number=loop_run.cycle_number + 1)
premises = read_premises(loop_run.root)
if isinstance(premises, Stop):
return premises
records = read_records(loop_run.root, paths.claude_dir)
if isinstance(records, Stop):
return records
models = get_or_ask_models(key, paths, env, effects)
if isinstance(models, Stop):
return models
# After the reads above, so a loop that stops on one makes no worktree.
facts, item = chunk_start(session, launcher.with_name("chunk-preflight"), loop_run.root, effects)
project = project_rung(models.worker)
route = routed(loop_run.route, project, models.worker, lambda: archived_route(archive_folder, session, effects), item)
say(f"\n=== cycle {loop_run.cycle_number}, worker on {route.rung} ===", effects, stdout=True)
concluded = run_cycle(Cycle(effects=effects, facts=facts, judge_model=models.judge, paths=paths, premises=premises, project=project, project_archive=archive_folder, records=records, root=loop_run.root, route=route, session=session, task=loop_run.task, unfinished_evidence=loop_run.unfinished_evidence))
if isinstance(concluded, Stop):
return concluded
closed = closed_cycle(loop_run, project, concluded, archive_folder, session, effects)
if isinstance(closed, Stop):
return closed
loop_run = closed
if stop := check_routing(archive_root(paths.home, env), loop_run.root, str(session.id), project or Rung(models.worker), paths, effects):
return stop
with shown_running(paths.waiting, str(session.id), loop_run.root, effects) as listed:
paths = dataclasses.replace(paths, waiting=listed.folder)
while True:
if stop := exec_if_edited(launcher, baseline, loop_run, effects):
return stop
loop_run = dataclasses.replace(loop_run, cycle_number=loop_run.cycle_number + 1)
premises = read_premises(loop_run.root)
if isinstance(premises, Stop):
return premises
records = read_records(loop_run.root, paths.claude_dir)
if isinstance(records, Stop):
return records
models = get_or_ask_models(key, paths, env, effects)
if isinstance(models, Stop):
return models
# After the reads above, so a loop that stops on one makes no worktree.
facts, item = chunk_start(session, launcher.with_name("chunk-preflight"), loop_run.root, effects)
project = project_rung(models.worker)
route = routed(loop_run.route, project, models.worker, lambda: archived_route(archive_folder, session, effects), item)
say(f"\n=== cycle {loop_run.cycle_number}, worker on {route.rung} ===", effects, stdout=True)
show_taken_in = shown_items(listed.show, loop_run.root, route.item)
show_taken_in(loop_run.items_taken_in)
concluded = run_cycle(Cycle(effects=effects, facts=facts, judge_model=models.judge, paths=paths, premises=premises, project=project, project_archive=archive_folder, records=records, root=loop_run.root, route=route, session=session, show_taken_in=show_taken_in, task=loop_run.task, unfinished_evidence=loop_run.unfinished_evidence))
if isinstance(concluded, Stop):
return concluded
closed = closed_cycle(loop_run, project, concluded, archive_folder, session, effects)
if isinstance(closed, Stop):
return closed
loop_run = closed
if stop := check_routing(archive_root(paths.home, env), loop_run.root, str(session.id), project or Rung(models.worker), paths, effects):
return stop
def shown_items(show: Show, root: str, routed: int) -> typing.Callable[[tuple[int, ...]], None]:
"""A function that lists in loop-inbox the items a chunk takes, given the IDs the judge found taken in. routed is the item the chunk was routed on, 0 for none. shown_items reads todo.md once, as the cycle starts, and the function shows those taglines."""
todo = fetched_todo(root)
return lambda taken_in: show(taken_items(todo, routed, taken_in))
def fetched_todo(root: str) -> str | Failure:
"""todo.md on the default branch, as last fetched. fetched_plan reads it too, but also the release tag, CHANGELOG.md and each todo.md since the tag, which the listing doesn't need."""
ref = default_ref(root, ORIGIN_TIMEOUT)
return ref if isinstance(ref, Failure) else file_at(ref, "todo.md", root)
def routed(route: Route | None, project: Rung | None, model: str, archived: typing.Callable[[], Route | None], item: typing.Callable[[], Item | None]) -> Route:
@@ -234,12 +254,12 @@ def reached_limit(loop_run: LoopRun) -> Stop | None:
def after_verdict(loop_run: LoopRun, project: Rung | None, concluded: Concluded) -> LoopRun:
"""The loop run the next cycle starts from. A finished chunk drops its route and its run of unfinished verdicts. An unfinished one takes the route stepped_route makes, the evidence the judge gave for the verdict, and counts the verdict."""
"""The loop run the next cycle starts from. A finished chunk drops its route, its run of unfinished verdicts and the items it took in. An unfinished one takes the route stepped_route makes, the evidence the judge gave for the verdict and the items it found taken in, and counts the verdict."""
verdict = concluded.verdict
if isinstance(verdict, Finished):
return dataclasses.replace(loop_run, route=None, unfinished_evidence="", unfinished_run=0)
return dataclasses.replace(loop_run, route=None, unfinished_evidence="", unfinished_run=0, items_taken_in=())
route = stepped_route(project, concluded.route, verdict)
return dataclasses.replace(loop_run, route=route, unfinished_evidence=verdict.evidence, unfinished_run=loop_run.unfinished_run + 1)
return dataclasses.replace(loop_run, route=route, unfinished_evidence=verdict.evidence, unfinished_run=loop_run.unfinished_run + 1, items_taken_in=verdict.taken_in.items)
def stepped_route(project: Rung | None, ended_on: Route, verdict: Unfinished) -> Route:
+7 -1
View File
@@ -26,6 +26,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 IDs of the items the last unfinished verdict found the chunk takes, which loop-inbox lists until the next ruling.
items_taken_in: tuple[int, ...] = ()
def decode_handed(handed: str, kind: type[T]) -> T | None:
@@ -43,7 +45,7 @@ RETIRED = object()
def decoded_as(value: object, kind: typing.Any) -> typing.Any:
"""value as kind, REJECTED or RETIRED: a dataclass from an object holding its fields, a union's first member that fits, else a value of exactly kind."""
"""value as kind, REJECTED or RETIRED: a dataclass from an object holding its fields, a union's first member that fits, a tuple of one type from a list, else a value of exactly kind."""
if isinstance(kind, types.UnionType):
found = [decoded_as(value, option) for option in typing.get_args(kind)]
fits = [each for each in found if each is not REJECTED and each is not RETIRED]
@@ -64,6 +66,10 @@ def decoded_as(value: object, kind: typing.Any) -> typing.Any:
if any(field in (REJECTED, RETIRED) for field in fields.values()) or not getattr(kind, "fits", lambda _: True)(fields):
return REJECTED
return kind(**fields)
if typing.get_origin(kind) is tuple:
element = typing.get_args(kind)[0]
found = [decoded_as(each, element) for each in value] if isinstance(value, list) else [REJECTED]
return REJECTED if REJECTED in found or RETIRED in found else tuple(found)
return value if type(value) is kind else REJECTED
+3 -3
View File
@@ -78,13 +78,13 @@ def after_unfinished(project: Rung, route: Route, verdict: Unfinished) -> Route:
Its rung never falls. It first rises to the rung that the verdict's highest L taken in picks, where that is higher. From there it steps one rung up on every second unfinished verdict, or on an escalation while below escalation_cap; where both fall on one verdict, it steps once. A step on an escalation moves the mark, as loop_claude/escalation_mark.py says; a step on the count of unfinished verdicts alone keeps it. Last, the route takes in the verdict's highest E + I, as Route.taking_in does.
"""
rung = raised(project, route, verdict.highest_likelihood_taken_in)
rung = raised(project, route, verdict.taken_in.highest_likelihood)
mark = escalation_mark.moved_to(verdict)
if route.unfinished + 1 >= UNFINISHED_PER_STEP or (mark is not None and below_cap(project, route, rung)):
after = one_rung_up(route, rung, route.escalated_at if mark is None else mark)
else:
after = dataclasses.replace(route, rung=rung, unfinished=route.unfinished + 1)
return after.taking_in(verdict.highest_escape_and_impact_taken_in)
return after.taking_in(verdict.taken_in.highest_escape_and_impact)
def after_ruling(project: Rung, route: Route, verdict: Interrupt | QuotedAnswer) -> Route:
@@ -92,7 +92,7 @@ def after_ruling(project: Rung, route: Route, verdict: Interrupt | QuotedAnswer)
mark = escalation_mark.moved_to(verdict)
if mark is None:
return route
rung = raised(project, route, verdict.highest_likelihood_taken_in)
rung = raised(project, route, verdict.taken_in.highest_likelihood)
return one_rung_up(route, rung, mark) if below_cap(project, route, rung) else dataclasses.replace(route, rung=rung)
+137
View File
@@ -0,0 +1,137 @@
"""The files by which a loop-claude shows loop-inbox that it runs, and the todo.md items its chunk takes.
A running loop holds its session's lock (session_lock.py) in Paths.waiting for its whole run. Beside the lock it keeps
<session>.running, which holds the loop's checkout and each item its chunk takes, by ID and by its tagline on the default
branch as last fetched. The items are the one the chunk was routed on, then those the judge's latest ruling found the
worker took in, each listed once. loop-inbox lists a loop, and its question (waiting.py), only while the loop holds its
lock. So a killed loop drops off the list, though its files stay until loop-inbox removes them: <session>.running
through drop_ended_loops here, and the question through waiting.drop_ended.
"""
import contextlib
import dataclasses
import json
import pathlib
import shutil
import typing
from loop_claude.effects import Effects, say
from loop_claude.session_lock import ended, held, running
from failure import Failure
from todo_table import items
from file_writes import replace_json
# How many times, 0.1 s apart, a loop tries to take its lock: loop-inbox takes it for a moment each time it checks whether the loop has ended.
LOCK_TRIES = 10
@dataclasses.dataclass(frozen=True)
class Taken:
"""A todo.md item a chunk takes."""
id: int
# The item's tagline without its bold marks; empty where the default branch's todo.md can't be read or holds no such item.
tagline: str
@dataclasses.dataclass(frozen=True)
class RunningLoop:
session: str
# The checkout the loop runs in.
root: str
# The routed item first; empty until the chunk has an item.
items: tuple[Taken, ...]
Show = typing.Callable[[tuple[Taken, ...]], None]
@dataclasses.dataclass(frozen=True)
class Listed:
"""How a running loop shows itself in loop-inbox."""
# Where the loop keeps its questions: Paths.waiting where it holds its session's lock. Where another loop on the session holds the lock, a folder of its own that loop-inbox doesn't read, so this loop never touches the other's questions.
folder: pathlib.Path
show: Show
def running_file(folder: pathlib.Path, session: str) -> pathlib.Path:
return folder / f"{session}.running"
@contextlib.contextmanager
def shown_running(folder: pathlib.Path, session: str, root: str, effects: Effects) -> typing.Iterator[Listed]:
"""Lists the loop in loop-inbox as running while the with block runs, at first with no item. A failure only warns: the loop runs unlisted, and its questions are answered on its terminal."""
with contextlib.ExitStack() as stack:
if unlocked := locked_soon(stack, folder, session, effects):
say(f"loop-inbox cannot list this loop or its questions: {unlocked.reason}", effects)
unlisted = folder / "unlisted" / effects.new_id()
try:
yield Listed(unlisted, lambda items: None)
finally:
shutil.rmtree(unlisted, ignore_errors=True)
return
def show(items: tuple[Taken, ...]) -> None:
if unshown := replace_json(running_file(folder, session), {"root": root, "items": [dataclasses.asdict(item) for item in items]}):
say(f"loop-inbox cannot list this loop's items: {unshown.reason}", effects)
show(())
try:
yield Listed(folder, show)
finally:
# A file this fails to remove stays until loop-inbox removes it, once the lock is let go.
with contextlib.suppress(OSError):
running_file(folder, session).unlink(missing_ok=True)
def locked_soon(stack: contextlib.ExitStack, folder: pathlib.Path, session: str, effects: Effects) -> Failure | None:
"""Holds the session's lock until stack closes, trying LOCK_TRIES times; returns None once it holds the lock, else the last try's failure."""
for _ in range(LOCK_TRIES):
attempt = contextlib.ExitStack()
unlocked = attempt.enter_context(held(folder, session))
if not unlocked:
stack.enter_context(attempt)
return None
attempt.close()
effects.sleep(0.1)
return unlocked
def running_loops(folder: pathlib.Path) -> list[RunningLoop]:
"""The loops that hold their lock, by checkout. A file that cannot be read or parsed is left out."""
try:
paths = list(folder.glob("*.running"))
except OSError:
return []
loops = [loop for path in paths if (loop := read_running(path)) and running(folder, loop.session)]
return sorted(loops, key=lambda loop: loop.root)
def drop_ended_loops(folder: pathlib.Path) -> None:
"""Removes each running file whose session's lock no loop holds: a loop that was killed leaves it behind. A file it cannot remove stays on disk, and running_loops leaves it out all the same."""
for session in ended(folder, "*.running"):
with contextlib.suppress(OSError):
running_file(folder, session).unlink(missing_ok=True)
def read_running(path: pathlib.Path) -> RunningLoop | None:
try:
data = json.loads(path.read_text(encoding="utf-8"))
except (OSError, ValueError):
return None
match data:
case {"root": str(root), "items": list(items)} if all(is_item(item) for item in items):
return RunningLoop(path.name.removesuffix(".running"), root, tuple(Taken(item["id"], item["tagline"]) for item in items))
return None
def is_item(item: object) -> bool:
match item:
# type(), not isinstance(): JSON true is no ID.
case {"id": id_, "tagline": str()} if type(id_) is int:
return True
return False
def taken_items(todo: str | Failure, routed: int, taken_in: tuple[int, ...]) -> tuple[Taken, ...]:
"""The items a chunk takes, as the module docstring says, with their taglines from todo, the default branch's todo.md. routed, the item the chunk was routed on, is 0 for none."""
found = items(todo) if isinstance(todo, str) else []
taglines = {item.id: item.tagline.removeprefix("**").removesuffix("**") for item in found} if isinstance(found, list) else {}
ids = dict.fromkeys(([routed] if routed else []) + list(taken_in))
return tuple(Taken(id_, taglines.get(id_, "")) for id_ in ids)
+18 -6
View File
@@ -1,7 +1,7 @@
"""The lock a loop-claude holds on its worker's session while loop-inbox lists the session's question. loop-inbox reads a held lock as a loop that still runs.
"""The lock by which loop-inbox tells whether a loop-claude still runs.
The lock is <session>.lock, held with flock, which the kernel frees however the loop ends, killed included. The lock
file stays once the loop ends: docs/decisions.md → `loop-inbox: …` says why.
A loop holds <session>.lock for its whole run (running_loops.py), with flock, which the kernel frees however the loop
ends, killed included. The lock file stays once the loop ends: docs/decisions.md → `loop-inbox: …` says why.
"""
import contextlib
import fcntl
@@ -17,14 +17,14 @@ def lock_file(folder: pathlib.Path, session: str) -> pathlib.Path:
@contextlib.contextmanager
def locked(folder: pathlib.Path, session: str) -> typing.Iterator[Failure | None]:
"""Holds the session's lock while the with block runs, or yields a Failure where it cannot. loop-inbox's drop_ended takes the lock for a moment on each ask still on disk, so a loop may find it held."""
def held(folder: pathlib.Path, session: str) -> typing.Iterator[Failure | None]:
"""Holds the session's lock while the with block runs, or yields a Failure where it cannot. loop-inbox takes the lock for a moment through ended, on each session whose files are still on disk, so a loop may find it held."""
path = lock_file(folder, session)
try:
make_private(folder)
except OSError as failure:
yield Failure(f"cannot make {folder}: {failure.strerror}")
return
path = lock_file(folder, session)
try:
handle = open(path, "a")
except OSError as failure:
@@ -42,6 +42,18 @@ def locked(folder: pathlib.Path, session: str) -> typing.Iterator[Failure | None
yield None
def ended(folder: pathlib.Path, pattern: str) -> typing.Iterator[str]:
"""Each session with a file in folder that matches pattern, such as "*.json", and whose lock no loop holds. It yields each while holding that lock, so a loop that starts meanwhile keeps its files."""
try:
sessions = {path.stem for path in folder.glob(pattern)}
except OSError:
return
for session in sessions:
with held(folder, session) as unlocked:
if not unlocked:
yield session
def running(folder: pathlib.Path, session: str) -> bool:
"""Whether a loop holds the session's lock; False also where the lock file cannot be opened or locked."""
try:
+30 -4
View File
@@ -18,7 +18,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from test_env import isolated_env
from loop_claude import waiting
from loop_claude import session_lock, waiting
BIN = pathlib.Path(__file__).resolve().parents[1]
TASK = "Do the next chunk."
@@ -38,6 +38,8 @@ role = "judge" if "--json-schema" in argv else "worker" if "-p" in argv else "in
scenario = pathlib.Path(os.environ["FAKE_CLAUDE_SCENARIO"])
steps = json.loads(scenario.read_text())
call = {{"argv": argv, "cwd": os.getcwd(), "role": role, "ctrl_c_ignored": signal.getsignal(signal.SIGINT) == signal.SIG_IGN}}
# The items each loop lists in loop-inbox as this claude starts.
call["running"] = [json.loads(path.read_text())["items"] for path in sorted((pathlib.Path.home() / ".local" / "state" / "loop-claude").glob("*.running"))]
if role == "judge":
call["stdin"] = sys.stdin.read()
with open(os.environ["FAKE_CLAUDE_LOG"], "a") as log:
@@ -143,8 +145,8 @@ def worker(**step):
return {"role": "worker", **step}
def judge(interrupt=False, finished=False, evidence="working", question="", highest_likelihood_taken_in=0, highest_escape_and_impact_taken_in=0, escalation="", release_ready=False, **step):
verdict = {"answer": "", "highest_likelihood_taken_in": highest_likelihood_taken_in, "highest_escape_and_impact_taken_in": highest_escape_and_impact_taken_in, "escalation": escalation, "evidence": evidence, "finished": finished, "interrupt": interrupt, "question": question, "release_ready": release_ready}
def judge(interrupt=False, finished=False, evidence="working", question="", items_taken_in=(), highest_likelihood_taken_in=0, highest_escape_and_impact_taken_in=0, escalation="", release_ready=False, **step):
verdict = {"items_taken_in": list(items_taken_in), "answer": "", "highest_likelihood_taken_in": highest_likelihood_taken_in, "highest_escape_and_impact_taken_in": highest_escape_and_impact_taken_in, "escalation": escalation, "evidence": evidence, "finished": finished, "interrupt": interrupt, "question": question, "release_ready": release_ready}
return {"role": "judge", "verdict": verdict, **step}
@@ -470,6 +472,16 @@ class Cycles(unittest.TestCase):
self.assertIn("item 6, L 4, E + I 5", prompt)
self.assertTrue((checkout.home / "code" / "proj-item-6").is_dir())
def test_lists_itself_in_loop_inbox_with_its_routed_item_then_those_the_judge_finds_taken_in_until_the_chunk_finishes(self):
checkout = Checkout(self)
checkout.env["LOOP_CLAUDE_WORKER_MODEL"] = "claude-opus-5-5"
checkout.commit_plan(TODO)
run = checkout.run([worker(), judge(items_taken_in=[7, 4]), worker(), judge(finished=True), worker()])
self.assertEqual(run.code, 130)
routed, taken_in = {"id": 4, "tagline": "Do it."}, {"id": 7, "tagline": ""}
self.assertEqual([call["running"] for call in run.calls], [[[routed]], [[routed]], [[routed, taken_in]], [[routed, taken_in]], [[routed]], [[routed]]])
self.assertEqual(list((checkout.home / ".local" / "state" / "loop-claude").glob("*.running")), [])
def test_steps_the_worker_up_a_rung_when_the_judge_finds_in_the_transcript_the_escalation_trigger_it_cites(self):
checkout = Checkout(self)
checkout.env["LOOP_CLAUDE_WORKER_MODEL"] = "claude-opus-5-5"
@@ -745,6 +757,20 @@ class Interrupt(unittest.TestCase):
self.assertIn("[human] B\n\nUsing B.", run.calls[3]["stdin"])
self.assertEqual([path for path in folder.iterdir() if path.suffix != ".lock"], [])
def test_a_second_loop_on_the_session_runs_unlisted_and_keeps_its_question_out_of_the_first_loops_folder(self):
checkout = Checkout(self)
folder = checkout.home / ".local" / "state" / "loop-claude"
asked = [worker(say="Shall I use A or B?"), judge(interrupt=True, evidence="Shall I use A or B?", question="A or B?")]
session = argument(checkout.run(asked).calls[0], "--session-id")
# The first loop on the session, still running.
self.enterContext(session_lock.held(folder, session))
asks = []
run = checkout.run(asked, terminal_input="\n", before_typing=("Answer (", lambda: asks.extend(folder.glob("*.json"))))
self.assertEqual(run.code, 2)
self.assertIn(f"loop-inbox cannot list this loop or its questions: another process holds {session_lock.lock_file(folder, session)}", run.stderr)
self.assertEqual((asks, run.calls[0]["running"]), ([], []))
self.assertFalse((folder / "unlisted").exists() and any((folder / "unlisted").iterdir()))
def test_hands_the_terminal_over_and_exits_2_when_nothing_is_typed(self):
checkout = Checkout(self)
checkout.git("commit", "--allow-empty", "--quiet", "-m", "start")
@@ -939,7 +965,7 @@ 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} 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, "items_taken_in": []} for cycle in (2, 3, 4)])
self.assertIn("=== cycle 5,", run.stdout)
outside = checkout.temp / "outside"
+95 -58
View File
@@ -24,9 +24,9 @@ from loop_claude.project import checkout, model_choice, records
from chunk_pick import DefaultPlan, LastCut
from loop_claude.effects import Effects, POLL_SECONDS, PYTHON_TIMEOUT, run_python, say, system_effects
from claude_code import entries, reply, session
from loop_claude import escalation_mark, hand_over, paths, routing, session_lock, waiting
from loop_claude import escalation_mark, hand_over, paths, routing, running_loops, session_lock, waiting
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, TakenIn, Unfinished
from loop_claude.cycle import interrupt, judge, prompts, retry, run, states, worker
from model_routing import ladder
from model_routing.ladder import LADDER, Rung
@@ -37,6 +37,7 @@ from transcript_archive import outcomes, write
from transcript_archive.location import project_archive
from model_routing.route import Route, route_from, WorkerLine
from loop_claude.stop import Stop
from loop_claude.running_loops import Taken
from utc_stamp import utc
from loop_claude.cycle.judge import verdict_from
@@ -144,8 +145,8 @@ def ran(stdout="", code=0, stderr=""):
return subprocess.CompletedProcess([], code, stdout, stderr)
def judged(verdict, evidence="working", answer="", escalation="", release_ready=False):
reply = {"answer": answer, "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": escalation, "evidence": evidence, "finished": verdict == "finished", "interrupt": verdict == "interrupt", "question": "Which one?" if verdict in ("interrupt", "quoted") else "", "release_ready": release_ready}
def judged(verdict, evidence="working", answer="", escalation="", release_ready=False, items_taken_in=()):
reply = {"items_taken_in": list(items_taken_in), "answer": answer, "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": escalation, "evidence": evidence, "finished": verdict == "finished", "interrupt": verdict == "interrupt", "question": "Which one?" if verdict in ("interrupt", "quoted") else "", "release_ready": release_ready}
return ran(json.dumps({"structured_output": reply}))
@@ -251,7 +252,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(effects=fake.effects(), facts=facts, judge_model="judge-model", paths=self.paths, 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.", unfinished_evidence=unfinished_evidence)
return run.Cycle(effects=fake.effects(), facts=facts, judge_model="judge-model", paths=self.paths, premises="## Goals", project=None, project_archive=self.archive, records=records, root=str(self.home), route=Route(Rung("worker-model")), session=self.session, show_taken_in=lambda items: None, task="Do it.", unfinished_evidence=unfinished_evidence)
def archived_outcomes(self):
return sorted(path.read_text() for path in self.archive.glob("*/*.outcomes.md"))
@@ -262,6 +263,20 @@ class Cycles(unittest.TestCase):
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: finished\n\nEvidence:\n> working\n\nJudge: judge-model\nWorker: {OFF_LADDER}\n"])
self.assertIsNone(session.transcript_file(self.session))
def test_shows_the_items_each_ruling_finds_the_chunk_takes_as_the_judge_gave_them(self):
worker = Worker(self.paths.claude_code_transcripts.parent)
fake = FakeEffects(streams=[worker], claude=[judged("unfinished", items_taken_in=(14, 3))])
shown = []
run.run_cycle(dataclasses.replace(self.cycle(fake), show_taken_in=shown.append))
self.assertEqual(shown, [(14, 3)])
def test_shows_no_items_for_a_finished_chunk(self):
worker = Worker(self.paths.claude_code_transcripts.parent)
fake = FakeEffects(streams=[worker], claude=[judged("finished", items_taken_in=(3,))])
shown = []
run.run_cycle(dataclasses.replace(self.cycle(fake), show_taken_in=shown.append))
self.assertEqual(shown, [])
def test_a_fresh_worker_reads_the_preflights_facts_and_a_resumed_one_does_not(self):
worker = Worker(self.paths.claude_code_transcripts.parent)
fake = FakeEffects(streams=[worker, worker], claude=[judged("unfinished"), judged("finished")])
@@ -434,7 +449,7 @@ class Cycles(unittest.TestCase):
for ruling in (Interrupt("e", "q", entries_read=3), QuotedAnswer("e", "q", "A.", entries_read=3)):
with self.subTest(ruling=ruling):
self.assertIsNone(run.ruling_step_up(cycle, ruling))
self.assertEqual(run.ruling_step_up(cycle, Interrupt("e", "q", "round 2: 🔴", 4, entries_read=3)), escalation_mark.StepUp(cycle.route, Route(Routing.XHIGH, 3, 3, 4, escalated_at=3)))
self.assertEqual(run.ruling_step_up(cycle, Interrupt("e", "q", "round 2: 🔴", TakenIn(highest_likelihood=4), entries_read=3)), escalation_mark.StepUp(cycle.route, Route(Routing.XHIGH, 3, 3, 4, escalated_at=3)))
def test_an_escalation_after_an_interrupt_stepped_the_worker_steps_it_again_in_the_same_cycle(self):
streams = [Worker(self.paths.claude_code_transcripts.parent, text="round 2: 🔴"), Worker(self.paths.claude_code_transcripts.parent), Worker(self.paths.claude_code_transcripts.parent)]
@@ -447,7 +462,7 @@ class Cycles(unittest.TestCase):
self.assertEqual([args[args.index("--effort") + 1] for args in fake.made("stream_claude")], ["high", "medium", "high"])
def test_an_escalation_quoted_from_before_the_workers_last_step_up_steps_nothing_and_a_later_one_reaches_the_verdict(self):
for escalation, verdict in (("round 2: 🔴", Unfinished("working", entries_read=4)), ("working", Unfinished("working", 0, "working", entries_read=4))):
for escalation, verdict in (("round 2: 🔴", Unfinished("working", entries_read=4)), ("working", Unfinished("working", "working", entries_read=4))):
with self.subTest(escalation=escalation):
self.session = session.session_named(f"A proj {escalation} loop-claude", self.paths.claude_code_transcripts)
streams = [Worker(self.paths.claude_code_transcripts.parent, text="round 2: 🔴"), Worker(self.paths.claude_code_transcripts.parent)]
@@ -668,7 +683,8 @@ 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?"):
with contextlib.redirect_stderr(io.StringIO()) as said:
"""interrupt's answer and what it said, run while the session's lock is held, as a running loop holds it."""
with contextlib.redirect_stderr(io.StringIO()) as said, session_lock.held(self.paths.waiting, str(self.session.id)):
answer = interrupt.interrupt(question, answer_here, self.session, self.paths, effects or fake.effects())
return answer, said.getvalue()
@@ -744,15 +760,6 @@ class Interrupts(unittest.TestCase):
stop, _ = self.put(FakeEffects(inputs=["/talk"], on_terminal_claude=[0], git=[""]))
self.assertEqual(stop, Stop(2, "the human is needed to answer the question above, but the interrupt ended with nothing typed"))
def test_leaves_the_question_another_loop_lists_for_the_session_where_that_loop_holds_its_lock(self):
theirs = self.ask(question="Theirs?")
self.enterContext(session_lock.locked(self.paths.waiting, theirs.session))
waiting.publish(self.paths.waiting, theirs)
answer, said = self.put(FakeEffects(inputs=["Use B."]))
self.assertEqual(answer, "Use B.")
self.assertIn(f"loop-inbox cannot show this question: another process holds {session_lock.lock_file(self.paths.waiting, theirs.session)}", said)
self.assertEqual(self.asked(), [theirs])
def test_makes_way_for_the_claude_loop_inbox_opens_and_goes_on_once_the_human_typed_there(self):
def claude_ran(_):
# loop-inbox opens claude only once the loop lists it as open there.
@@ -833,6 +840,7 @@ class RoutingCheck(unittest.TestCase):
def check(self, fake):
"""What check_routing returns and says for a loop in /code/log."""
with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()) as said:
self.enterContext(session_lock.held(self.paths.waiting, "s1"))
stop = routing_check.check_routing(self.root, "/code/log", "s1", Rung("m", "high"), self.paths, fake.effects())
return stop, said.getvalue()
@@ -955,12 +963,12 @@ TODO = """# todo
def unfinished(likelihood=0, escalated_at=None):
"""An unfinished verdict: the worker took in an item of that L, 0 for none, and the judge found an escalation after reading escalated_at transcript entries, None for none."""
return Unfinished("e", escalation="round 2: 🔴" if escalated_at is not None else "", highest_likelihood_taken_in=likelihood, entries_read=escalated_at)
return Unfinished("e", escalation="round 2: 🔴" if escalated_at is not None else "", taken_in=TakenIn(highest_likelihood=likelihood), entries_read=escalated_at)
def interrupted(likelihood=0, escalated_at=None):
"""An interrupt, its arguments as unfinished's."""
return Interrupt("e", "q", escalation="round 2: 🔴" if escalated_at is not None else "", highest_likelihood_taken_in=likelihood, entries_read=escalated_at)
return Interrupt("e", "q", escalation="round 2: 🔴" if escalated_at is not None else "", taken_in=TakenIn(highest_likelihood=likelihood), entries_read=escalated_at)
class Routing(unittest.TestCase):
@@ -1184,7 +1192,12 @@ class Steps(unittest.TestCase):
run_with = main.LoopRun(cycle_number=1, root="/r", task="do it", unfinished_evidence="old", route=Route(self.OPUS))
self.assertEqual(main.after_verdict(run_with, self.OPUS, run.Concluded(Finished("x"), run_with.route)), dataclasses.replace(run_with, route=None, unfinished_evidence=""))
self.assertEqual(main.after_verdict(dataclasses.replace(run_with, unfinished_run=3), self.OPUS, run.Concluded(Finished("x"), run_with.route)).unfinished_run, 0)
self.assertEqual(main.after_verdict(run_with, self.OPUS, run.Concluded(Unfinished("new", 4), run_with.route)), dataclasses.replace(run_with, route=Route(Rung("claude-opus-5-5", "high"), unfinished=1), unfinished_evidence="new", unfinished_run=1))
self.assertEqual(main.after_verdict(run_with, self.OPUS, run.Concluded(Unfinished("new", taken_in=TakenIn(highest_likelihood=4)), run_with.route)), dataclasses.replace(run_with, route=Route(Rung("claude-opus-5-5", "high"), unfinished=1), unfinished_evidence="new", unfinished_run=1))
def test_an_unfinished_chunk_keeps_the_items_its_verdict_found_taken_in_and_a_finished_one_drops_them(self):
run_with = main.LoopRun(cycle_number=1, root="/r", task="do it", unfinished_evidence="", route=Route(self.OPUS), items_taken_in=(3,))
self.assertEqual(main.after_verdict(run_with, self.OPUS, run.Concluded(Unfinished("new", taken_in=TakenIn((3, 12))), run_with.route)).items_taken_in, (3, 12))
self.assertEqual(main.after_verdict(run_with, self.OPUS, run.Concluded(Finished("x"), run_with.route)).items_taken_in, ())
def test_steps_from_the_route_its_cycle_ended_on_which_a_ruling_may_have_raised(self):
run_with = main.LoopRun(cycle_number=1, root="/r", task="do it", unfinished_evidence="", route=Route(self.OPUS, 3, 3, 4))
@@ -1194,11 +1207,11 @@ class Steps(unittest.TestCase):
def test_keeps_the_route_its_cycle_ended_on_off_the_ladder(self):
off_ladder = Route(Rung("worker-model"))
run_with = main.LoopRun(cycle_number=1, root="/r", task="do it", unfinished_evidence="")
self.assertEqual(main.after_verdict(run_with, None, run.Concluded(Unfinished("new", 4, "round 2: 🔴", entries_read=9), off_ladder)).route, off_ladder)
self.assertEqual(main.after_verdict(run_with, None, run.Concluded(Unfinished("new", "round 2: 🔴", TakenIn(highest_likelihood=4), entries_read=9), off_ladder)).route, off_ladder)
def test_an_unfinished_verdicts_escalation_marks_the_transcript_entries_the_judge_read(self):
run_with = main.LoopRun(cycle_number=1, root="/r", task="do it", unfinished_evidence="", route=Route(self.OPUS, 3, 3, 4, escalated_at=2))
self.assertEqual(main.after_verdict(run_with, self.OPUS, run.Concluded(Unfinished("new", 0, "round 2: 🔴", entries_read=9), run_with.route)).route, Route(Rung("claude-opus-5-5", "high"), 3, 3, 4, escalated_at=9))
self.assertEqual(main.after_verdict(run_with, self.OPUS, run.Concluded(Unfinished("new", "round 2: 🔴", entries_read=9), run_with.route)).route, Route(Rung("claude-opus-5-5", "high"), 3, 3, 4, escalated_at=9))
self.assertEqual(main.after_verdict(run_with, self.OPUS, run.Concluded(Unfinished("new", entries_read=9), run_with.route)).route, Route(self.OPUS, 3, 3, 4, unfinished=1, escalated_at=2))
def test_archives_a_step_up_as_it_happens_so_a_rerun_resumes_on_it(self):
@@ -1211,7 +1224,7 @@ class Steps(unittest.TestCase):
before = Route(self.OPUS, 3, 3, 4)
with contextlib.redirect_stderr(io.StringIO()):
self.assertIsNone(write.archive(archive, str(transcript), "Do it.", outcomes.unfinished(before.worker_line(), "working", "j", ""), NOW))
after = main.after_verdict(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), self.OPUS, run.Concluded(Unfinished("working", 4), before))
after = main.after_verdict(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), self.OPUS, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_likelihood=4)), before))
self.assertIsNone(main.archive_step(archive, opened, "Do it.", before, after.route, FakeEffects().effects()))
self.assertEqual(main.archived_route(archive, opened, FakeEffects().effects()), Route(Rung("claude-opus-5-5", "high"), 3, 3, 4))
self.assertIsNone(main.archive_step(archive, opened, "Do it.", after.route, after.route, FakeEffects().effects()))
@@ -1233,12 +1246,18 @@ class Steps(unittest.TestCase):
before = Route(self.OPUS, 3, 3, 4)
with contextlib.redirect_stderr(io.StringIO()):
self.assertIsNone(write.archive(archive, str(transcript), "Do it.", outcomes.unfinished(before.worker_line(), "working", "j", ""), NOW))
after = main.after_verdict(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), self.OPUS, run.Concluded(Unfinished("working", highest_escape_and_impact_taken_in=6), before))
after = main.after_verdict(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), self.OPUS, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_escape_and_impact=6)), before))
self.assertIsNone(main.archive_step(archive, opened, "Do it.", before, after.route, FakeEffects().effects()))
self.assertEqual(main.archived_route(archive, opened, FakeEffects().effects()), Route(self.OPUS, 3, 3, 4, escape_and_impact_taken_in=6))
class ChunkFacts(unittest.TestCase):
def test_names_the_routed_item_then_each_taken_in_once_by_its_tagline_on_the_default_branch(self):
self.assertEqual(running_loops.taken_items(TODO, 3, (99, 3, 99)), (Taken(3, "Do the next thing."), Taken(99, "")))
self.assertEqual(running_loops.taken_items(TODO, 0, (3,)), (Taken(3, "Do the next thing."),))
self.assertEqual(running_loops.taken_items(Failure("no todo.md"), 3, ()), (Taken(3, ""),))
self.assertEqual(running_loops.taken_items(TODO, 0, ()), ())
PREFLIGHT = pathlib.Path("/b/chunk-preflight")
def test_runs_the_preflight_at_the_checkout_root_and_quotes_what_it_printed(self):
@@ -1296,23 +1315,23 @@ class SessionLock(unittest.TestCase):
def test_a_held_lock_refuses_a_second_taker_and_reads_as_running_until_let_go(self):
self.assertFalse(session_lock.running(self.folder, "s1"))
with session_lock.locked(self.folder, "s1") as first:
with session_lock.held(self.folder, "s1") as first:
self.assertIsNone(first)
with session_lock.locked(self.folder, "s1") as second:
with session_lock.held(self.folder, "s1") as second:
self.assertEqual(second, Failure(f"another process holds {self.path}"))
self.assertTrue(session_lock.running(self.folder, "s1"))
self.assertFalse(session_lock.running(self.folder, "s1"))
def test_a_lock_that_cannot_be_opened_is_a_failure_and_no_loop_running(self):
self.path.mkdir()
with session_lock.locked(self.folder, "s1") as unlocked:
with session_lock.held(self.folder, "s1") as unlocked:
self.assertEqual(unlocked, Failure(f"cannot open {self.path}: Is a directory"))
self.assertFalse(session_lock.running(self.folder, "s1"))
def test_a_lock_the_kernel_refuses_is_a_failure_and_no_loop_running(self):
self.path.touch()
with unittest.mock.patch("fcntl.flock", side_effect=OSError(errno.ENOLCK, "No locks available")):
with session_lock.locked(self.folder, "s1") as unlocked:
with session_lock.held(self.folder, "s1") as unlocked:
self.assertEqual(unlocked, Failure(f"cannot lock {self.path}: No locks available"))
self.assertFalse(session_lock.running(self.folder, "s1"))
@@ -1579,8 +1598,8 @@ class JudgePrompt(unittest.TestCase):
def test_drops_an_escalation_quote_from_after_the_step_up_that_the_tail_it_shows_cuts_off(self):
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "old " + "x" * judge.JUDGE_PROMPT_CHARS}), assistant({"type": "text", "text": "new"})]
_, grounds = judge.judge_prompt("Do it.", "## Goals", "", entries, 1)
self.assertEqual(judge.quotes_checked(Unfinished("e", 0, "old x", entries_read=3), grounds), Unfinished("e", entries_read=3))
self.assertEqual(judge.quotes_checked(Unfinished("e", 0, "new", entries_read=3), grounds), Unfinished("e", 0, "new", entries_read=3))
self.assertEqual(judge.quotes_checked(Unfinished("e", "old x", entries_read=3), grounds), Unfinished("e", entries_read=3))
self.assertEqual(judge.quotes_checked(Unfinished("e", "new", entries_read=3), grounds), Unfinished("e", "new", entries_read=3))
def test_shows_a_typed_answer_before_the_step_up_as_the_humans(self):
typed = prompts.typed("Which one?", "Use B.", Route(Rung("worker-model")), None, False)
@@ -1610,58 +1629,68 @@ class Grounded(unittest.TestCase):
class Verdict(unittest.TestCase):
def test_needs_every_field_the_schema_requires(self):
self.assertEqual(verdict_from({"highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": False, "evidence": "e", "finished": True, "question": "", "release_ready": False}), Finished("e"))
self.assertEqual(verdict_from({"highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": False, "evidence": "e", "finished": False, "question": "ignored", "release_ready": False}), Unfinished("e"))
self.assertEqual(verdict_from({"highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": True, "evidence": "e", "finished": True, "question": "Which one?", "release_ready": False}), Interrupt("e", "Which one?"))
self.assertEqual(verdict_from({"highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": True, "evidence": "e", "finished": False, "question": "Cut 0.2.0?", "release_ready": True}), Interrupt("e", "Cut 0.2.0?", release_ready=True))
self.assertEqual(verdict_from({"highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": True, "evidence": "e", "finished": False, "question": "Cut 0.2.0?"}), Failure("the judge's reply has no release_ready of type boolean"))
self.assertEqual(verdict_from({"highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "A.", "interrupt": False, "evidence": "e", "finished": False, "question": "Which one?", "release_ready": False}), QuotedAnswer("e", "Which one?", "A."))
self.assertEqual(verdict_from({"highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "A.", "interrupt": True, "evidence": "e", "finished": False, "question": "Which one?", "release_ready": False}), Interrupt("e", "Which one?"))
self.assertEqual(verdict_from({"highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "A.", "interrupt": False, "evidence": "e", "finished": True, "question": "", "release_ready": False}), Failure("the judge quoted an answer without a question"))
self.assertEqual(verdict_from({"highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": "no", "evidence": "", "finished": True, "question": "", "release_ready": False}), Failure("the judge's reply has no interrupt of type boolean"))
self.assertEqual(verdict_from({"highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": False, "evidence": None, "finished": True, "question": "", "release_ready": False}), Failure("the judge's reply has no evidence of type string"))
self.assertEqual(verdict_from({"highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": True, "evidence": "x", "finished": False, "question": " ", "release_ready": False}), Failure("the judge interrupted without a question"))
self.assertEqual(verdict_from({"items_taken_in": [], "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": False, "evidence": "e", "finished": True, "question": "", "release_ready": False}), Finished("e"))
self.assertEqual(verdict_from({"items_taken_in": [], "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": False, "evidence": "e", "finished": False, "question": "ignored", "release_ready": False}), Unfinished("e"))
self.assertEqual(verdict_from({"items_taken_in": [], "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": True, "evidence": "e", "finished": True, "question": "Which one?", "release_ready": False}), Interrupt("e", "Which one?"))
self.assertEqual(verdict_from({"items_taken_in": [], "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": True, "evidence": "e", "finished": False, "question": "Cut 0.2.0?", "release_ready": True}), Interrupt("e", "Cut 0.2.0?", release_ready=True))
self.assertEqual(verdict_from({"items_taken_in": [], "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": True, "evidence": "e", "finished": False, "question": "Cut 0.2.0?"}), Failure("the judge's reply has no release_ready of type boolean"))
self.assertEqual(verdict_from({"items_taken_in": [], "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "A.", "interrupt": False, "evidence": "e", "finished": False, "question": "Which one?", "release_ready": False}), QuotedAnswer("e", "Which one?", "A."))
self.assertEqual(verdict_from({"items_taken_in": [], "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "A.", "interrupt": True, "evidence": "e", "finished": False, "question": "Which one?", "release_ready": False}), Interrupt("e", "Which one?"))
self.assertEqual(verdict_from({"items_taken_in": [], "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "A.", "interrupt": False, "evidence": "e", "finished": True, "question": "", "release_ready": False}), Failure("the judge quoted an answer without a question"))
self.assertEqual(verdict_from({"items_taken_in": [], "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": "no", "evidence": "", "finished": True, "question": "", "release_ready": False}), Failure("the judge's reply has no interrupt of type boolean"))
self.assertEqual(verdict_from({"items_taken_in": [], "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": False, "evidence": None, "finished": True, "question": "", "release_ready": False}), Failure("the judge's reply has no evidence of type string"))
self.assertEqual(verdict_from({"items_taken_in": [], "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "answer": "", "interrupt": True, "evidence": "x", "finished": False, "question": " ", "release_ready": False}), Failure("the judge interrupted without a question"))
self.assertEqual(verdict_from(None), Failure("the judge returned no reply"))
def test_takes_the_highest_l_taken_in_on_its_scale_and_counts_any_other_as_none(self):
reply = {"answer": "", "highest_escape_and_impact_taken_in": 0, "escalation": "", "interrupt": False, "evidence": "e", "finished": False, "question": "", "release_ready": False}
self.assertEqual(verdict_from({**reply, "highest_likelihood_taken_in": 4}), Unfinished("e", 4))
reply = {"items_taken_in": [], "answer": "", "highest_escape_and_impact_taken_in": 0, "escalation": "", "interrupt": False, "evidence": "e", "finished": False, "question": "", "release_ready": False}
self.assertEqual(verdict_from({**reply, "highest_likelihood_taken_in": 4}), Unfinished("e", taken_in=TakenIn(highest_likelihood=4)))
self.assertEqual(verdict_from({**reply, "highest_likelihood_taken_in": True}), Failure("the judge's reply has no highest_likelihood_taken_in of type integer"))
for highest_likelihood_taken_in in (5, 13, -1):
with self.subTest(highest_likelihood_taken_in=highest_likelihood_taken_in):
self.assertEqual(verdict_from({**reply, "highest_likelihood_taken_in": highest_likelihood_taken_in}), Unfinished("e", 0))
self.assertEqual(verdict_from({**reply, "highest_likelihood_taken_in": highest_likelihood_taken_in}), Unfinished("e"))
def test_takes_the_highest_e_plus_i_taken_in_on_its_scale_and_counts_any_other_as_none(self):
reply = {"answer": "", "highest_likelihood_taken_in": 0, "escalation": "", "interrupt": False, "evidence": "e", "finished": False, "question": "", "release_ready": False}
self.assertEqual(verdict_from({**reply, "highest_escape_and_impact_taken_in": 6}), Unfinished("e", 0, highest_escape_and_impact_taken_in=6))
self.assertEqual(verdict_from({**reply, "highest_escape_and_impact_taken_in": 2}), Unfinished("e", 0, highest_escape_and_impact_taken_in=2))
reply = {"items_taken_in": [], "answer": "", "highest_likelihood_taken_in": 0, "escalation": "", "interrupt": False, "evidence": "e", "finished": False, "question": "", "release_ready": False}
self.assertEqual(verdict_from({**reply, "highest_escape_and_impact_taken_in": 6}), Unfinished("e", taken_in=TakenIn(highest_escape_and_impact=6)))
self.assertEqual(verdict_from({**reply, "highest_escape_and_impact_taken_in": 2}), Unfinished("e", taken_in=TakenIn(highest_escape_and_impact=2)))
self.assertEqual(verdict_from({**reply, "highest_escape_and_impact_taken_in": False}), Failure("the judge's reply has no highest_escape_and_impact_taken_in of type integer"))
for escape_and_impact in (1, 9, -1):
with self.subTest(escape_and_impact=escape_and_impact):
self.assertEqual(verdict_from({**reply, "highest_escape_and_impact_taken_in": escape_and_impact}), Unfinished("e", 0))
self.assertEqual(verdict_from({**reply, "highest_escape_and_impact_taken_in": escape_and_impact}), Unfinished("e"))
def test_takes_the_items_taken_in_as_the_judge_gives_them_leaving_out_ids_below_1(self):
reply = {"items_taken_in": [], "answer": "", "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "", "interrupt": False, "evidence": "e", "finished": False, "question": "", "release_ready": False}
self.assertEqual(verdict_from({**reply, "items_taken_in": [12, 14, 12]}), Unfinished("e", taken_in=TakenIn((12, 14, 12))))
self.assertEqual(verdict_from({**reply, "items_taken_in": [7, 0]}), Unfinished("e", taken_in=TakenIn((7,))))
self.assertEqual(verdict_from({**reply, "items_taken_in": [3], "interrupt": True, "question": "Which one?"}), Interrupt("e", "Which one?", taken_in=TakenIn((3,))))
self.assertEqual(verdict_from({**reply, "items_taken_in": [3], "answer": "A.", "question": "Which one?"}), QuotedAnswer("e", "Which one?", "A.", taken_in=TakenIn((3,))))
self.assertEqual(verdict_from({**reply, "items_taken_in": [3], "finished": True}), Finished("e"))
self.assertEqual(verdict_from({**reply, "items_taken_in": "3"}), Failure("the judge's reply has no items_taken_in of type array of integers"))
self.assertEqual(verdict_from({**reply, "items_taken_in": ["3"]}), Failure("the judge's reply has no items_taken_in of type array of integers"))
def test_takes_an_escalation_quote_on_an_unfinished_verdict(self):
reply = {"answer": "", "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "round 2: 🔴", "interrupt": False, "evidence": "e", "finished": False, "question": "", "release_ready": False}
self.assertEqual(verdict_from(reply), Unfinished("e", 0, "round 2: 🔴"))
reply = {"items_taken_in": [], "answer": "", "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "round 2: 🔴", "interrupt": False, "evidence": "e", "finished": False, "question": "", "release_ready": False}
self.assertEqual(verdict_from(reply), Unfinished("e", "round 2: 🔴"))
self.assertEqual(verdict_from({**reply, "finished": True}), Finished("e"))
self.assertEqual(verdict_from({**reply, "escalation": None}), Failure("the judge's reply has no escalation of type string"))
def test_takes_an_escalation_quote_on_an_interrupt(self):
reply = {"answer": "", "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "round 2: 🔴", "interrupt": True, "evidence": "e", "finished": False, "question": "Which one?", "release_ready": False}
reply = {"items_taken_in": [], "answer": "", "highest_likelihood_taken_in": 0, "highest_escape_and_impact_taken_in": 0, "escalation": "round 2: 🔴", "interrupt": True, "evidence": "e", "finished": False, "question": "Which one?", "release_ready": False}
self.assertEqual(verdict_from(reply), Interrupt("e", "Which one?", "round 2: 🔴"))
self.assertEqual(verdict_from({**reply, "highest_likelihood_taken_in": 4}), Interrupt("e", "Which one?", "round 2: 🔴", 4))
self.assertEqual(verdict_from({**reply, "highest_likelihood_taken_in": 4}), Interrupt("e", "Which one?", "round 2: 🔴", TakenIn(highest_likelihood=4)))
self.assertEqual(verdict_from({**reply, "highest_likelihood_taken_in": 5}), Interrupt("e", "Which one?", "round 2: 🔴"))
def test_drops_an_escalation_quote_the_transcript_does_not_hold_word_for_word_from_an_interrupt_or_an_unfinished_verdict(self):
shown = "The agent: round 2: 🔴. Which one?"
self.assertEqual(judge.quotes_checked(Interrupt("e", "q", "round 2: 🔴"), judge.Grounds(shown, shown, "")), Interrupt("e", "q", "round 2: 🔴"))
self.assertEqual(judge.quotes_checked(Interrupt("e", "q", "round 2: … 🔴"), judge.Grounds(shown, shown, "")), Interrupt("e", "q"))
self.assertEqual(judge.quotes_checked(Unfinished("e", 0, "round 3: 🔴"), judge.Grounds(shown, shown, "")), Unfinished("e"))
self.assertEqual(judge.quotes_checked(Unfinished("e", "round 3: 🔴"), judge.Grounds(shown, shown, "")), Unfinished("e"))
def test_takes_an_escalation_quote_and_the_highest_l_taken_in_on_a_quoted_answer(self):
reply = {"answer": "A.", "highest_likelihood_taken_in": 4, "highest_escape_and_impact_taken_in": 0, "escalation": "round 2: 🔴", "interrupt": False, "evidence": "e", "finished": False, "question": "Which one?", "release_ready": False}
self.assertEqual(verdict_from(reply), QuotedAnswer("e", "Which one?", "A.", "round 2: 🔴", 4))
reply = {"items_taken_in": [], "answer": "A.", "highest_likelihood_taken_in": 4, "highest_escape_and_impact_taken_in": 0, "escalation": "round 2: 🔴", "interrupt": False, "evidence": "e", "finished": False, "question": "Which one?", "release_ready": False}
self.assertEqual(verdict_from(reply), QuotedAnswer("e", "Which one?", "A.", "round 2: 🔴", TakenIn(highest_likelihood=4)))
self.assertEqual(verdict_from({**reply, "highest_likelihood_taken_in": 5}), QuotedAnswer("e", "Which one?", "A.", "round 2: 🔴"))
def test_drops_an_escalation_quote_the_transcript_does_not_hold_word_for_word_from_a_quoted_answer(self):
@@ -1670,7 +1699,8 @@ class Verdict(unittest.TestCase):
self.assertEqual(judge.quotes_checked(QuotedAnswer("e", "q", "A.", "round 2: … 🔴"), judge.Grounds(shown, shown, "A.")), QuotedAnswer("e", "q", "A."))
def test_puts_a_quoted_answer_the_records_do_not_hold_to_the_human_with_the_escalation_it_carried(self):
self.assertEqual(judge.quotes_checked(QuotedAnswer("e", "q", "not there", "round 2: 🔴", 4), judge.Grounds("The agent: round 2: 🔴.", "The agent: round 2: 🔴.", "A.")), Interrupt("e", "q", "round 2: 🔴", 4))
self.assertEqual(judge.quotes_checked(QuotedAnswer("e", "q", "not there", taken_in=TakenIn((3,))), judge.Grounds("shown", "shown", "A.")), Interrupt("e", "q", taken_in=TakenIn((3,))))
self.assertEqual(judge.quotes_checked(QuotedAnswer("e", "q", "not there", "round 2: 🔴", TakenIn(highest_likelihood=4)), judge.Grounds("The agent: round 2: 🔴.", "The agent: round 2: 🔴.", "A.")), Interrupt("e", "q", "round 2: 🔴", TakenIn(highest_likelihood=4)))
def test_puts_a_quoted_answer_the_records_do_not_hold_word_for_word_to_the_human(self):
self.assertEqual(judge.quotes_checked(QuotedAnswer("e", "q", "not there"), judge.Grounds("shown", "shown", "the records")), Interrupt("e", "q"))
@@ -1680,9 +1710,9 @@ class Verdict(unittest.TestCase):
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "round 3: 🔴"}), assistant({"type": "text", "text": "working"})]
def judged_on(mark, escalation):
return judge.judge_once("/r", "Do it.", "## Goals", "", entries, mark, Rung("judge-model"), FakeEffects(claude=[judged("unfinished", escalation=escalation)]).effects())
self.assertEqual(judged_on(0, "round 2: 🔴"), Unfinished("working", 0, "round 2: 🔴", entries_read=3))
self.assertEqual(judged_on(0, "round 2: 🔴"), Unfinished("working", "round 2: 🔴", entries_read=3))
self.assertEqual(judged_on(1, "round 2: 🔴"), Unfinished("working", entries_read=3))
self.assertEqual(judged_on(1, "round 3: 🔴"), Unfinished("working", 0, "round 3: 🔴", entries_read=3))
self.assertEqual(judged_on(1, "round 3: 🔴"), Unfinished("working", "round 3: 🔴", entries_read=3))
self.assertEqual(judged_on(1, "round 2: 🔴\n\nround 3: 🔴"), Unfinished("working", entries_read=3))
self.assertEqual(judged_on(3, "round 3: 🔴"), Unfinished("working", entries_read=3))
@@ -1742,6 +1772,13 @@ class LoopRuns(unittest.TestCase):
def test_decodes_a_state_from_before_a_field_with_a_default_joined_it(self):
self.assertEqual(reload.decode_handed(json.dumps({"cycle_number": 3, "root": "/r", "task": "do it", "unfinished_evidence": ""}), main.LoopRun), main.LoopRun(3, "/r", "do it", ""))
def test_decodes_the_items_taken_in_as_a_tuple_of_ids(self):
state = main.LoopRun(cycle_number=1, root="/r", task="do it", unfinished_evidence="", items_taken_in=(12, 14))
self.assertEqual(reload.decode_handed(json.dumps(dataclasses.asdict(state)), main.LoopRun), state)
for taken_in in ([12, "14"], [True], "12", {"12": 1}):
with self.subTest(taken_in=taken_in):
self.assertIsNone(reload.decode_handed(json.dumps(dataclasses.asdict(state) | {"items_taken_in": taken_in}), main.LoopRun))
def test_stops_when_the_reload_cannot_start_python(self):
with tempfile.TemporaryDirectory() as root:
launcher = pathlib.Path(root, "loop-claude")
+14 -8
View File
@@ -2,14 +2,24 @@
import dataclasses
@dataclasses.dataclass(frozen=True)
class TakenIn:
"""What the judge read in the transcript about the todo.md items the worker took into the chunk, the item the chunk was routed on included."""
# Their IDs; loop-inbox lists them.
items: tuple[int, ...] = ()
# The highest L among them, 0 for none: an escalation steps up from the rung that L picks, and an unfinished verdict also raises the worker to it.
highest_likelihood: int = 0
# The highest E + I among them, 0 for none: after an unfinished verdict, it routes the next cycle's judge and reviewers.
highest_escape_and_impact: int = 0
@dataclasses.dataclass(frozen=True)
class Interrupt:
evidence: str
question: str
# The judge's quote showing that the worker's cited escalation trigger fired; empty for none.
escalation: str = ""
# The highest L the judge saw the worker take into the chunk, 0 for none: an escalation steps up from the rung that L picks.
highest_likelihood_taken_in: int = 0
taken_in: TakenIn = TakenIn()
release_ready: bool = False
# How many transcript entries the judge read, which escalation_mark.stamped stamps. An escalation the verdict carries moves the route's mark there. None means it was never stamped, and then its escalation doesn't step the worker.
entries_read: int | None = None
@@ -23,7 +33,7 @@ class QuotedAnswer:
answer: str
# As on Interrupt.
escalation: str = ""
highest_likelihood_taken_in: int = 0
taken_in: TakenIn = TakenIn()
entries_read: int | None = None
@@ -35,13 +45,9 @@ class Finished:
@dataclasses.dataclass(frozen=True)
class Unfinished:
evidence: str
# As on Interrupt; the worker also rises to the rung that L picks.
highest_likelihood_taken_in: int = 0
# As on Interrupt.
escalation: str = ""
# The highest E + I the judge saw the worker take into the chunk, 0 for none.
highest_escape_and_impact_taken_in: int = 0
# As on Interrupt.
taken_in: TakenIn = TakenIn()
entries_read: int | None = None
+19 -27
View File
@@ -1,11 +1,11 @@
"""The files by which a loop-claude shows its interrupt in loop-inbox, and takes an answer typed there.
A waiting loop keeps its ask in <session>.json in Paths.waiting: the question, with an id new for each question.
<session> is the worker's session id, so a loop lists one question at a time. The loop holds the session's lock while it
lists the ask, and removes the ask once the question is answered or the loop stops. loop-inbox lists an ask only while
its lock is held, and removes one whose lock is free. The ask's state says whether the loop waits for an answer, or has
claude open for it, on the loop's own terminal or in loop-inbox. loop-inbox answers by replacing <session>.answer, which
names the ask's id. So an answer meant for an earlier question, or sent as the loop took an answer on its terminal,
<session> is the worker's session id, so a loop lists one question at a time. The loop removes the ask once the question
is answered or the loop stops. loop-inbox lists an ask only while the loop holds the session's lock (running_loops.py),
and removes one whose lock is free. The ask's state says whether the loop waits for an answer, or has claude open for
it, on the loop's own terminal or in loop-inbox. loop-inbox answers by replacing <session>.answer, which names the
ask's id. So an answer meant for an earlier question, or sent as the loop took an answer on its terminal,
never answers a later one.
/talk from loop-inbox goes in three steps, so that only one claude ever holds the worker's session:
@@ -23,8 +23,8 @@ import typing
from loop_claude.hand_over import ClaudeCommand
from loop_claude.effects import Effects, POLL_SECONDS, say
from loop_claude.session_lock import ended, running
from failure import Failure
from loop_claude.session_lock import locked, running
from file_writes import make_private, replace_json
# Seconds loop-inbox waits for a loop to make way for its claude: ten of the loop's looks, so a loop slow for a moment still makes way.
@@ -121,18 +121,16 @@ def shown(folder: pathlib.Path, ask: Ask, effects: Effects) -> None:
@contextlib.contextmanager
def listed(folder: pathlib.Path, ask: Ask, effects: Effects) -> typing.Iterator[None]:
"""Lists ask in loop-inbox while the with block runs, then takes it out, with any answer. A failure to list it only warns: the question is still answered on the loop's terminal."""
with locked(folder, ask.session) as unlocked:
if unlocked:
say(f"loop-inbox cannot show this question: {unlocked.reason}", effects)
yield
return
shown(folder, ask, effects)
try:
yield
finally:
# An ask this fails to remove is left to loop-inbox, which stops listing it once the lock is let go, and removes it.
withdraw(folder, ask.session)
"""Lists ask in loop-inbox while the with block runs, then takes it out, with any answer. A failure to list it only warns: the question is still answered on the loop's terminal.
listed doesn't take the session's lock, which loop-inbox needs held to list the ask. Pass the folder running_loops.shown_running yields: shown_running holds the lock for the loop's whole run.
"""
shown(folder, ask, effects)
try:
yield
finally:
# An ask this fails to remove is left to loop-inbox, which stops listing it once the lock is let go, and removes it.
withdraw(folder, ask.session)
def waiting(folder: pathlib.Path) -> list[Ask]:
@@ -146,15 +144,9 @@ def waiting(folder: pathlib.Path) -> list[Ask]:
def drop_ended(folder: pathlib.Path) -> None:
"""Removes each ask, with any answer, whose session's lock no loop holds: a loop that was killed leaves its ask behind. It removes one while holding the lock, so a loop that lists a new ask meanwhile keeps it. An ask it cannot remove stays on disk, and waiting leaves it out all the same."""
try:
paths = list(folder.glob("*.json"))
except OSError:
return
for path in paths:
with locked(folder, path.stem) as unlocked:
if not unlocked:
withdraw(folder, path.stem)
"""Removes each ask, with any answer, whose session's lock no loop holds: a loop that was killed leaves its ask behind. An ask it cannot remove stays on disk, and waiting leaves it out all the same."""
for session in ended(folder, "*.json"):
withdraw(folder, session)
def read_ask(path: pathlib.Path) -> Ask | None:
+28 -3
View File
@@ -3,12 +3,15 @@
How it shows the loops and a question was picked on 2026-10-28 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: a block per
loop with its checkout's path and how long it has waited, and an answer prompt saying that Enter alone doesn't stop the loop.
A second bench, on 2026-10-29, picked the running loops' section: below the waiting loops, a line per loop with its
checkout and its number in the list above where it waits for an answer, then a line per item its chunk takes, with its ID and tagline.
"""
import dataclasses
import textwrap
import typing
from loop_claude.waiting import Ask, Asking, OpenInInbox, OpenOnTerminal, TALK
from loop_claude.running_loops import RunningLoop, Taken
ENTER = "enter"
BACKSPACE = "backspace"
@@ -24,10 +27,11 @@ NARROWEST = 20
@dataclasses.dataclass(frozen=True)
class Listing:
"""The waiting loops as they were when the human began typing a number, so a loop's number doesn't change while they type it."""
"""The waiting and running loops as they were when the human began typing a number, so a loop's number doesn't change while they type it."""
shown: tuple[Ask, ...] = ()
typed: str = ""
note: str = ""
running: tuple[RunningLoop, ...] = ()
@dataclasses.dataclass(frozen=True)
@@ -65,9 +69,9 @@ def pressed(screen: Screen, key: str) -> Screen | Send | Open | Quit:
if key == ENTER:
return picked(shown, typed)
if key == BACKSPACE:
return Listing(shown, typed[:-1])
return dataclasses.replace(screen, typed=typed[:-1], note="")
# isdigit would also take "²", which int() rejects.
return Listing(shown, typed + key) if key.isdecimal() else screen
return dataclasses.replace(screen, typed=typed + key, note="") if key.isdecimal() else screen
case Answering(ask, typed):
if key == ESCAPE or (key == ENTER and not typed.strip()):
return Listing()
@@ -106,10 +110,31 @@ def listing_lines(screen: Listing, now: float, local_time: typing.Callable[[floa
lines += wrapped(f"[{number}] {ask.root}, waiting since {local_time(ask.asked)} ({waited(now - ask.asked)}){state}", width)
lines += cut(wrapped(ask.question, width - len(INDENT) - len(ELLIPSIS)), SHOWN_LINES)
lines.append("")
lines += running_lines(screen.running, screen.shown, width)
ask_for = "Type a number and Enter to answer that loop; " if count else ""
return lines, [*wrapped(screen.note, width), *wrapped(f"{ask_for}{QUIT} quits loop-inbox, and the loops keep waiting.", width), *typed_after(">", screen.typed, width)]
def running_lines(running: tuple[RunningLoop, ...], shown: tuple[Ask, ...], width: int) -> list[str]:
"""Each running loop's checkout, with its number in the waiting list where it waits for an answer, and a line per item its chunk takes."""
if not running:
return ["No loop runs."]
numbers = {ask.session: number for number, ask in enumerate(shown, 1)}
lines = wrapped(f"Running: {len(running)} loop{'s' if len(running) > 1 else ''}", width)
for loop in running:
waits_as = f", waiting as [{numbers[loop.session]}]" if loop.session in numbers else ""
lines += wrapped(f"- {loop.root}{waits_as}", width)
for item in loop.items or (None,):
lines += cut(wrapped(item_line(item), width - len(INDENT) - len(ELLIPSIS)), 1)
return lines
def item_line(item: Taken | None) -> str:
if item is None:
return "no todo.md item yet"
return f"item {item.id}: {item.tagline}" if item.tagline else f"item {item.id}"
def answering_lines(screen: Answering, now: float, local_time: typing.Callable[[float], str], width: int) -> tuple[list[str], list[str]]:
"""The question, in lines of at most width characters, and its foot, the prompt for the answer."""
ask = screen.ask
+11 -3
View File
@@ -1,4 +1,5 @@
"""Show the interrupts of every loop-claude on this machine, oldest first, and answer each one here.
Below them, list every loop-claude that runs and the todo.md items its chunk takes.
usage: loop-inbox
@@ -20,8 +21,13 @@ loop-inbox running. A loop with claude open, for a release ready to cut, the rou
asking for its project's model, as on a project's first run, asks on its own terminal only. q quits
loop-inbox; the loops keep waiting.
Below the questions, loop-inbox lists each running loop: its checkout, its number in the list
above where it waits for an answer, and a line per todo.md item its chunk takes, with the item's
tagline on the default branch. A loop whose process is gone drops off this list too.
The loops' questions are files in ~/.local/state/loop-claude, read and written as
bin/loop_claude/waiting.py describes.
bin/loop_claude/waiting.py describes; the running loops are files beside them, as
bin/loop_claude/running_loops.py describes.
Exit 2 when stdin or stdout is not a terminal, or on an unknown argument.
"""
@@ -34,6 +40,7 @@ import typing
from loop_inbox.inbox import Answering, answering_lines, BACKSPACE, ENTER, ESCAPE, fitted, Listing, listing_lines, Open, pressed, Quit, Screen, Send
from loop_claude.waiting import Ask, ask_file, Asking, claim_talk, ClaudeEnded, drop_ended, MAKE_WAY_SECONDS, read_ask, send, Typed, waiting
from loop_claude.running_loops import drop_ended_loops, running_loops
from loop_claude.effects import Effects, system_effects
from failure import Failure
from loop_claude.hand_over import hand_over
@@ -71,6 +78,7 @@ def run(window: curses.window, screen_off: typing.Callable[[], typing.ContextMan
screen: Screen = Listing()
while True:
drop_ended(folder)
drop_ended_loops(folder)
screen = entered(screen, refreshed(screen, folder), effects)
draw(window, screen, effects)
try:
@@ -103,10 +111,10 @@ def key_name(key: str | int) -> str:
def refreshed(screen: Screen, folder: pathlib.Path) -> Screen:
"""screen with the loops as they wait now, unless the human is typing a number; a question that no longer waits leaves the answer screen."""
"""screen with the loops as they wait and run now, unless the human is typing a number; a question that no longer waits leaves the answer screen."""
match screen:
case Listing(_, "", note):
return Listing(tuple(waiting(folder)), "", note)
return Listing(tuple(waiting(folder)), "", note, tuple(running_loops(folder)))
case Answering(ask) if not still_waits(folder, ask):
return Listing(note=no_longer_waits(ask))
return screen
+99 -10
View File
@@ -18,9 +18,9 @@ from loop_claude.hand_over import ClaudeCommand
from failure import Failure
from loop_inbox import inbox, main
from loop_claude.paths import paths_from
from loop_claude import session_lock
from loop_claude import running_loops, session_lock, waiting
from loop_claude.running_loops import RunningLoop, Taken
from loop_claude.effects import system_effects
from loop_claude import waiting
ASKING = Asking(ClaudeCommand(["--resume", "s"], "/c", {}))
# The pid of this loop-inbox.
@@ -33,9 +33,9 @@ def asked(session, root, question="Which one?", at=100.0, state=ASKING):
def loops_hold(test, folder, *sessions):
"""Holds each session's lock until the test ends, as the loop that lists its ask does."""
"""Holds each session's lock until the test ends, as a running loop does."""
for session in sessions:
test.enterContext(session_lock.locked(folder, session))
test.enterContext(session_lock.held(folder, session))
def asks_and_answers(folder):
@@ -122,6 +122,10 @@ class Answers(unittest.TestCase):
waiting.publish(self.folder, ask)
self.assertEqual(main.refreshed(Listing(note="Sent to /a."), self.folder), Listing((log,), "", "Sent to /a."))
def test_the_list_shows_the_loops_running_now(self):
self.enterContext(running_loops.shown_running(self.folder, "s9", "/code/web", system_effects()))
self.assertEqual(main.refreshed(Listing(), self.folder), Listing(running=(RunningLoop("s9", "/code/web", ()),)))
def test_a_number_picks_the_loop_it_had_when_the_human_began_typing_it(self):
log, bender = asked("s1", "/code/log", at=100), asked("s2", "/code/bender", at=200)
typing = keyed(Listing((log, bender)), "2")
@@ -288,6 +292,11 @@ class Keys(unittest.TestCase):
with self.subTest(keys=keys):
self.assertEqual(keyed(Listing((ask,)), *keys), after)
def test_a_number_typed_keeps_the_running_loops_shown_and_clears_the_note(self):
running = (RunningLoop("s1", "/code/log", ()),)
self.assertEqual(keyed(Listing(note="No loop has the number 7.", running=running), "1", "2", BACKSPACE), Listing((), "1", "", running))
self.assertEqual(keyed(Listing(typed="1", note="No loop has the number 7.", running=running), BACKSPACE), Listing((), "", "", running))
def test_an_answer_is_sent_stripped_talk_opens_claude_and_enter_alone_or_esc_goes_back(self):
ask = asked("s1", "/code/log")
for keys, after in (
@@ -322,7 +331,7 @@ class Waiting(unittest.TestCase):
def test_drops_and_removes_the_ask_a_killed_loop_left_behind(self):
with tempfile.TemporaryDirectory() as temp:
folder = pathlib.Path(temp)
lists_and_waits = "import pathlib, sys, time\nfrom test_loop_inbox import asked, system_effects, waiting\nwith waiting.listed(pathlib.Path(sys.argv[1]), asked('s1', '/a'), system_effects()):\n\tprint(flush=True); time.sleep(60)"
lists_and_waits = "import pathlib, sys, time\nfrom test_loop_inbox import asked, session_lock, system_effects, waiting\nwith session_lock.held(pathlib.Path(sys.argv[1]), 's1'), waiting.listed(pathlib.Path(sys.argv[1]), asked('s1', '/a'), system_effects()):\n\tprint(flush=True); time.sleep(60)"
loop = subprocess.Popen([sys.executable, "-c", lists_and_waits, temp], cwd=pathlib.Path(__file__).parent, stdout=subprocess.PIPE)
self.addCleanup(loop.wait)
self.addCleanup(loop.kill)
@@ -336,24 +345,29 @@ class Waiting(unittest.TestCase):
waiting.drop_ended(folder)
self.assertEqual(asks_and_answers(folder), [])
def test_loop_inbox_removes_a_killed_loops_ask_and_answer_as_it_looks(self):
def test_loop_inbox_removes_a_killed_loops_ask_answer_and_running_file_as_it_looks(self):
with tempfile.TemporaryDirectory() as home:
paths = paths_from(pathlib.Path(home))
ask = asked("s1", "/a")
waiting.publish(paths.waiting, ask)
waiting.send(paths.waiting, ask, Typed("Use A."))
running_loops.running_file(paths.waiting, "s1").write_text(json.dumps({"root": "/a", "items": []}))
main.run(Window("q"), contextlib.nullcontext, paths, system_effects())
self.assertEqual(asks_and_answers(paths.waiting), [])
def test_removes_only_the_asks_and_answers_whose_loop_has_ended(self):
def test_removes_only_the_asks_answers_and_running_files_whose_loop_has_ended_each_by_its_own_module(self):
with tempfile.TemporaryDirectory() as temp:
folder = pathlib.Path(temp)
loops_hold(self, folder, "s1")
for ask in (asked("s1", "/a"), asked("s2", "/b")):
waiting.publish(folder, ask)
waiting.send(folder, ask, Typed("Use A."))
for session in ("s1", "s2", "s3"):
running_loops.running_file(folder, session).write_text(json.dumps({"root": "/a", "items": []}))
waiting.drop_ended(folder)
self.assertEqual(asks_and_answers(folder), ["s1.answer", "s1.json"])
self.assertEqual(asks_and_answers(folder), ["s1.answer", "s1.json", "s1.running", "s2.running", "s3.running"])
running_loops.drop_ended_loops(folder)
self.assertEqual(asks_and_answers(folder), ["s1.answer", "s1.json", "s1.running"])
def test_a_talk_claim_from_pid_0_or_below_is_no_answer_since_it_would_name_a_process_group(self):
with tempfile.TemporaryDirectory() as temp:
@@ -399,6 +413,52 @@ class Waiting(unittest.TestCase):
self.assertEqual((waiting.answered(folder, another), waiting.claude_ended(folder, another)), (None, False))
class RunningLoops(unittest.TestCase):
def setUp(self):
self.folder = pathlib.Path(tempfile.mkdtemp())
self.addCleanup(shutil.rmtree, self.folder)
self.effects = dataclasses.replace(system_effects(), sleep=lambda seconds: None)
def test_lists_a_loop_with_the_items_it_shows_until_it_ends(self):
with running_loops.shown_running(self.folder, "s1", "/code/log", self.effects) as listed:
self.assertEqual(running_loops.running_loops(self.folder), [RunningLoop("s1", "/code/log", ())])
listed.show((Taken(255, "Have loop-inbox list every running loop."),))
self.assertEqual(running_loops.running_loops(self.folder), [RunningLoop("s1", "/code/log", (Taken(255, "Have loop-inbox list every running loop."),))])
self.assertEqual(running_loops.running_loops(self.folder), [])
def test_lists_the_loops_by_checkout_and_leaves_out_one_that_was_killed_or_whose_file_cannot_be_read(self):
# Five, so the order the files are found in is unlikely to be the order by checkout.
for session, root in (("s1", "/code/web"), ("s2", "/code/c"), ("s7", "/code/a"), ("s8", "/code/z"), ("s9", "/code/m")):
self.enterContext(running_loops.shown_running(self.folder, session, root, self.effects))
# A killed loop leaves its file behind, and its lock free.
(self.folder / "s3.running").write_text(json.dumps({"root": "/code/old", "items": []}))
for session, content in (("s4", "{"), ("s5", json.dumps({"root": "/code/x", "items": [{"id": "1", "tagline": ""}]})), ("s6", json.dumps({"root": "/code/x"})), ("s10", json.dumps({"root": "/code/x", "items": [{"id": True, "tagline": ""}]}))):
self.enterContext(session_lock.held(self.folder, session))
(self.folder / f"{session}.running").write_text(content)
self.assertEqual(running_loops.running_loops(self.folder), [RunningLoop("s7", "/code/a", ()), RunningLoop("s2", "/code/c", ()), RunningLoop("s9", "/code/m", ()), RunningLoop("s1", "/code/web", ()), RunningLoop("s8", "/code/z", ())])
def test_a_second_loop_on_the_session_warns_and_leaves_the_first_listed_with_its_question(self):
ask = asked("s1", "/code/log")
with running_loops.shown_running(self.folder, "s1", "/code/log", self.effects) as first:
waiting.publish(first.folder, ask)
with contextlib.redirect_stderr(io.StringIO()) as said:
with running_loops.shown_running(self.folder, "s1", "/code/log", self.effects) as second:
second.show((Taken(1, "Do it."),))
with waiting.listed(second.folder, asked("s1", "/code/log", question="Mine?"), self.effects):
self.assertEqual(waiting.waiting(self.folder), [ask])
self.assertIn(f"loop-inbox cannot list this loop or its questions: another process holds {session_lock.lock_file(self.folder, 's1')}", said.getvalue())
self.assertEqual(running_loops.running_loops(self.folder), [RunningLoop("s1", "/code/log", ())])
self.assertEqual(waiting.waiting(self.folder), [ask])
self.assertEqual(list((self.folder / "unlisted").iterdir()), [])
def test_takes_the_lock_once_loop_inbox_lets_go_of_it(self):
# loop-inbox holds the lock for a moment as it checks whether the loop runs.
looking = contextlib.ExitStack()
looking.enter_context(session_lock.held(self.folder, "s1"))
with running_loops.shown_running(self.folder, "s1", "/code/log", dataclasses.replace(self.effects, sleep=lambda seconds: looking.close())):
self.assertEqual(running_loops.running_loops(self.folder), [RunningLoop("s1", "/code/log", ())])
class Shown(unittest.TestCase):
def drawn(self, screen, window):
"""The lines draw puts on window for screen, 3700 s after the epoch."""
@@ -421,14 +481,43 @@ class Shown(unittest.TestCase):
" Cut 0.4.0?",
" Its changelog is ready.",
"",
"No loop runs.",
], [
"Type a number and Enter to answer that loop; q",
"quits loop-inbox, and the loops keep waiting.",
"> 1",
]))
def test_an_empty_list_says_no_loop_waits(self):
self.assertEqual(inbox.listing_lines(Listing(note="Sent to /a."), 0, str, 79), (["No loop waits for you.", ""], ["Sent to /a.", "q quits loop-inbox, and the loops keep waiting.", "> "]))
def test_the_running_loops_follow_the_waiting_ones_each_with_the_items_its_chunk_takes(self):
log = asked("s1", "/code/log", "Which one?", at=0)
running = (
RunningLoop("s2", "/code/c", (Taken(12, "Accept undefined in MetadataValue and drop such keys on output."), Taken(14, ""))),
RunningLoop("s1", "/code/log", (Taken(255, "Have loop-inbox list every running loop-claude on the machine."),)),
RunningLoop("s3", "/code/web", ()),
)
lines, _ = inbox.listing_lines(Listing((log,), running=running), 120, lambda seconds: f"<{seconds}>", 50)
self.assertEqual(lines, [
"1 loop waits for you.",
"",
"[1] /code/log, waiting since <0> (2 min)",
" Which one?",
"",
"Running: 3 loops",
"- /code/c",
" item 12: Accept undefined in MetadataValue…",
" item 14",
"- /code/log, waiting as [1]",
" item 255: Have loop-inbox list every running…",
"- /code/web",
" no todo.md item yet",
])
def test_the_running_section_counts_one_loop(self):
lines, _ = inbox.listing_lines(Listing(running=(RunningLoop("s1", "/code/log", ()),)), 0, str, 79)
self.assertEqual(lines, ["No loop waits for you.", "", "Running: 1 loop", "- /code/log", " no todo.md item yet"])
def test_an_empty_list_says_no_loop_waits_or_runs(self):
self.assertEqual(inbox.listing_lines(Listing(note="Sent to /a."), 0, str, 79), (["No loop waits for you.", "", "No loop runs."], ["Sent to /a.", "q quits loop-inbox, and the loops keep waiting.", "> "]))
def test_the_answer_screen_at_80_columns_shows_every_character_of_each_line_and_says_what_enter_alone_does(self):
# The question's first line has 80 characters, one more than a line drawn at 80 columns holds.
+135
View File
@@ -3194,3 +3194,138 @@ Inherited architect, would restructure first:
- `bin/rule_hook/reviewer_report.py:10` `REVIEWERS`: a second source of truth for who is a reviewer, beside review_passes.py's table of the same name
- `bin/loop_claude/routing.py:76` `after_unfinished`: "routing" spans loop_claude/routing.py, model_routing, routing_check, routing_figures and rung_replay
- `bin/loop_claude/loop/main.py:169` `run_loop`: a fan-in of about 25 modules
## 2026-10-29T19:59:03Z, PR #397 at 1723469, against 77ab11e
Ruling: same
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|---|---|---|---|---|---|
| Mid A | same | worse | better | same | same |
| Inherited architect | same | worse | better | same | same |
Mid A, decided by:
- Locality: `bin/loop_claude/loop/main.py:182` `run_loop`: the line after `shown_running` rebinds `paths.waiting` to `listed.folder`, a private unlisted folder when the lock can't be taken; `interrupt` and `routing_check` read `paths.waiting` with no way to see the swap
- Locality: `bin/loop_claude/waiting.py:123` `listed`: works only when the caller passes the folder `running_loops.shown_running` yields; in the base the ask carried its own liveness check
- Locality: `bin/loop_claude/cycle/prompts.py:72` `review_launches`: types out the "Markdown no agent follows" list by hand instead of deriving it from `INSTRUCTION_FILES` and `INSTRUCTION_FOLDERS` in `bin/rule_hook/reviewer_rung.py:22`
- Shape: `bin/loop_claude/verdicts.py:6` `TakenIn`: three loose fields on each verdict become one named value, and `taken_in_from` in `bin/loop_claude/cycle/judge.py:139` takes the clamping out of `verdict_from`
- Navigation, Self-sufficiency: `bin/loop_claude/running_loops.py:1` module docstring: leads from "loop-inbox doesn't show my loop" to the mechanism as directly as the base's pointer to `waiting.py`; `session_lock.py` still sends the reader to `docs/decisions.md` for why lock files stay
Inherited architect, decided by:
- Locality: `bin/loop_claude/loop/main.py:182` `run_loop`: rebinds `paths.waiting` to `listed.folder`, a throwaway `unlisted/<id>` folder where another loop holds the lock; `cycle/interrupt.py` and `loop/routing_check.py` write questions to a folder they can't see was swapped, explained only at `Listed.folder`
- Locality: `bin/loop_claude/running_loops.py:3` module docstring: liveness moved from one `Ask.pid` field to a flock shared by `session_lock.py`, `running_loops.py` and `waiting.py`, and `listed` has a precondition stated only in its docstring
- Locality: `bin/loop_claude/cycle/prompts.py:72` `review_launches`: its "Markdown only" list repeats `INSTRUCTION_FILES` and `INSTRUCTION_FOLDERS` in `bin/rule_hook/reviewer_rung.py:22` and the skill's "Markdown only" section, with nothing tying them together
- Locality: `bin/loop_claude/running_loops.py:83` `locked_soon`: the flock lapses for a moment when the reload execs into the edited script inside the `with` at `bin/loop_claude/loop/main.py:185`, and no comment says so; the nested `ExitStack` takes more than one read
- Shape: `bin/loop_claude/verdicts.py:6` `TakenIn`: one value replaces the `highest_*_taken_in` pair repeated across three verdicts, and `taken_in_from` checks the ranges in one place
- Shape: `bin/rule_hook/reviewer_rung.py:22` `prose`: the name hides "Markdown no agent follows", and `markdown_only` runs git inside a hook module that was pure
- Navigation: `bin/loop_claude/session_lock.py:1` module docstring: small, well-named modules lead to the protocol quickly, against liveness now spread over three files
- Self-sufficiency: `bin/loop_claude/session_lock.py:1` module docstring: a new pointer to `docs/decisions.md`, offset by the in-place explanations at `Listed.folder` and `fetched_todo`
## 2026-10-29T20:01:40Z, PR #397 at 1723469
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|---|---|---|---|---|---|
| Junior A | 7 | 5.5 | 6 | 6 | 6 |
| Mid A | 7 | 6 | 6 | 6 | 6 |
| Maintainability senior | 7 | 6 | 6 | 6 | 6 |
| Inherited architect | 6.5 | 6 | 5.5 | 7 | 6 |
| Mean | 6.88 | 5.88 | 5.88 | 6.25 | 6.00 |
Junior A, hardest first:
- `bin/loop_claude/routing.py:76` `after_unfinished`: eight names held at once to follow one call; the docstring resolves it only after `escalation_mark.py` and `rules/todo-items.md`
- `bin/rank_todo.py:568` `score`: every scoring step branches on SHAPE against OLD_SHAPE, so each function reads twice; nothing says when OLD_SHAPE can go
- `bin/loop_claude/cycle/run.py:56` `run_cycle`: the route swaps on a step-up outside `transition`, and `archive_stepped` and `ask` touch it too, so where the rung changes has three answers
- `bin/loop_claude/loop/reload.py:47` `decoded_as`: a recursive reflection-based decoder with two sentinels and a duck-typed `fits`; the comments give the reason
- `bin/loop_claude/cycle/prompts.py:55` `review_launches`: six conditional sentences; checking one branch needs `ladder.py`'s `review_rungs` and `replay_applies`
- `bin/loop_claude/cycle/judge.py:185` `quotes_checked`: the misquote rule splits across `judge.py` and `escalation_mark.py`, and `grounded`'s fragment matching is subtle
- `bin/comprehension_history.py:164` `worse_places`: one nested comprehension to unroll by hand
- `skills/larv-review/SKILL.md:84` "Re-entry": a table plus exceptions across 🔴, 🟡, the cap and round 2
Mid A, hardest first:
- `bin/loop_claude/routing.py:76` `after_unfinished`: five near-synonymous rung helpers held at once, and one docstring sentence packs five rules; resolved only across `escalation_mark.py`, `ladder.py` and `route.py`
- `bin/loop_claude/cycle/run.py:169` `ask`: `step_up` threads through three states, and which route each archived line names matters only for `routing_figures/measure.py`'s `rung_at`
- `bin/loop_claude/loop/reload.py:47` `decoded_as`: a recursive decoder with two sentinels and duck-typed hooks that `Route` defines far away
- `bin/rank_todo.py:428` `place`: recursive with loop detection, in the largest module, which keeps two table shapes side by side
- `bin/chunk_pick.py:109` `next_release`: `Upcoming.landed` is `bool | Failure`, and "landed" has four meanings across modules
- `bin/loop_claude/cycle/prompts.py:55` `review_launches`: six conditional sentence kinds coupled to the routing rules
- `bin/comprehension_history.py:159` `scored`: two look-alike predicates that differ on history formats named only by PR numbers
- `bin/loop_claude/loop/main.py:1` module docstring: about 120 lines, every sentence a rule, restated again by the units
Maintainability senior, hardest first:
- `bin/loop_claude/routing.py:76` `after_unfinished`: four rules in one pass over four near-synonym callees; the docstring lists them, but they still had to be simulated by hand
- `bin/loop_claude/cycle/run.py:56` `run_cycle`: `cycle.route` is replaced inside the loop on a step-up, and a StepUp pair rides through the states so each archive line names the right rung
- `bin/loop_claude/loop/reload.py:47` `decoded_as`: a recursive decoder with sentinels and a duck-typed `fits`; nothing at the call site says which LoopRun fields survive a reload
- `bin/loop_claude/cycle/prompts.py:55` `review_launches`: sentences branch on ladder positions, so checking one means computing rungs by hand
- `bin/routing_figures/measure.py:104` `measured`: nine locals, timestamps matched as strings cut to the second, and price rescaling on one screen
- `bin/rank_todo.py:332` `weigh`: the OLD_SHAPE compatibility is spread across many functions rather than cut at the boundary
- `bin/comprehension_history.py:159` `scored`: differs from `newest_scored` only by a carve-out dated by a PR number
- `bin/loop_claude/cycle/judge.py:185` `quotes_checked`: three quotes checked against three texts, each misquote with its own outcome; the exit-1 path takes four files
Inherited architect, would restructure first:
- `README.md:129` module map: names bin/'s 18 root modules only as a group, at a level of about 50 entries
- `bin/round_titles.py:8` `CAP`: the round cap lives here and in `bin/rule_hook/round_cap.py:8`, not in larv_review/, and nothing says it counts commit titles rather than launches
- `bin/loop_claude/routing.py:76` `after_unfinished`: step-up and escalation logic spans about eight files, from `cycle/run.py` to `loop/main.py`'s `stepped_route`
- `bin/loop_claude/running_loops.py:1` module docstring: the inbox file protocol sits inside loop_claude though loop-inbox imports it
- `bin/rule_hook/git.py:7` `git`: shadows `bin/git_repo.py:26` `git`, and `reviewer_rung.py` imports and calls both
- `bin/rung_replay/search.py:17` `Item`: TypeVars named `Item` and `Reply` collide with `todo_table.Item` and judge.py's `Reply`
- `bin/branch_chunks/cut.py:22` `Commit`: a second `Commit` dataclass with other fields than `bin/git_command.py:10`'s
## 2026-10-29T20:02:43Z, PR #397 rerun at 1723469
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|---|---|---|---|---|---|
| Junior A | 7 | 5.5 | 6 | 5.5 | 6 |
| Mid A | 7 | 6 | 6.5 | 6.5 | 6.5 |
| Maintainability senior | 6.5 | 5 | 6 | 5 | 5.5 |
| Inherited architect | 6.5 | 6 | 5.5 | 7 | 6 |
| Mean | 6.75 | 5.63 | 6.00 | 6.00 | 6.00 |
Junior A, hardest first:
- `bin/loop_claude/routing.py:76` `after_unfinished`: several conditions combine and hand off to six near-synonym rung helpers; the why sits behind `docs/decisions.md`
- `bin/loop_claude/loop/reload.py:47` `decoded_as`: a recursive decoder with sentinels and an unwritten `fits` convention, followed only by tracing one call by hand
- `bin/routing_figures/measure.py:104` `measured`: many jobs in one function, coupled to `costed` and a long comprehension in `render`
- `bin/comprehension_history.py:130` `newest_scored`: a Markdown file parsed as a database, with back-compat notes dated by PR numbers
- `bin/chunk_pick.py:166` `named_releases`: "release" is split across `chunk_pick`, `todo_table` and `larv_review/plan.py`
- `bin/rank_todo.py:428` `place`: recursive, with OLD_SHAPE threaded through a 658-line file whose help text is the format spec
- `bin/loop_claude/cycle/judge.py:185` `quotes_checked`: quote checks layered across three functions and `escalation_mark.py`
- `bin/rule_hook/repeat_read.py:72` `shown_lines`: timestamps compared as text, and Read and Bash reads treated differently
Mid A, hardest first:
- `bin/loop_claude/routing.py:76` `after_unfinished`: folds five rules into one function, and the cap it enforces is spread across five files
- `bin/loop_claude/loop/reload.py:47` `decoded_as`: a hand-written decoder with two sentinels, a union rule for RETIRED and a `fits` hook found by `getattr`; three passes to follow
- `bin/rank_todo.py:568` `score`: two table shapes run through scoring, weighing and validation, and nothing says which is leaving
- `bin/loop_claude/cycle/prompts.py:55` `review_launches`: six sentence groups from one `ReviewChoice`, with a replay branch that `ladder.py`'s empty `REPLAYED` leaves without data
- `bin/loop_claude/waiting.py:212` `claim_talk`: the `/talk` handshake runs between two programs through files and a flock, with deadlines and a compensating `ClaudeEnded`
- `bin/rule_hook/repeat_read.py:72` `shown_lines`: pairs transcript tool calls with results by id and handles truncation markers of a transcript format written down nowhere
- `bin/chunk_pick.py:109` `next_release`: renamed releases, the history since the last tag and landed work; the rename handling stayed unresolved
- `bin/shell_command.py:44` `segments`: a heuristic token loop with a redirect-target flag; its docstring lists what it doesn't parse
Maintainability senior, hardest first:
- `bin/loop_claude/routing.py:76` `after_unfinished`: combines the unfinished count, the escalation cap and whether a step already happened, with inputs built in `cycle/run.py`; three files open at once
- `bin/loop_claude/cycle/prompts.py:55` `review_launches`: about six conditional sentence kinds, with no example output beside the function
- `bin/loop_claude/loop/main.py:173` `run_loop`: the line rebinding `paths.waiting` to `listed.folder` quietly points every later question at another folder, explained only at `Listed.folder`
- `bin/model_routing/ladder.py:97` `review_rungs`: the Markdown-only exception that lowers a reviewer lives only in `bin/rule_hook/reviewer_rung.py:34`, and `REPLAYED` is empty
- `bin/loop_claude/loop/reload.py:47` `decoded_as`: sentinels, a duck-typed `fits` and recursion over type hints; which archived shapes decode needs `route.py` too
- `bin/rank_todo.py:558` `goal_term`: OLD_SHAPE and SHAPE run through nearly every function, selected by the string "W" or "V"
- `bin/loop_claude/waiting.py:212` `claim_talk`: a three-step handshake over three files, resolved only by holding the whole protocol
- `bin/loop_claude/cycle/judge.py:207` `grounded`: a misquote is handled three ways by what was quoted, with no single table of the outcomes
Inherited architect, would restructure first:
- `README.md:129` module map: bin/'s root holds about 64 ungrouped entries, mixing review, plan and infrastructure modules
- `bin/rule_hook/round_cap.py:8` `round_cap_breaches`: the cap counts round commit titles, while a third reviewer launch is governed only by `skills/larv-review/SKILL.md:76` "Round cap"
- `bin/round_titles.py:22` `round_counts`: any unknown pass name gets its own counter, so a misspelled pass never reaches the cap
- `bin/loop_claude/routing.py:76` `after_unfinished`: routing has four homes, from `model_routing/` to `loop/routing_check.py`
- `bin/loop_claude/loop/main.py:256` `after_verdict`: the hub of about 25 imports that every routing or judge feature edits, with `stepped_route` on the same path
- `bin/loop_claude/stop.py:1` `Stop`: documented as loop-claude's exit, but rung_replay exits through it and imports `cycle.retry` too
- `bin/rank_todo.py:71` `GOAL_STEP`: a separable formula evaluator inside a 658-line, 39-function module
- `bin/chunk_pick.py:1` module docstring: beside `bin/chunk_preflight/`, the names don't say which does what
+3 -2
View File
@@ -101,7 +101,7 @@ Hours. A chunk ran a median 0.7 hours from its first message to its last, one in
Valid while cache reads cost a twentieth of input and Claude Code's compaction keeps the worker's task.
## loop-inbox: a waiting loop-claude lists its question as one file per session under `~/.local/state/loop-claude/`, and takes the first answer, from its terminal or from loop-inbox, that names that question
## loop-inbox: a loop-claude lists itself while it runs, and its waiting question, as files per session under `~/.local/state/loop-claude/`, and takes the first answer, from its terminal or from loop-inbox, that names that question
2026-10-28, lilleman, todo item 243. Serves goal 1. With several loops running, each asked on its own terminal, and the human searched the terminals for the ones that waited. loop-inbox lists every loop's interrupts, the routing calls included, oldest first, and the human answers each one there. A loop asking for its project's model, as on a project's first run, asks on its terminal only: the human has just started it there, and no worker session exists yet. `bin/loop_claude/waiting.py` holds the protocol:
- An answer reaching the wrong loop is the worst failure. Each answer names the question it answers by a fresh id, so an answer meant for an earlier question, or sent as the terminal answered, never answers a later one.
@@ -109,7 +109,8 @@ Valid while cache reads cost a twentieth of input and Claude Code's compaction k
- While claude is open for a question, as for a release ready to cut, the routing calls or a `/talk`, loop-inbox lists the loop and where claude is open, but takes no answer for it.
- loop-inbox runs the claude command the loop wrote, `bypassPermissions` included, so that claude runs in the same sandbox as the loop. Since loop-inbox runs a command read from a file, the folder is private to the user.
- Files, read by polling, need no daemon and only the standard library, and a loop with no loop-inbox running is answered on its terminal as before.
- loop-inbox lists a question only while its loop holds the session's lock file with flock, and removes a question whose lock is free. The kernel frees the lock however the loop ends, killed included. A process id could not tell a running loop from a killed one: on 2026-10-29 this machine's kernel handed out its 32,768 ids again every 30 to 75 minutes, so a killed loop's question came back whenever another process got its id. The lock file stays once the loop ends, one per project: removing it while another process has it open could let loop-inbox lock a file no loop holds. Todo item 252.
- loop-inbox lists a question only while its loop holds the session's lock file with flock, and removes a question whose lock is free. The loop holds the lock for its whole run. The kernel frees the lock however the loop ends, killed included. A process id could not tell a running loop from a killed one: on 2026-10-29 this machine's kernel handed out its 32,768 ids again every 30 to 75 minutes, so a killed loop's question came back whenever another process got its id. The lock file stays once the loop ends, one per project: removing it while another process has it open could let loop-inbox lock a file no loop holds. PR #396.
- A loop also lists itself as running, with the items its chunk takes, in `<session>.running`, under the same lock: one lock tells loop-inbox both that the loop runs and that its question stands. The judge names the items the worker took in, as an array of IDs in its reply's `items_taken_in`. PR #397.
A bench of three readers seated as the README's audience picked the name `loop-inbox`, 3–0.
+2 -2
View File
@@ -6,7 +6,7 @@
`Bar = 0.1`
`Next ID = 255`
`Next ID = 256`
## Items
@@ -152,7 +152,7 @@ F is 8 until then, about one S 3 change, lilleman's call in PR #283. A chunk cos
### 215. Decode a reload's handed JSON with a decoder for `LoopRun` and its `Route`, in place of `decoded_as`'s generic one with its two sentinels and `Route.fits` hook.
Release 0.3.0's Mid A (PR #324 at c713910) named `bin/loop_claude/loop/reload.py:43` `decoded_as`: "a generic decoder with two sentinels and a duck-typed fits hook defined on Route". This lowers Shape: `decoded_as` is generic over any type, yet `decode_handed` calls it with one dataclass, `LoopRun`. Keep what it does today: a field added since the running script started may be missing, and a handed dataclass holding a field its `RETIRED` names decodes as None where its type allows None, and is rejected otherwise. Make `decoded_as` easier to read.
Release 0.3.0's Mid A (PR #324 at c713910) named `bin/loop_claude/loop/reload.py:43` `decoded_as`: "a generic decoder with two sentinels and a duck-typed fits hook defined on Route". This lowers Shape: `decoded_as` is generic over any type, yet `decode_handed` calls it with one dataclass, `LoopRun`. Keep what it does today: a field added since the running script started may be missing, and a handed dataclass holding a field its `RETIRED` names decodes as None where its type allows None, and is rejected otherwise. `LoopRun.items_taken_in`, a tuple of item IDs, decodes only from a JSON array of integers. Make `decoded_as` easier to read.
### 237. Give `judge` and `judge_once` in `bin/loop_claude/cycle/judge.py` a record of the inputs they share, in place of nine and eight parameters, or record why they stay.