Move loop-claude's cycle, judge, interrupt, tmux and routing into agent_cycle
CI / tests (pull_request) Failing after 3m50s

This commit is contained in:
2026-11-18 16:21:35 +01:00
parent 2c5406ab38
commit 54fc339fb0
45 changed files with 348 additions and 237 deletions
+2
View File
@@ -31,6 +31,8 @@
!bin/adf_codec/node_shim/package-lock.json
!bin/adf_codec/node_shim/package.json
!bin/adf_codec/node_shim/shim.mjs
!bin/agent_cycle/
!bin/agent_cycle/*.py
!bin/atlassian/
!bin/atlassian/*.py
!bin/branch_chunks/
+3 -2
View File
@@ -209,6 +209,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. Beside the packages, `bin/`'s root holds only the launchers, the tools of one file with their tests, `test_env.py`, `failure.py` and `setup.cfg`. `failure.py`'s `Failure`, which modules across `bin/` return for a failed step, belongs to no single package. `atlassian/`, `branch_chunks/`, `claude_code/`, `command_lines/`, `forge/`, `git_cli/`, `loop_effects/`, `loop_state/`, `machine_load/`, `model_routing/`, `notifier/`, `plan/`, `plan_store/`, `record_store/`, `release_plan/`, `review_rules/`, `rung_replay/`, `text_files/` and `transcript_archive/` serve more than one tool. No package imports one that imports it back, which `repo_checks/test_package_cycles.py` checks.
- `adf_codec/` converts markdown to ADF, the rich text of Jira Cloud and Confluence, and back, in a throwaway container running a pinned `@larvit/adf-codec`. It builds the container's image inside a heavy slot.
- `agent_cycle/` runs one cycle of a headless claude worker and the judge of its transcript (`run.py`), with the judge, the interrupt, the tmux window and the routing of the worker's rung. An entry point hands it its own prompts and file names (`worker_prompts.py`) and its reading of the items a worker took in. `loop_claude` drives it, and `do_epic` will; it doesn't import either.
- `atlassian/` holds what the Jira and Confluence backends share (`client.py`): one Atlassian account's credentials, the request both backends send, and each service's error messages.
- `branch_chunks/` cuts a default branch into chunks and finds, for each, the items it shipped and the later chunks that fixed its code, for `score_outcomes` and `routing_figures`. It imports `reading_cost`'s record path.
- `command_lines/` reads a shell command: its simple commands, and a docker call's subcommand and memory limits, for `command_patterns`, `reading_cost`, `routing_figures`, `rule_hook` and `run_heavy`.
@@ -216,7 +217,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `do_epic/` will hold the tool that drives one Jira epic. So far `config.py` reads its machine-wide settings, importing `project_config`'s settings and `model_routing`'s ladder file, and `epic_record.py` reads and writes an epic's description by section and language line, through `record_store`'s `EpicDescription`. `repos.py` finds a repo's checkout and project config by its name, and clones a missing checkout from the host and owner of the epic's other repos, through `forge`'s `url_beside`. `repo_pick.py` asks claude, by `repo-rule.md`, where an epic item is worked, and records the answer as a label on the issue. `backend/` reads and files the epic's issues and adds those labels.
- `forge/` tells a GitHub origin from a Gitea one, names a repo beside an origin's and runs that forge's CLI (`commands.py`), and finds a pull request and waits for its checks (`pulls.py`), for `chunk_preflight`, `chunk_pr`, `deploy_release`, `do_epic` and `larv_review`.
- `git_cli/` runs git for every tool (`git_repo.py`), and reads the git calls in a shell command (`git_command.py`).
- `judge_replay` imports `loop_claude`'s judge, verdicts, premises and records.
- `judge_replay` imports `agent_cycle`'s judge and verdicts, and `loop_claude`'s premises, records and prompt names.
- `loop_claude` runs `chunk-preflight` as a process of its own.
- `loop_effects/` holds `Effects`: the processes, terminal, clock and git a tool reaches, injected so its tests can script them. loop-claude, both replay tools and `reviewer-merge-trials`' driver use it.
- `loop_state/` holds where loop-claude keeps its files (`paths.py`), which `rung_replay` reads too.
@@ -232,7 +233,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `rest_client/` sends a JSON request to a REST API and reads its credentials from an env file, for `notifier`, `atlassian` and `record_store`.
- `review_rules/` holds the larv-review rules that several tools apply: its passes, its review folder, its round commit titles and the comprehension history's format.
- `routing_figures/` measures loop-claude's archive, and each of its projects' default branches, for loop-claude's routing calls.
- `rung_replay/` holds what `judge_replay` and `review_replay` share: the parallel replay runner, the argument reader, the candidate rungs and the exits, and `judge_replay`'s rung search. It reads `loop_claude`'s retry count and models file, and finds that file through `loop_state`'s paths. Its `archive.py` keeps each replay's runs and its report in a `replays/` folder of loop-claude's archive.
- `rung_replay/` holds what `judge_replay` and `review_replay` share: the parallel replay runner, the argument reader, the candidate rungs and the exits, and `judge_replay`'s rung search. It reads `agent_cycle`'s retry count and `loop_claude`'s models file, and finds that file through `loop_state`'s paths. Its `archive.py` keeps each replay's runs and its report in a `replays/` folder of loop-claude's archive.
- `test_env.py` serves the tests.
- `text_files/` reads a Markdown file's `##` sections, quotes a passage and joins names into a list, stamps times in UTC, replaces a file in one step, private where it is new, and gzips a file beside its plain name, by which it reads it afterwards.
- `transcript_archive/` stores loop-claude's transcripts. Its `project_key.py` names each project's archive folder, loop-claude session and models-file entry.
+4
View File
@@ -0,0 +1,4 @@
"""One cycle of a headless claude worker and the judge of its transcript, for every entry point that drives such cycles: loop-claude today, do-epic next (docs/decisions.md → `do-epic: drives one Jira epic …`).
run.py runs a cycle through the states in states.py: worker.py runs the worker, judge.py rules on its transcript, interrupt.py puts a question to the human in the tmux window tmux.py names, and routing.py picks the rung the worker runs on next. An entry point hands the cycle what is its own: its prompts and file names (worker_prompts.py) and how it reads the plan items a worker took in (run.py's Cycle.taken_in). No module here imports an entry point's package, which test_agent_cycle.py checks. A reader finds a module by its name, so the modules stay at one level. docs/decisions.md → `principles: about seven things per level, …` allows that.
"""
@@ -12,13 +12,13 @@ import typing
from claude_code.transcript import assistant_lines, render, Typed
from claude_code.entries import AssistantTurn, Entry
from loop_claude.verdicts import Escalating, Verdict
from loop_claude.quotes import verbatim
from agent_cycle.verdicts import Escalating, Verdict
from agent_cycle.quotes import verbatim
# Only the judge reads the step line, so it is not a [loop] line.
STEP_TAG = "[step]"
STEP_LINE = f"{STEP_TAG} loop-claude stepped the worker up a rung here, so the escalation triggers that fired before this line are spent."
# Reply.escalation's description in cycle/judge.py carries this sentence, so the judge reads STEP_LINE as the mark.
# Reply.escalation's description in agent_cycle/judge.py carries this sentence, so the judge reads STEP_LINE as the mark.
QUOTE_AFTER_STEP = f"Where a {STEP_TAG} line says loop-claude stepped the worker up a rung, quote only the worker's own words after it, and leave this empty where the trigger fired only before it."
@@ -3,14 +3,14 @@ import sys
import typing
import uuid
from loop_claude.hand_over import claude_args, ClaudeCommand, hand_over
from agent_cycle.hand_over import claude_args, ClaudeCommand, hand_over
from loop_effects.effects import Effects, say
from failure import Failure
from claude_code.transcript import human_turns, read_transcript
from loop_claude.stop import needs_human, needs_terminal, Stop
from agent_cycle.stop import needs_human, needs_terminal, Stop
from model_routing.ladder import Rung
from loop_claude.direct_message import tell
from loop_claude import tmux
from agent_cycle.direct_message import tell
from agent_cycle import tmux
ANSWER_QUESTION = "answer the question above"
# TALK, what the human types at loop-claude's terminal to open claude for the question, and ASK_ANSWER were picked on 2026-10-17 by a bench of three readers seated as the README's audience, as ~/.claude/CLAUDE.md → "Working loop" → "Bench a syntax with the people who write it." has it.
@@ -3,19 +3,19 @@ import json
import re
import typing
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS, ANSWERS_RECORDED, typed_answer
from agent_cycle.worker_prompts import answers_recorded, typed_answer
from claude_code.reply import claude_reply, Limited
from loop_effects.effects import Effects
from claude_code.entries import Entry, structured_output
from loop_claude import escalation_mark
from agent_cycle import escalation_mark
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, Judged, QuotedAnswer, Unfinished, Verdict
from agent_cycle.verdicts import Finished, Interrupt, Judged, QuotedAnswer, Unfinished, Verdict
from claude_code.transcript import human_answers
from transcript_archive.judge_run import JudgeRun
from loop_claude.quotes import plain, verbatim
from loop_claude.cycle.retry import retried
from agent_cycle.quotes import plain, verbatim
from agent_cycle.retry import retried
from model_routing.ladder import Rung
from loop_claude.stop import Stop
from agent_cycle.stop import Stop
from claude_code.tokens import tokens_of
# At 3 to 4 characters a token, 100,000 to 133,000 tokens, which leaves a 200,000-token context room for the reply; the largest session rendered here was 364,000 characters on 2026-10-03.
@@ -56,15 +56,21 @@ QUOTE_RULES = (
FINISHED_RULES = (
"The chunk is the piece of work the worker is on, shipped as one pull request.\n\n"
"finished=true when the chunk is complete: merged, or nothing remains that the worker could do on "
f"its own. Even then, it is finished only once {ANSWERS_RECORDED}.\n\n"
"its own. Even then, it is finished only once {answers_recorded}.\n\n"
"An answer counts as recorded where the premises or the records above already hold it, the human's rules "
"(~/.claude/CLAUDE.md, ~/.claude/rules/, the project's review standards, each headed by its path) included. "
f"It also counts where the transcript shows the worker writing it into {ANSWER_DESTINATIONS}, "
"It also counts where the transcript shows the worker writing it into {answer_destinations}, "
"but not into one of the human's rules.\n\n"
"finished=false when work remains that a further run can "
"continue: an open PR, a review not yet run, CI not yet reported, an answer not yet recorded."
)
JUDGE_RULES = "\n\n".join((INTERRUPT_RULES, QUOTE_RULES, FINISHED_RULES))
def judge_rules(answer_destinations: str) -> str:
"""The rules that end the judge's prompt. answer_destinations names where the entry point's worker may record an answer the human typed."""
return "\n\n".join((INTERRUPT_RULES, QUOTE_RULES, FINISHED_RULES.format(answers_recorded=answers_recorded(answer_destinations), answer_destinations=answer_destinations)))
# Open the task and the transcript in the prompt; the premises and the records come before the task, the rules after the transcript.
# judge_replay.archived_prompt splits each archived prompt on them, so rewording one makes every run archived before it replay as failed.
TASK_HEADING = "The task the worker was given:\n"
@@ -74,7 +80,7 @@ TRANSCRIPT_HEADING = "What the worker did and said, what the human typed on [hum
@dataclasses.dataclass(frozen=True)
class Reply:
answer: str = dataclasses.field(metadata={"description": "With interrupt false, the passage of the premises or the records that answers the worker's question, quoted verbatim, without elisions. Empty otherwise."})
# Routes the worker one rung up, as the judge interrupts or quotes an answer, or on the next cycle: loop_claude/escalation_mark.py.
# Routes the worker one rung up, as the judge interrupts or quotes an answer, or on the next cycle: agent_cycle/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."})
finished: bool = dataclasses.field(metadata={"description": "Whether the chunk is finished."})
@@ -122,10 +128,11 @@ class Grounds(typing.NamedTuple):
class Brief(typing.NamedTuple):
"""What the judge reads: the worker's task, the premises and records the worker is judged by, the transcript's entries, and escalated_at, how many of those entries the session held when an escalation last stepped the worker up a rung, 0 before any."""
"""What the judge reads: the worker's task, the premises and records the worker is judged by, answer_destinations, which names where the worker may record an answer the human typed, the transcript's entries, and escalated_at, how many of those entries the session held when an escalation last stepped the worker up a rung, 0 before any."""
task: str
premises: str
records: str
answer_destinations: str
entries: list[Entry]
escalated_at: int
@@ -274,7 +281,8 @@ def judge_prompt(brief: Brief) -> tuple[str, Grounds]:
f"{TASK_HEADING}{brief.task}\n\n"
f"{TRANSCRIPT_HEADING}"
)
room = max(0, JUDGE_PROMPT_CHARS - len(head) - len(JUDGE_RULES) - 2)
rules = judge_rules(brief.answer_destinations)
room = max(0, JUDGE_PROMPT_CHARS - len(head) - len(rules) - 2)
transcript = escalation_mark.transcript(brief.entries, brief.escalated_at, typed_answer)
# The tail, where an interrupt or a finish lands; the session's transcript grows cycle over cycle.
shown = transcript[max(0, len(transcript) - room):]
@@ -284,4 +292,4 @@ def judge_prompt(brief: Brief) -> tuple[str, Grounds]:
quotable=f"{brief.premises}\n\n{brief.records}",
typed=tuple(human_answers(brief.entries, typed_answer)),
)
return f"{head}{shown}\n\n{JUDGE_RULES}", grounds
return f"{head}{shown}\n\n{rules}", grounds
@@ -3,7 +3,7 @@ import typing
from loop_effects.effects import Effects, say
from failure import Failure
from claude_code.reply import Limited
from loop_claude.stop import Stop
from agent_cycle.stop import Stop
T = typing.TypeVar("T")
@@ -2,9 +2,9 @@
The worker, and the session /talk opens, run on a Route (model_routing/route.py). A model off the ladder gets a route without an item, and it is never stepped.
- Start. routed_item finds the plan item that routes a fresh chunk, if there is one with L, E and I scored; first_route picks the worker's rung from its L, or the project's rung without an item.
- Start. The entry point finds the plan item that routes a fresh chunk, as loop_claude/routed_item.py does; first_route picks the worker's rung from its L, or the project's rung without an item.
- Rerun. kept decides whether a rerun resumes the route its archive last names.
- Step-up. next_route raises the route after an unfinished verdict (unfinished_route), or an interrupt or a quoted answer that carries an escalation (escalated_route); escalation_cap bounds an escalation, and loop_claude/escalation_mark.py states the escalation mark's rule. step_up names the change where it changes the worker line, which the archive records.
- Step-up. next_route raises the route after an unfinished verdict (unfinished_route), or an interrupt or a quoted answer that carries an escalation (escalated_route); escalation_cap bounds an escalation, and agent_cycle/escalation_mark.py states the escalation mark's rule. step_up names the change where it changes the worker line, which the archive records.
- Judge. judge_rung picks the rung of the judge of a JUDGE_REPLAYED model.
A step-up weighs five rungs:
@@ -29,13 +29,10 @@ Each verdict then moves the rung by one rule, and the rung never falls. The rung
"""
import dataclasses
from release_plan.release_standing import chunk_item, LastCut, Next
from loop_claude import escalation_mark
from failure import Failure
from loop_claude.verdicts import Interrupt, QuotedAnswer, Unfinished
from plan.todo_table import Item, NoItemsTable
from agent_cycle import escalation_mark
from agent_cycle.verdicts import Interrupt, QuotedAnswer, Unfinished
from plan.todo_table import Item
from model_routing.ladder import Ladder, ProjectRung, Rung
from plan_store.plans import Plan
from model_routing.route import Route
UNFINISHED_PER_STEP = 2
@@ -45,20 +42,6 @@ ESCALATION_CAP = 2
JUDGE_REPLAYED = ("claude-opus-5-5",)
def routed_item(plan: Plan | Failure, cut: LastCut, item_id: int | None = None) -> Item | Failure | None:
"""The plan's item item_id, or without one the item release_standing.chunk_item picks from plan, weighed against the last cut; None when there is none, or it lacks L, E or I."""
if isinstance(plan, NoItemsTable):
return None
if isinstance(plan, Failure):
return plan
if item_id is None:
pick = chunk_item(plan.items, cut)
takes = pick.item if isinstance(pick, Next) else None
else:
takes = next((item for item in plan.items if item.id == item_id), None)
return takes if takes and takes.likelihood and takes.escape_and_impact else None
def first_route(project: ProjectRung, item: Item | None) -> Route:
"""The route a chunk starts on: the rung its item's L picks from the project's rung, or the project's rung without an item."""
if item is None:
@@ -133,7 +116,7 @@ def unfinished_route(project: ProjectRung, route: Route, verdict: Unfinished) ->
def escalated_route(project: ProjectRung, route: Route, verdict: Interrupt | QuotedAnswer) -> Route:
"""The route after an interrupt or a quoted answer. Without an escalation it holds, since neither is an unfinished verdict.
With one, the rung rises to floor_rung, which the verdict's highest L taken in may raise. Where floor_rung lies below escalation_cap, the rung steps one up from it and the mark moves, as loop_claude/escalation_mark.py says; at the cap the rung stays on floor_rung and the mark holds.
With one, the rung rises to floor_rung, which the verdict's highest L taken in may raise. Where floor_rung lies below escalation_cap, the rung steps one up from it and the mark moves, as agent_cycle/escalation_mark.py says; at the cap the rung stays on floor_rung and the mark holds.
"""
mark = escalation_mark.moved_to(verdict)
if mark is None:
@@ -2,31 +2,29 @@ import dataclasses
import pathlib
import typing
from loop_claude.cycle.states import Active, Archived, Closing, Ended, Event, HumanTalked, HumanTyped, Interrupting, Judging, QUOTED_ANSWERS_PER_CYCLE, Ruled, State, to_the_human, transition, TypedAnswer, WorkerRan, Working
from agent_cycle.states import Active, Archived, Closing, Ended, Event, HumanTalked, HumanTyped, Interrupting, Judging, QUOTED_ANSWERS_PER_CYCLE, Ruled, State, to_the_human, transition, TypedAnswer, WorkerRan, Working
from transcript_archive.write import archive
from loop_claude.cycle.worker import AUTO_COMPACT_WINDOW, COMPACT_WINDOW, run_worker, worker_args
from agent_cycle.worker import AUTO_COMPACT_WINDOW, COMPACT_WINDOW, run_worker, worker_args
from claude_code.output_limits import BASH_CEILING, BASH_CEILING_CHARACTERS
from loop_claude.cycle.judge import Brief, judge, Rejected
from loop_claude.cycle import chunk_items
from agent_cycle.judge import Brief, judge, Rejected
from claude_code.session import delete_session, Session, session_open, transcript_file
from loop_effects.effects import Effects, say
from claude_code.entries import Entry
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, Judged, QuotedAnswer, Unfinished, Verdict
from loop_claude.cycle.interrupt import interrupt, Talked, WorkerSession
from agent_cycle.verdicts import Finished, Interrupt, Judged, QuotedAnswer, TakenIn, Unfinished, Verdict
from agent_cycle.interrupt import interrupt, Talked, WorkerSession
from transcript_archive.judge_run import JudgeRun
from transcript_archive.read import last_spent
from loop_claude.routing import next_route, step_up, StepUp
from agent_cycle.routing import next_route, step_up, StepUp
from transcript_archive import outcomes
from plan_store.plans import Plan
from model_routing.ladder import ProjectRung, Rung
from loop_claude.cycle import prompts
from agent_cycle.worker_prompts import WorkerPrompts
from claude_code.transcript import read_transcript
from loop_claude.cycle.retry import retried
from agent_cycle.retry import retried
from model_routing.route import Route
from loop_claude.cycle import spend
from loop_claude.stop import Stop
from loop_claude.tmux import Window
from agent_cycle import spend
from agent_cycle.stop import Stop
from agent_cycle.tmux import Window
from model_routing import worker_rungs
@@ -44,6 +42,8 @@ class Cycle:
# The rung routing.judge_rung picks for the project's judge model.
judge: Rung
premises: str
# The prompts and the file names of the entry point that drives the cycle.
prompts: WorkerPrompts
# The project's rung on the ladder that model_routing/ladder_file.py read as the cycle started; None for a model off the ladder.
project: ProjectRung | None
project_archive: pathlib.Path
@@ -52,8 +52,8 @@ class Cycle:
route: Route
session: Session
task: str
# The plan on the default branch as the cycle starts, which scores the items the worker names.
plan: Plan | Failure
# The plan items a transcript's worker has taken into its chunk, as the entry point reads and scores them.
taken_in: typing.Callable[[list[Entry]], TakenIn]
# Empty when the previous cycle's verdict was not Unfinished.
unfinished_evidence: str
# The tmux window the loop runs in, which an interrupt marks.
@@ -120,7 +120,7 @@ def step(cycle: Cycle, state: Active) -> Event | Stop:
def work(cycle: Cycle, answered: QuotedAnswer | TypedAnswer | None, stepped: bool) -> WorkerRan | Stop:
if isinstance(answered, QuotedAnswer):
say(f"\n=== {prompts.QUOTE_SOURCES} answered: {answered.question} ===\n{answered.answer}", cycle.effects, stdout=True)
say(f"\n=== {cycle.prompts.quote_sources} answered: {answered.question} ===\n{answered.answer}", cycle.effects, stdout=True)
# worker_start runs inside the lambda: a failed attempt may have opened the session.
if stop := retried("worker", lambda: run_worker(cycle.root, worker_start(cycle, answered, stepped), worker_environment(cycle), cycle.effects), cycle.effects):
return stop
@@ -139,24 +139,24 @@ def worker_session(cycle: Cycle, transcript_path: str) -> WorkerSession:
def worker_start(cycle: Cycle, answered: QuotedAnswer | TypedAnswer | None, stepped: bool) -> list[str]:
if isinstance(answered, QuotedAnswer):
return worker_args(cycle.session, cycle.route.rung, prompts.answered(answered.question, answered.answer, cycle.route, cycle.project, stepped), resume=True)
return worker_args(cycle.session, cycle.route.rung, cycle.prompts.answered(answered.question, answered.answer, cycle.route, cycle.project, stepped), resume=True)
if isinstance(answered, TypedAnswer):
return worker_args(cycle.session, cycle.route.rung, prompts.typed(answered.question, answered.answer, cycle.route, cycle.project, stepped), resume=True)
return worker_args(cycle.session, cycle.route.rung, cycle.prompts.typed(answered.question, answered.answer, cycle.route, cycle.project, stepped), resume=True)
if session_open(cycle.session):
return worker_args(cycle.session, cycle.route.rung, prompts.resumed(cycle.unfinished_evidence, cycle.route, cycle.project), resume=True)
return worker_args(cycle.session, cycle.route.rung, prompts.fresh(cycle.task, cycle.premises, cycle.route, cycle.project, cycle.facts), resume=False)
return worker_args(cycle.session, cycle.route.rung, cycle.prompts.resumed(cycle.unfinished_evidence, cycle.route, cycle.project), resume=True)
return worker_args(cycle.session, cycle.route.rung, cycle.prompts.fresh(cycle.task, cycle.premises, cycle.route, cycle.project, cycle.facts), resume=False)
def rule(cycle: Cycle, transcript_path: str, quoted_answers: int) -> Ruled | Stop:
"""The judge's ruling. Unless it is Finished, code stamps it with the items the worker names on its latest `Chunk items:` line. An interrupt or a quoted answer is archived as it is ruled, on the route the worker ran on until then, and then any step-up it makes, so the figures charge each stretch of work to its own rung."""
"""The judge's ruling. Unless it is Finished, code stamps it with the items the worker took in, as cycle.taken_in reads them. An interrupt or a quoted answer is archived as it is ruled, on the route the worker ran on until then, and then any step-up it makes, so the figures charge each stretch of work to its own rung."""
entries = read_transcript(transcript_path)
if isinstance(entries, Failure):
return Stop(1, entries.reason)
verdict = judge(cycle.root, Brief(cycle.task, cycle.premises, cycle.records, entries, cycle.route.escalated_at), cycle.judge, cycle.effects, lambda rejected: keep_rejection(cycle, transcript_path, rejected))
verdict = judge(cycle.root, Brief(cycle.task, cycle.premises, cycle.records, cycle.prompts.answer_destinations, entries, cycle.route.escalated_at), cycle.judge, cycle.effects, lambda rejected: keep_rejection(cycle, transcript_path, rejected))
if isinstance(verdict, Stop):
return verdict
if not isinstance(verdict, Finished):
verdict = dataclasses.replace(verdict, taken_in=chunk_items.taken_in(entries, cycle.plan))
verdict = dataclasses.replace(verdict, taken_in=cycle.taken_in(entries))
if not isinstance(verdict, Interrupt | QuotedAnswer):
return Ruled(verdict)
annotation = annotation_of(cycle, transcript_path, entries, verdict.judged)
@@ -183,8 +183,8 @@ def annotation_of(cycle: Cycle, transcript_path: str, entries: list[Entry], judg
def ruling_outcome(cycle: Cycle, ruling: Interrupt | QuotedAnswer, quoted_answers: int, annotation: outcomes.Annotation) -> str:
"""The archive's outcome for a ruling: interrupted where it goes to the human, with the question put to them, and else answered from the premises or the records."""
if isinstance(ruling, QuotedAnswer) and not to_the_human(ruling, quoted_answers):
return outcomes.answered(question=ruling.question, sources=prompts.QUOTE_SOURCES, answer=ruling.answer, evidence=ruling.evidence, escalation=ruling.escalation, judge=str(cycle.judge), worker=cycle.route.worker_line(), judge_cost=ruling.judged.cost, annotation=annotation, judge_run=ruling.judged.run)
return outcomes.interrupted(question_for(ruling), ruling.evidence, str(cycle.judge), ruling.escalation, cycle.route.worker_line(), judge_cost=ruling.judged.cost, annotation=annotation, judge_run=ruling.judged.run)
return outcomes.answered(question=ruling.question, sources=cycle.prompts.quote_sources, answer=ruling.answer, evidence=ruling.evidence, escalation=ruling.escalation, judge=str(cycle.judge), worker=cycle.route.worker_line(), judge_cost=ruling.judged.cost, annotation=annotation, judge_run=ruling.judged.run)
return outcomes.interrupted(question_for(cycle, ruling), ruling.evidence, str(cycle.judge), ruling.escalation, cycle.route.worker_line(), judge_cost=ruling.judged.cost, annotation=annotation, judge_run=ruling.judged.run)
def keep_rejection(cycle: Cycle, transcript_path: str, rejected: Rejected) -> Stop | None:
@@ -197,7 +197,7 @@ def keep_rejection(cycle: Cycle, transcript_path: str, rejected: Rejected) -> St
def ask(cycle: Cycle, transcript_path: str, ruling: Interrupt | QuotedAnswer) -> HumanTyped | HumanTalked | Stop:
"""The human's answer to a ruling that rule archived as it ruled; the human's answer then grows the transcript."""
# Only the human may cut a release, so a release ready to cut opens claude's session at once.
answer = interrupt(question_for(ruling), not (isinstance(ruling, Interrupt) and ruling.release_ready), worker_session(cycle, transcript_path), cycle.window, cycle.effects)
answer = interrupt(question_for(cycle, ruling), not (isinstance(ruling, Interrupt) and ruling.release_ready), worker_session(cycle, transcript_path), cycle.window, cycle.effects)
match answer:
case Stop():
return answer
@@ -221,10 +221,10 @@ def archived_step(project_archive: pathlib.Path, transcript_path: str, task: str
return archived(project_archive, transcript_path, task, outcomes.stepped_up(step_up.after.worker_line()), effects)
def question_for(ruling: Interrupt | QuotedAnswer) -> str:
def question_for(cycle: Cycle, ruling: Interrupt | QuotedAnswer) -> str:
if isinstance(ruling, Interrupt):
return ruling.question
return prompts.past_the_cap(ruling.question, ruling.answer, QUOTED_ANSWERS_PER_CYCLE)
return cycle.prompts.past_the_cap(ruling.question, ruling.answer, QUOTED_ANSWERS_PER_CYCLE)
def close(cycle: Cycle, transcript_path: str, verdict: Finished | Unfinished) -> Archived | Stop:
@@ -1,6 +1,6 @@
import dataclasses
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
from agent_cycle.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
from model_routing.route import Route
# A backstop for what the judge misses, such as a reworded repeat, so the worker cannot loop unattended on answers quoted from the premises or the records.
+21
View File
@@ -0,0 +1,21 @@
import ast
import pathlib
import unittest
PACKAGE = pathlib.Path(__file__).resolve().parent
# The packages of the entry points that drive a cycle.
ENTRY_POINTS = ("loop_claude", "do_epic")
class Imports(unittest.TestCase):
def test_no_module_imports_an_entry_points_package_so_a_second_entry_point_drives_the_cycle_alone(self):
imported = []
for path in sorted(PACKAGE.glob("*.py")):
for node in ast.walk(ast.parse(path.read_text())):
names = [node.module or ""] if isinstance(node, ast.ImportFrom) else [alias.name for alias in node.names] if isinstance(node, ast.Import) else []
imported += [(path.name, name) for name in names if name.split(".")[0] in ENTRY_POINTS]
self.assertEqual(imported, [])
if __name__ == "__main__":
unittest.main()
@@ -4,7 +4,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from loop_claude import quotes
from agent_cycle import quotes
class Verbatim(unittest.TestCase):
+58
View File
@@ -0,0 +1,58 @@
"""The prompts that resume a worker with an answer to its question, worded with what the entry point driving the cycle supplies.
An entry point, such as loop-claude, words the prompts of its own workflow and names the files of its project. WorkerPrompts holds those, so the cycle and the judge name none of them.
"""
import dataclasses
import typing
from claude_code.transcript import Typed
from model_routing.ladder import ProjectRung
from model_routing.route import Route
# Opens typed's prompt, with the answer on the line after it, so typed_answer finds the answer at the prompt's start, whatever the question holds.
TYPED_HERE = "The human answered your question at loop-claude's terminal:"
def answers_recorded(destinations: str) -> str:
"""What a chunk owes each answer the human typed, before it is finished. destinations names where an answer may be recorded."""
return f"every answer the human typed in it that a later chunk could need is recorded in {destinations} at the one place it governs"
def typed_answer(prompt: str) -> Typed | None:
"""Splits a prompt from WorkerPrompts.typed into its answer and the rest, so the judge reads the answer as the human's; None for any other prompt."""
opening = f"{TYPED_HERE}\n"
if not prompt.startswith(opening):
return None
answer, _, rest = prompt.removeprefix(opening).partition("\n\n")
return Typed(rest, answer)
@dataclasses.dataclass(frozen=True)
class WorkerPrompts:
"""What an entry point supplies to the prompts of its cycles."""
# The prompt that starts a worker, from its task, the premises, its route, the project's rung and the facts found before the cycle.
fresh: typing.Callable[[str, str, Route, ProjectRung | None, str], str]
# The prompt that resumes a worker whose previous run ended before the chunk was finished, from the evidence of the unfinished verdict, if there was one.
resumed: typing.Callable[[str, Route, ProjectRung | None], str]
# The sentences that depend on the worker's rung, each after a space, to follow the sentence a prompt ends on.
rungs_held: typing.Callable[[Route, ProjectRung | None], str]
# Where the judge may quote an answer from, named as the human and the worker see them.
quote_sources: str
# Where the worker may record an answer the human typed.
answer_destinations: str
def answered(self, question: str, answer: str, route: Route, project: ProjectRung | None, stepped: bool) -> str:
"""stepped is whether the answer's ruling stepped the worker up."""
return f"Your question: {question}\n\n{self.quote_sources} answers it:\n\n{answer}\n\nContinue the task.{self.stepped_to(route, project, stepped)}"
def typed(self, question: str, answer: str, route: Route, project: ProjectRung | None, stepped: bool) -> str:
"""The prompt that resumes the worker with the human's answer to an interrupt. answer is one line, as the terminal reads it."""
return f"{TYPED_HERE}\n{answer}\n\nYour question was: {question}\n\nContinue the task. The chunk is finished only once {answers_recorded(self.answer_destinations)}.{self.stepped_to(route, project, stepped)}"
def stepped_to(self, route: Route, project: ProjectRung | None, stepped: bool) -> str:
"""The sentences naming the worker's new rung, as resumed has them, where the ruling that brought the answer stepped the worker up; empty otherwise."""
return f" Your request for a higher rung went through: loop-claude runs you on {route.rung}. The escalation triggers that fired before this step are spent.{self.rungs_held(route, project)}" if stepped else ""
def past_the_cap(self, question: str, answer: str, cap: int) -> str:
"""The question a quoted answer puts to the human once the cycle's quoted answers reach the cap."""
return f"{question}\n\n{self.quote_sources} says:\n{answer}\n\nThose files have answered {cap} questions this cycle, the most allowed, so this one comes to you."
+5 -4
View File
@@ -1,9 +1,10 @@
from claude_code.entries import Entry
from loop_claude import escalation_mark
from agent_cycle import escalation_mark
from failure import Failure
from loop_claude.cycle.judge import Grounds, JUDGE_RULES, TASK_HEADING, TRANSCRIPT_HEADING
from agent_cycle.judge import Grounds, judge_rules, TASK_HEADING, TRANSCRIPT_HEADING
from claude_code.transcript import human_answers
from loop_claude.cycle.prompts import typed_answer
from agent_cycle.worker_prompts import typed_answer
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS
def grounds_of(prompt: str, entries: list[Entry]) -> Grounds | Failure:
@@ -12,4 +13,4 @@ def grounds_of(prompt: str, entries: list[Entry]) -> Grounds | Failure:
_, transcript_heading, shown = after_task.partition(TRANSCRIPT_HEADING)
if not (task_heading and transcript_heading):
return Failure(f"the archived prompt lacks the heading {TASK_HEADING.strip()!r} or {TRANSCRIPT_HEADING.strip()!r}, which judge_prompt writes")
return Grounds(shown.removesuffix(f"\n\n{JUDGE_RULES}"), escalation_mark.after_mark(entries, 0), before_task, tuple(human_answers(entries, typed_answer)))
return Grounds(shown.removesuffix(f"\n\n{judge_rules(ANSWER_DESTINATIONS)}"), escalation_mark.after_mark(entries, 0), before_task, tuple(human_answers(entries, typed_answer)))
+5 -4
View File
@@ -23,7 +23,7 @@ it, missed none.
Record each run in docs/decisions.md → `routing: on a model judge-replay covered`. Where the
model's cheapest rung misses no interrupt, the run is the evidence to add the model to
JUDGE_REPLAYED in bin/loop_claude/routing.py, which routes that model's judge. judge_rung there
JUDGE_REPLAYED in bin/agent_cycle/routing.py, which routes that model's judge. judge_rung there
keeps the judge to its own model's rungs; a rung above them that misses no interrupt is the
evidence to let the judge climb onto it.
@@ -57,7 +57,7 @@ from transcript_archive.location import archive_root, transcript_of
from transcript_archive.read import archived_outcomes
from rung_replay.archive import archiving, print_report, replay_folder
from rung_replay.command import arguments_or_exit, down_from, failed, limited_exit, projects_on
from loop_claude.cycle.judge import Brief, judge_archived, judge_once
from agent_cycle.judge import Brief, judge_archived, judge_once
from judge_replay.replay import Case, case_from, Kind, report, reproduced, sample, verdict_kind
from transcript_archive.project_key import checkout_of
from loop_effects.effects import Effects
@@ -69,10 +69,11 @@ from transcript_archive.judge_run import JudgeRun
from model_routing.ladder import Ladder, ProjectRung, REVIEW_STEPS, Rung
from claude_code.reply import Limited
from model_routing.ladder_file import read_ladder, SHIPPED
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS
from loop_claude.project.premises import read_premises
from loop_claude.project.records import read_records
from claude_code.transcript import read_transcript
from loop_claude.verdicts import Verdict
from agent_cycle.verdicts import Verdict
TOOL = "judge-replay"
USAGE = f"{TOOL} <model> [--offline]; <model> is a model on the routing ladder"
@@ -171,5 +172,5 @@ def rule(case: Case, rung: Rung, home: pathlib.Path, effects: Effects) -> Kind |
if isinstance(records, Failure):
return verdict_kind(records)
# 0 for the route's mark, as before any step-up: the replay compares verdict kinds, and a mark changes only which escalation quotes count.
verdict = first_reply(lambda: judge_once(case.root, Brief(case.task, premises, records, entries, 0), rung, effects))
verdict = first_reply(lambda: judge_once(case.root, Brief(case.task, premises, records, ANSWER_DESTINATIONS, entries, 0), rung, effects))
return verdict if isinstance(verdict, Limited) else verdict_kind(verdict)
+1 -1
View File
@@ -6,7 +6,7 @@ import typing
from transcript_archive.outcomes import ANSWERED, FINISHED, first_verdict, INTERRUPTED, judge_run_at, task_of, UNFINISHED
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
from agent_cycle.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
from rung_replay.search import Replay
from model_routing.ladder import Rung
+5 -4
View File
@@ -16,9 +16,10 @@ from text_files import compressed
from project_config.test_project_config import configured
from loop_effects.effects import Effects
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished
from agent_cycle.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished
from judge_replay.archived_prompt import grounds_of
from loop_claude.cycle.judge import judge_archived, JUDGE_RULES, Rejected, TASK_HEADING, TRANSCRIPT_HEADING
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS
from agent_cycle.judge import judge_archived, judge_rules, Rejected, TASK_HEADING, TRANSCRIPT_HEADING
from judge_replay import main
from rung_replay.search import Miss, Replay, Tried
from model_routing.ladder import Rung
@@ -328,7 +329,7 @@ class Main(unittest.TestCase):
class JudgeArchivedRuns(unittest.TestCase):
"""judge_archived on a prompt as judge_prompt writes it: the premises, the task, the transcript the judge was shown, and the rules."""
PROMPT = f"HEAD: Ship fast.\n\n{TASK_HEADING}Do it.\n\n{TRANSCRIPT_HEADING}Worker chose option B.\n[human] Use Postgres.\n\n{JUDGE_RULES}"
PROMPT = f"HEAD: Ship fast.\n\n{TASK_HEADING}Do it.\n\n{TRANSCRIPT_HEADING}Worker chose option B.\n[human] Use Postgres.\n\n{judge_rules(ANSWER_DESTINATIONS)}"
ENTRIES = [AssistantTurn(parts=(Text("Worker chose option B."),)), HumanTurn(text="Use Postgres."), LoopPrompt(text="Keep going.")]
def judged(self, prompt=PROMPT, **fields):
@@ -361,7 +362,7 @@ class JudgeArchivedRuns(unittest.TestCase):
self.assertEqual((type(rejected), rejected.cost), (Rejected, 0.25))
def test_checks_neither_the_task_nor_the_rules_as_the_transcript_or_the_premises(self):
self.assertIsInstance(self.judged(evidence=JUDGE_RULES)[0], Rejected)
self.assertIsInstance(self.judged(evidence=judge_rules(ANSWER_DESTINATIONS))[0], Rejected)
self.assertIsInstance(self.judged(answer="Do it.", question="Which?")[0], Interrupt)
def test_splits_the_prompt_at_the_first_transcript_heading(self):
+1 -1
View File
@@ -1,4 +1,4 @@
"""loop-claude: headless claude cycles, judged, that interrupt the human only for a decision that is theirs (loop/usage.py's help).
Its packages hold one concern each: cycle/ runs a cycle, loop/ runs the cycles, and project/ reads a checkout's files. Its paths live in bin/loop_state/, and its effects in bin/loop_effects/. Each module at this level is imported by more than one package, or by a module at this level that is. A reader finds a module by its name, so the modules stay at one level. docs/decisions.md → `principles: about seven things per level, …` allows that.
Its packages hold one concern each: cycle/ words the worker's prompts and reads the items it names, loop/ runs the cycles, and project/ reads a checkout's files. The cycle itself, its judge, interrupts and routing live in bin/agent_cycle/, which other entry points drive too. Its paths live in bin/loop_state/, and its effects in bin/loop_effects/. Each module at this level is imported by more than one package, or by a module at this level that is. A reader finds a module by its name, so the modules stay at one level. docs/decisions.md → `principles: about seven things per level, …` allows that.
"""
+2 -2
View File
@@ -3,9 +3,9 @@ import re
from claude_code.entries import AssistantTurn, Entry, Text
from failure import Failure
from loop_claude.quotes import plain
from agent_cycle.quotes import plain
from plan_store.plans import Plan
from loop_claude.verdicts import TakenIn
from agent_cycle.verdicts import TakenIn
# The label opening the line; prompts.NAME_THE_ITEMS asks the worker for it.
CHUNK_ITEMS = "Chunk items:"
+5 -34
View File
@@ -1,19 +1,19 @@
"""What loop-claude says to the worker each cycle. model_routing.review_choice chooses where the reviews run. review_launches and reruns put that choice into sentences, and escalation says where escalated subagents run; rung_sentences returns the sentences of all three. In a chunk's first prompt, routed_by places them after its routing sentences where an item routed the chunk, and fresh places them alone otherwise. rungs_held repeats them at the end of a prompt after a step-up or an unfinished verdict."""
from model_routing.review_choice import chosen, ReviewChoice
from agent_cycle.worker_prompts import answers_recorded, WorkerPrompts
from loop_claude.cycle.chunk_items import CHUNK_ITEMS
from model_routing.route import ESCALATION_MARKER, Route
from loop_claude.routing import escalation_rungs
from agent_cycle.routing import escalation_rungs
from loop_claude.project.records import HUMAN_RULE_NAMES, RECORD_FILES
from review_rules.review_passes import INSTRUCTION_FILES, INSTRUCTION_FOLDERS
from text_files.markdown_text import listed, quoted
from model_routing.ladder import ProjectRung, Rung
from claude_code.transcript import Typed
# Where the judge may quote an answer from, named as the human and the worker see them; of the goals file the judge sees only the premises.
QUOTE_SOURCES = listed(("the goals file's Goals and Audience", *RECORD_FILES, *HUMAN_RULE_NAMES), "or")
# Where the worker may write an answer the human typed, so it counts as recorded.
ANSWER_DESTINATIONS = "the goals file's Goals or Audience, " + ", ".join(RECORD_FILES) + ", the plan or a comment"
ANSWERS_RECORDED = f"every answer the human typed in it that a later chunk could need is recorded in {ANSWER_DESTINATIONS} at the one place it governs"
ANSWERS_RECORDED = answers_recorded(ANSWER_DESTINATIONS)
# How review_launches names the reviews: "each reviewer" covers every pass with an agent.
EACH_REVIEWER = "each reviewer"
EACH_SEAT = "each comprehension seat"
@@ -180,34 +180,5 @@ def rungs_held(route: Route, project: ProjectRung | None) -> str:
return "".join(f" {sentence}" for sentence in rung_sentences(route, project))
def answered(question: str, answer: str, route: Route, project: ProjectRung | None, stepped: bool) -> str:
"""stepped is whether the answer's ruling stepped the worker up."""
return f"Your question: {question}\n\n{QUOTE_SOURCES} answers it:\n\n{answer}\n\nContinue the task.{stepped_to(route, project, stepped)}"
def typed(question: str, answer: str, route: Route, project: ProjectRung | None, stepped: bool) -> str:
"""The prompt that resumes the worker with the human's answer to an interrupt. answer is one line, as the terminal reads it."""
return f"{TYPED_HERE}\n{answer}\n\nYour question was: {question}\n\nContinue the task. The chunk is finished only once {ANSWERS_RECORDED}.{stepped_to(route, project, stepped)}"
# Opens typed's prompt, with the answer on the line after it, so typed_answer finds the answer at the prompt's start, whatever the question holds.
TYPED_HERE = "The human answered your question at loop-claude's terminal:"
def typed_answer(prompt: str) -> Typed | None:
"""Splits a prompt from typed() into its answer and the rest, so the judge reads the answer as the human's; None for any other prompt."""
opening = f"{TYPED_HERE}\n"
if not prompt.startswith(opening):
return None
answer, _, rest = prompt.removeprefix(opening).partition("\n\n")
return Typed(rest, answer)
def stepped_to(route: Route, project: ProjectRung | None, stepped: bool) -> str:
"""The sentences naming the worker's new rung, as resumed has them, where the ruling that brought the answer stepped the worker up; empty otherwise."""
return f" Your request for a higher rung went through: loop-claude runs you on {route.rung}. The escalation triggers that fired before this step are spent.{rungs_held(route, project)}" if stepped else ""
def past_the_cap(question: str, answer: str, cap: int) -> str:
"""The question a quoted answer puts to the human once the cycle's quoted answers reach the cap."""
return f"{question}\n\n{QUOTE_SOURCES} says:\n{answer}\n\nThose files have answered {cap} questions this cycle, the most allowed, so this one comes to you."
# What loop-claude supplies to the prompts of its cycles.
WORKER = WorkerPrompts(fresh, resumed, rungs_held, QUOTE_SOURCES, ANSWER_DESTINATIONS)
+2 -1
View File
@@ -6,7 +6,8 @@ from git_cli.git_repo import default_ref
from release_plan.release_standing import DefaultPlan, project_plan, UNSEEN_RELEASES
from loop_effects.effects import Effects, say
from failure import Failure
from loop_claude.routing import first_route, kept, routed_item
from agent_cycle.routing import first_route, kept
from loop_claude.routed_item import routed_item
from loop_claude.loop.chunk_windows import held_beside, item_of
from chunk_preflight.main import ITEM
from plan.todo_table import Item
+1 -1
View File
@@ -20,7 +20,7 @@ from transcript_archive.project_key import project_key
from release_plan.release_standing import project_plan
from claude_code.transcript import read_transcript
from claude_code.session import Session, session_named, transcript_file
from loop_claude import tmux
from agent_cycle import tmux
# Under the home folder, a folder per project key holds LOCK.
STATE = ".local/state/loop-claude"
+4 -4
View File
@@ -2,12 +2,12 @@
import dataclasses
import pathlib
from loop_claude.cycle.run import archived_step, archived_stop, Concluded
from loop_claude.verdicts import Finished
from agent_cycle.run import archived_step, archived_stop, Concluded
from agent_cycle.verdicts import Finished
from loop_claude.loop.this_loop import Loop
from loop_claude.loop.reload import LoopRun
from loop_claude.stop import needs_human, Stop
from loop_claude.routing import next_route, step_up
from agent_cycle.stop import needs_human, Stop
from agent_cycle.routing import next_route, step_up
from model_routing.ladder import ProjectRung
from claude_code.session import transcript_file
+9 -7
View File
@@ -3,29 +3,30 @@ import pathlib
import typing
from transcript_archive.location import archive_root, project_archive
from loop_claude.cycle import chunk_items, prompts
from loop_claude.loop.chunk_start import archived_route, chunk_start, plan_item, routed, scored_plan
from loop_claude.loop.routing_check import check_routing
from loop_claude.project.checkout import checkout_root
from loop_claude.loop.chunk_windows import CHUNK_FLAG, chunk_session, item_of, start_chunks
from loop_claude.loop.close import closed_cycle
from loop_claude.cycle.run import Cycle, run_cycle
from agent_cycle.run import Cycle, run_cycle
from loop_claude.loop.reload import decode_handed, exec_if_edited, fingerprint, LoopRun, RELOAD_FLAG
from loop_effects.effects import Effects, say
from failure import Failure
from loop_claude.verdicts import Finished
from agent_cycle.verdicts import Finished
from loop_claude.project.model_choice import get_or_ask_models
from git_cli.git_repo import Git
from loop_claude.loop.usage import HELP
from loop_claude.routing import judge_rung
from agent_cycle.routing import judge_rung
from loop_claude.loop.this_loop import Loop
from loop_state.paths import Paths
from transcript_archive.project_key import project_key
from model_routing.ladder_file import project_ladder_file, read_ladder, SHIPPED
from loop_claude.project.premises import read_premises
from loop_claude.project.records import read_records
from loop_claude.stop import Stop
from loop_claude.direct_message import tell
from loop_claude import tmux
from agent_cycle.stop import Stop
from agent_cycle.direct_message import tell
from agent_cycle import tmux
def main(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher: pathlib.Path, cwd: pathlib.Path, effects: Effects) -> int:
@@ -129,7 +130,8 @@ def next_cycle(loop_run: LoopRun, loop: Loop) -> Cycle | Stop:
say(f"\n=== cycle {loop_run.cycle_number}, worker on {route.rung} ===", loop.effects, stdout=True)
if ladder_file != SHIPPED:
say(own_ladder(ladder_file, models.worker, project is None), loop.effects)
return Cycle(config=setup_version(loop.paths.claude_dir, loop.effects.git), effects=loop.effects, facts=facts, judge=judge_rung(ladder, models.judge), premises=premises, project=project, project_archive=archive_folder, records=records, root=loop.root, route=route, session=loop.session, task=loop_run.task, plan=scored_plan(default, loop.effects), unfinished_evidence=loop_run.unfinished_evidence, window=loop.window)
plan = scored_plan(default, loop.effects)
return Cycle(config=setup_version(loop.paths.claude_dir, loop.effects.git), effects=loop.effects, facts=facts, judge=judge_rung(ladder, models.judge), premises=premises, project=project, project_archive=archive_folder, records=records, root=loop.root, route=route, session=loop.session, task=loop_run.task, prompts=prompts.WORKER, taken_in=lambda entries: chunk_items.taken_in(entries, plan), unfinished_evidence=loop_run.unfinished_evidence, window=loop.window)
def own_ladder(file: pathlib.Path, model: str, unrouted: bool) -> str:
+1 -1
View File
@@ -8,7 +8,7 @@ import typing
from loop_claude.loop.this_loop import Loop
from model_routing.route import Route, route_of
from loop_effects.effects import say
from loop_claude.stop import Stop
from agent_cycle.stop import Stop
RELOAD_FLAG = "--reloaded"
+3 -3
View File
@@ -3,7 +3,7 @@ import pathlib
from routing_figures import archive
from routing_figures.calls import Call, calls, totals
from loop_claude.hand_over import claude_args, ClaudeCommand, hand_over
from agent_cycle.hand_over import claude_args, ClaudeCommand, hand_over
from loop_effects.effects import Effects, say
from failure import Failure
from loop_claude.loop.this_loop import Loop
@@ -12,8 +12,8 @@ from model_routing.ladder_file import read_ladder, SHIPPED
from routing_figures.render import render
from model_routing.ladder import Rung
from routing_figures import state
from loop_claude.stop import Stop
from loop_claude.direct_message import tell
from agent_cycle.stop import Stop
from agent_cycle.direct_message import tell
from text_files.utc_stamp import utc
+1 -1
View File
@@ -5,7 +5,7 @@ import typing
from loop_effects.effects import Effects
from loop_state.paths import Paths
from claude_code.session import Session
from loop_claude.tmux import Window
from agent_cycle.tmux import Window
@dataclasses.dataclass(frozen=True)
+3 -3
View File
@@ -49,7 +49,7 @@ claude session is named "A <key> loop-claude <window>", so a rerun resumes a chu
deleted when the chunk finishes. A fresh worker is told the items the project's other chunks hold,
running or stopped: each one's own and those on its latest `Chunk items:` line, and leaves them out.
A question only the human can answer is an interrupt (bin/loop_claude/cycle/interrupt.py).
A question only the human can answer is an interrupt (bin/agent_cycle/interrupt.py).
loop-claude prints the question in the chunk's window and rings its bell. Until it is answered the
window's name ends in " ?", as in "item-372 ?", which tmux's status bar shows. The human answers it
there:
@@ -82,7 +82,7 @@ Before each worker starts, loop-claude waits until at least a quarter of the mac
available (bin/machine_load/memory.py).
Each worker's claude, the session /talk opens and the subagents either launches run with a 200k
auto-compact window (CLAUDE_CODE_AUTO_COMPACT_WINDOW, bin/loop_claude/cycle/worker.py), so each
auto-compact window (CLAUDE_CODE_AUTO_COMPACT_WINDOW, bin/agent_cycle/worker.py), so each
compacts its context at about 170k tokens. They also save a Bash result of more than 6,000
characters to a file and see its path and the first 2,000 characters (BASH_MAX_OUTPUT_LENGTH,
bin/claude_code/output_limits.py).
@@ -101,7 +101,7 @@ models on another; a chunk no item routes runs on the project's model. The worke
rungs it launches its reviews on. The worker's rung steps up as a chunk stays unfinished, when the
worker names on its `Chunk items:` line an item that picks a higher rung, or when the judge finds
in the transcript an escalation trigger that fired and the worker asked for a higher rung. The
rules are in bin/loop_claude/routing.py and bin/model_routing/ladder.py, the choice of
rules are in bin/agent_cycle/routing.py and bin/model_routing/ladder.py, the choice of
each review's rung in bin/model_routing/review_choice.py, and the prompts' wording in
bin/loop_claude/cycle/prompts.py. Each verdict, interrupt, quoted answer, stop and
step-up in the archive ends with a Worker: line, the route as JSON (Route.worker_line in
+1 -1
View File
@@ -3,7 +3,7 @@ import pathlib
from failure import Failure
from loop_effects.effects import Effects
from loop_claude.stop import Stop
from agent_cycle.stop import Stop
def checkout_root(cwd: pathlib.Path, effects: Effects) -> str | Stop:
+1 -1
View File
@@ -7,7 +7,7 @@ import typing
from claude_code.model_catalog import catalog_models
from loop_effects.effects import Effects, say
from failure import Failure
from loop_claude.stop import needs_human, needs_terminal, Stop
from agent_cycle.stop import needs_human, needs_terminal, Stop
from loop_state.paths import Paths
from text_files.file_writes import replace_json
+19
View File
@@ -0,0 +1,19 @@
"""The plan item that routes a fresh chunk of loop-claude's: agent_cycle/routing.py's first_route picks the worker's rung from its L."""
from failure import Failure
from plan.todo_table import Item, NoItemsTable
from plan_store.plans import Plan
from release_plan.release_standing import chunk_item, LastCut, Next
def routed_item(plan: Plan | Failure, cut: LastCut, item_id: int | None = None) -> Item | Failure | None:
"""The plan's item item_id, or without one the item release_standing.chunk_item picks from plan, weighed against the last cut; None when there is none, or it lacks L, E or I."""
if isinstance(plan, NoItemsTable):
return None
if isinstance(plan, Failure):
return plan
if item_id is None:
pick = chunk_item(plan.items, cut)
takes = pick.item if isinstance(pick, Next) else None
else:
takes = next((item for item in plan.items if item.id == item_id), None)
return takes if takes and takes.likelihood and takes.escape_and_impact else None
+65 -61
View File
@@ -11,6 +11,7 @@ import stat
import subprocess
import sys
import tempfile
import types
import unittest
import unittest.mock
import uuid
@@ -28,9 +29,11 @@ from release_plan.release_standing import DefaultPlan, LastCut, UNSEEN_RELEASES
from loop_effects.effects import Effects, PYTHON_TIMEOUT
from claude_code import entries, reply, session
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, Judged, QuotedAnswer, TakenIn, Unfinished
from agent_cycle.verdicts import Finished, Interrupt, Judged, QuotedAnswer, TakenIn, Unfinished
from git_cli.git_repo import git
from loop_claude.cycle import interrupt, judge, prompts, retry, run, spend, states, worker
from agent_cycle import interrupt, judge, retry, run, spend, states, worker, worker_prompts
import loop_claude.routed_item
from loop_claude.cycle import prompts
from claude_code.reply import Limited
from loop_claude.loop import main, reload, routing_check, this_loop, usage
from machine_load import memory
@@ -42,13 +45,13 @@ from transcript_archive.location import project_archive
from model_routing.ladder import ProjectRung, Rung
from model_routing.ladder_file import read_ladder, SHIPPED
from model_routing.route import Route, route_from, WorkerLine
from loop_claude import routing
from loop_claude.stop import Stop
from loop_claude import tmux
from agent_cycle import routing
from agent_cycle.stop import Stop
from agent_cycle import tmux
from claude_code.tokens import Tokens, tokens_of
from touch_predictions.test_touch_predictions import plan as touch_plan
from text_files.utc_stamp import utc
from loop_claude.cycle.judge import verdict_from
from agent_cycle.judge import verdict_from
# How the archive records a worker that runs off the ladder.
LADDER = read_ladder(SHIPPED)
@@ -277,8 +280,9 @@ class Transitions(unittest.TestCase):
class QuestionFor(unittest.TestCase):
def test_puts_an_interrupts_question_as_asked_and_a_quoted_answer_past_the_cap_with_its_quote(self):
self.assertEqual(run.question_for(Interrupt("e", "Which one?")), "Which one?")
self.assertEqual(run.question_for(QuotedAnswer("e", "Which one?", "A.")), "Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's review standards says:\nA.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.")
cycle = types.SimpleNamespace(prompts=prompts.WORKER)
self.assertEqual(run.question_for(cycle, Interrupt("e", "Which one?")), "Which one?")
self.assertEqual(run.question_for(cycle, QuotedAnswer("e", "Which one?", "A.")), "Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's review standards says:\nA.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.")
class Cycles(unittest.TestCase):
@@ -291,7 +295,7 @@ class Cycles(unittest.TestCase):
self.archive = project_archive(str(self.home / "code" / "proj"), self.home, {})
def cycle(self, fake, records="", unfinished_evidence="", facts="- A preflight fact."):
return run.Cycle(config=CONFIG, window=WINDOW, effects=fake.effects(), facts=facts, judge=Rung("judge-model"), 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.", plan=plan_of(""), unfinished_evidence=unfinished_evidence)
return run.Cycle(config=CONFIG, window=WINDOW, effects=fake.effects(), facts=facts, judge=Rung("judge-model"), 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.", prompts=prompts.WORKER, taken_in=lambda entries: chunk_items.taken_in(entries, plan_of("")), unfinished_evidence=unfinished_evidence)
def archived_outcomes(self):
"""Each outcomes file's text without its `Judge run:` lines, which name a file by the hash of a prompt and its reply: the tests of the judge's runs check them."""
@@ -619,7 +623,7 @@ Spent since 2026-09-21T14:13:20Z, in tokens of input, cache write 5m, cache writ
resumed = fake.made("stream_claude")[1]
self.assertEqual(resumed[resumed.index("--resume") + 1], str(self.session.id))
typed = resumed[resumed.index("-p") + 1]
self.assertEqual(prompts.typed_answer(typed).answer, "Use B.")
self.assertEqual(worker_prompts.typed_answer(typed).answer, "Use B.")
self.assertIn("Which one?", typed)
self.assertIn("Continue the task. The chunk is finished only once every answer the human typed in it", typed)
judge_prompts = [stdin for args, stdin in fake.made("claude")]
@@ -1007,8 +1011,8 @@ class ModelPrompt(unittest.TestCase):
# A plan read with no release cut yet.
NO_CUT = LastCut(None, "", 0, [])
def routed_item(todo, cut):
"""routing.routed_item for the plan a todo.md's text holds."""
return routing.routed_item(plan_of(todo), cut)
"""loop_claude.routed_item.routed_item for the plan a todo.md's text holds."""
return loop_claude.routed_item.routed_item(plan_of(todo), cut)
TODO = """# todo
@@ -1710,13 +1714,13 @@ class TypedAnswers(unittest.TestCase):
def test_splits_the_prompt_handing_over_the_answer_into_the_answer_on_the_line_after_its_marker_and_the_rest_and_no_other_prompt(self):
route = Route(Rung("worker-model"))
marked = "The human answered your question at loop-claude's terminal:\nB"
typed = prompts.typed_answer(prompts.typed("Which one?", "Use B.", route, None, False))
typed = worker_prompts.typed_answer(prompts.WORKER.typed("Which one?", "Use B.", route, None, False))
self.assertEqual(typed.answer, "Use B.")
self.assertTrue(typed.loop_words.startswith("Your question was: Which one?\n\nContinue the task."))
self.assertEqual(prompts.typed_answer(prompts.typed(f"Which one?\n{marked}", "Use B.", route, None, False)).answer, "Use B.")
self.assertEqual(prompts.typed_answer(prompts.typed("Which one?", "Use B.", Route(Routing.SONNET, 179, 2, 5), OPUS_PROJECT, True)).answer, "Use B.")
self.assertIsNone(prompts.typed_answer(prompts.answered("Which one?", marked, route, None, False)))
self.assertIsNone(prompts.typed_answer(prompts.resumed(marked, route, None)))
self.assertEqual(worker_prompts.typed_answer(prompts.WORKER.typed(f"Which one?\n{marked}", "Use B.", route, None, False)).answer, "Use B.")
self.assertEqual(worker_prompts.typed_answer(prompts.WORKER.typed("Which one?", "Use B.", Route(Routing.SONNET, 179, 2, 5), OPUS_PROJECT, True)).answer, "Use B.")
self.assertIsNone(worker_prompts.typed_answer(prompts.WORKER.answered("Which one?", marked, route, None, False)))
self.assertIsNone(worker_prompts.typed_answer(prompts.resumed(marked, route, None)))
class WorkerArgs(unittest.TestCase):
@@ -1918,7 +1922,7 @@ class Records(unittest.TestCase):
class JudgePrompt(unittest.TestCase):
def test_shows_the_transcripts_tail_and_returns_what_it_showed(self):
entries = [assistant({"type": "text", "text": "old " + "x" * judge.JUDGE_PROMPT_CHARS}), assistant({"type": "text", "text": "new"})]
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", kinds(*entries), 0))
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 0))
self.assertTrue(grounds.shown.endswith("\n\nnew"))
self.assertNotIn("old", grounds.shown)
self.assertIn(grounds.shown, prompt)
@@ -1927,32 +1931,32 @@ class JudgePrompt(unittest.TestCase):
self.assertEqual(grounds.quotable, "## Goals\n\n")
def test_the_judge_prompt_and_schema_call_the_worker_the_worker(self):
prompt, _ = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", kinds(assistant({"type": "text", "text": "done"})), 1))
prompt, _ = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(assistant({"type": "text", "text": "done"})), 1))
self.assertNotRegex(prompt + json.dumps(judge.JUDGE_SCHEMA), r"\b[Aa]gent")
def test_the_judge_prompt_names_every_rule_the_judge_reads_from_the_human(self):
self.assertEqual([name for name in records.HUMAN_RULE_NAMES if name not in judge.JUDGE_RULES], [])
self.assertEqual([name for name in records.HUMAN_RULE_NAMES if name not in judge.judge_rules(prompts.ANSWER_DESTINATIONS)], [])
def test_shows_the_judge_where_the_worker_last_stepped_up_and_checks_an_escalation_only_after_it(self):
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "round 3: 🔴"})]
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", kinds(*entries), 1))
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1))
self.assertRegex(prompt, "round 2: 🔴\n\n\\[step\\] [^\n]+\n\nround 3: 🔴\n\n")
self.assertEqual(grounds.after_mark, "round 3: 🔴")
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", kinds(*entries), 0))
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 0))
self.assertNotIn("stepped the worker up", prompt)
self.assertEqual(grounds.shown, "round 2: 🔴\n\nround 3: 🔴")
self.assertEqual(grounds.after_mark, "round 2: 🔴\n\nround 3: 🔴")
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(judge.Brief("Do it.", "## Goals", "", kinds(*entries), 1))
_, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1))
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)
typed = prompts.WORKER.typed("Which one?", "Use B.", Route(Rung("worker-model")), None, False)
entries = [{**human(typed), "promptSource": "sdk"}, assistant({"type": "text", "text": "round 3: 🔴"})]
_, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", kinds(*entries), 1))
_, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1))
self.assertIn("\n\n[human] Use B.\n\n[step] ", grounds.shown)
@@ -2179,7 +2183,7 @@ class Verdict(unittest.TestCase):
def test_drops_an_escalation_quote_found_only_in_the_transcript_entries_before_the_workers_last_step_up(self):
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", judge.Brief("Do it.", "## Goals", "", kinds(*entries), mark), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", escalation=escalation)]).effects())
return judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), mark), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", escalation=escalation)]).effects())
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", "round 3: 🔴", entries_read=3))
@@ -2188,12 +2192,12 @@ class Verdict(unittest.TestCase):
def test_drops_an_escalation_quote_that_only_loop_claudes_prompts_or_the_humans_lines_repeat_after_the_step_up(self):
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), {**human("as the work remaining: round 2: 🔴"), "promptSource": "sdk"}, human("round 2: 🔴 again"), assistant({"type": "text", "text": "working"})]
verdict = judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", kinds(*entries), 1), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", escalation="round 2: 🔴")]).effects())
verdict = judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", escalation="round 2: 🔴")]).effects())
self.assertEqual(verdict, Unfinished("working", entries_read=4))
def test_takes_evidence_from_before_the_workers_last_step_up(self):
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "working"})]
verdict = judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", kinds(*entries), 1), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", evidence="round 2: 🔴")]).effects())
verdict = judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", evidence="round 2: 🔴")]).effects())
self.assertEqual(verdict, Unfinished("round 2: 🔴", entries_read=2))
@@ -2462,41 +2466,41 @@ class ExitContract(unittest.TestCase):
unreadable = f"the goals file, or {', '.join(names[:-1])} or {names[-1]} where they exist, cannot be read or is not UTF-8"
# Every Stop whose code is not a literal 0, 2 or 130, in source order: path, function, code, start of reason, its --help clause.
clauses = [
("cycle/interrupt.py", "claude_open", "1", "f'could not start claude for the interrupt:", "claude cannot start for an interrupt"),
("cycle/interrupt.py", "human_typed", "1", "entries.reason", read),
("cycle/interrupt.py", "human_typed", "1", "f'could not tell whether you typed anything:", read),
("cycle/retry.py", "retried", "1", "f'the {who} failed three times running:", "the worker or the judge fails three times running"),
("cycle/run.py", "archived_stop", "1", "f'{failure.reason}", read),
("cycle/run.py", "work", "1", "f'claude left no transcript for session", "claude leaves no transcript"),
("cycle/run.py", "rule", "1", "entries.reason", read),
("cycle/run.py", "rule", "1", "annotation.reason", read),
("cycle/run.py", "rule", "1", "failure.reason", read),
("cycle/run.py", "keep_rejection", "1", "unkept.reason", read),
("cycle/run.py", "close", "1", "annotation.reason", read),
("cycle/run.py", "close", "1", "failure.reason", read),
("cycle/run.py", "close", "1", "failure.reason", "a finished chunk's session cannot be deleted"),
("loop/close.py", "closed_cycle", "1", "failure.reason", read),
("loop/main.py", "run_loop", "1", "reason", "tmux is missing or older than 3.2"),
("loop/main.py", "run_loop", "1", "f'{CHUNK_FLAG} is how loop-claude starts itself", "--chunk is given outside a tmux window"),
("loop/main.py", "windows_opened", "1", "started.reason", "a chunk's window cannot be started"),
("loop/main.py", "windows_opened", "1", "f\"`tmux {' '.join(shown)}` failed", "the tmux session cannot be put on the terminal"),
("loop/main.py", "handed_on", "1", "f'the chunk finished, but the next could not start", "a chunk's window cannot be started"),
("loop/main.py", "next_cycle", "1", "premises.reason", premises_),
("loop/main.py", "next_cycle", "1", "records.reason", unreadable),
("loop/main.py", "next_cycle", "1", "ladder_file.reason", premises_),
("loop/main.py", "next_cycle", "1", "ladder.reason", "the project's routing ladder cannot be read or holds a fault"),
("loop/main.py", "loop_run_from", "0 if task else 1", "HELP", "no task is given"),
("loop/main.py", "loop_run_from", "1", 'f"the edited loop-claude cannot read the state', "a reload cannot read the state the running script handed it"),
("loop/reload.py", "exec_if_edited", "1", "f'could not reload loop-claude:", "python cannot start for a reload"),
("loop/routing_check.py", "raise_calls", "1", "f\"could not start claude for the routing calls in {loop.paths.config_clone}", "claude cannot start for an interrupt"),
("project/checkout.py", "checkout_root", "1", "found.reason", git),
("project/model_choice.py", "get_or_ask_model", "1", "models.reason", models_),
("project/model_choice.py", "get_or_ask_model", "1", "models.reason", models_),
("project/model_choice.py", "get_or_ask_model", "1", "f'could not save the model in", models_),
("agent_cycle/interrupt.py", "claude_open", "1", "f'could not start claude for the interrupt:", "claude cannot start for an interrupt"),
("agent_cycle/interrupt.py", "human_typed", "1", "entries.reason", read),
("agent_cycle/interrupt.py", "human_typed", "1", "f'could not tell whether you typed anything:", read),
("agent_cycle/retry.py", "retried", "1", "f'the {who} failed three times running:", "the worker or the judge fails three times running"),
("agent_cycle/run.py", "archived_stop", "1", "f'{failure.reason}", read),
("agent_cycle/run.py", "work", "1", "f'claude left no transcript for session", "claude leaves no transcript"),
("agent_cycle/run.py", "rule", "1", "entries.reason", read),
("agent_cycle/run.py", "rule", "1", "annotation.reason", read),
("agent_cycle/run.py", "rule", "1", "failure.reason", read),
("agent_cycle/run.py", "keep_rejection", "1", "unkept.reason", read),
("agent_cycle/run.py", "close", "1", "annotation.reason", read),
("agent_cycle/run.py", "close", "1", "failure.reason", read),
("agent_cycle/run.py", "close", "1", "failure.reason", "a finished chunk's session cannot be deleted"),
("loop_claude/loop/close.py", "closed_cycle", "1", "failure.reason", read),
("loop_claude/loop/main.py", "run_loop", "1", "reason", "tmux is missing or older than 3.2"),
("loop_claude/loop/main.py", "run_loop", "1", "f'{CHUNK_FLAG} is how loop-claude starts itself", "--chunk is given outside a tmux window"),
("loop_claude/loop/main.py", "windows_opened", "1", "started.reason", "a chunk's window cannot be started"),
("loop_claude/loop/main.py", "windows_opened", "1", "f\"`tmux {' '.join(shown)}` failed", "the tmux session cannot be put on the terminal"),
("loop_claude/loop/main.py", "handed_on", "1", "f'the chunk finished, but the next could not start", "a chunk's window cannot be started"),
("loop_claude/loop/main.py", "next_cycle", "1", "premises.reason", premises_),
("loop_claude/loop/main.py", "next_cycle", "1", "records.reason", unreadable),
("loop_claude/loop/main.py", "next_cycle", "1", "ladder_file.reason", premises_),
("loop_claude/loop/main.py", "next_cycle", "1", "ladder.reason", "the project's routing ladder cannot be read or holds a fault"),
("loop_claude/loop/main.py", "loop_run_from", "0 if task else 1", "HELP", "no task is given"),
("loop_claude/loop/main.py", "loop_run_from", "1", 'f"the edited loop-claude cannot read the state', "a reload cannot read the state the running script handed it"),
("loop_claude/loop/reload.py", "exec_if_edited", "1", "f'could not reload loop-claude:", "python cannot start for a reload"),
("loop_claude/loop/routing_check.py", "raise_calls", "1", "f\"could not start claude for the routing calls in {loop.paths.config_clone}", "claude cannot start for an interrupt"),
("loop_claude/project/checkout.py", "checkout_root", "1", "found.reason", git),
("loop_claude/project/model_choice.py", "get_or_ask_model", "1", "models.reason", models_),
("loop_claude/project/model_choice.py", "get_or_ask_model", "1", "models.reason", models_),
("loop_claude/project/model_choice.py", "get_or_ask_model", "1", "f'could not save the model in", models_),
]
root = pathlib.Path(main.__file__).parents[1]
root = pathlib.Path(main.__file__).parents[2]
found = []
for path in sorted(path for path in root.rglob("*.py") if not path.name.startswith("test_")):
for path in sorted(path for package in ("agent_cycle", "loop_claude") for path in (root / package).rglob("*.py") if not path.name.startswith("test_")):
functions = [node for node in ast.walk(ast.parse(path.read_text())) if isinstance(node, ast.FunctionDef)]
stops = [(call.lineno, function.name, ast.unparse(call.args[0]), ast.unparse(call.args[1])) for function in functions for call in ast.walk(function) if isinstance(call, ast.Call) and getattr(call.func, "id", None) == "Stop" and not (isinstance(call.args[0], ast.Constant) and call.args[0].value in (0, 2, 130))]
found += [(str(path.relative_to(root)), function, code, reason) for _, function, code, reason in sorted(stops)]
+1 -1
View File
@@ -52,7 +52,7 @@ class Route:
unfinished: int = 0
# The highest E + I among the items the worker names on its `Chunk items:` line, kept only where it picks a higher review step than the item's; 0 otherwise.
escape_and_impact_taken_in: int = 0
# The escalation mark, as loop_claude/escalation_mark.py says: how many transcript entries the session held when an escalation last stepped the worker up, 0 before any.
# The escalation mark, as agent_cycle/escalation_mark.py says: how many transcript entries the session held when an escalation last stepped the worker up, 0 before any.
escalated_at: int = 0
def __post_init__(self) -> None:
+1 -1
View File
@@ -5,7 +5,7 @@ import sys
import typing
from failure import Failure
from loop_claude.cycle.retry import FAILURES_RUNNING
from agent_cycle.retry import FAILURES_RUNNING
from claude_code.reply import Limited
from model_routing.ladder import Rung
+5 -5
View File
@@ -208,7 +208,7 @@ Valid while `~/.claude` is a checkout of this repo.
- **The archive and the route needed no change.** The archive keys each chunk by its own transcript's first line, and a rerun's route comes from the latest verdict on that transcript, so both follow the session. The routing figures are measured across all projects, under their own lock.
- **git's own lock serializes the config folder's commits, in place of the file lock the item asked for.** `git commit` holds `.git/index.lock`, so of two commits at once the second fails, and the worker tries again. A wrapper lock would only make it wait, and a command spelled `flock … git commit` would pass rule-hook unchecked, since it reads only a command that starts with `git`. What two chunks could still break is one committing the file the other staged, so each commits only its own file, as `git commit -m <title> -- <file>` (`CLAUDE.md` → "Git, commits, and PRs").
2026-11-16, lilleman's second call of 2026-11-13 splitting item 361: lilleman knows tmux and prefers it. Each chunk runs in its own window of one tmux session per project, `loop-<key>`, up to the number the config's `parallel-chunks` sets, 1 by default. tmux runs even at 1, so every project runs the same workflow (goal 1.3). A window waiting for the human ends its name in ` ?` and rings the bell, and the DM names `<session>:<window>`. The worker's choices, for what the call left open (`bin/loop_claude/tmux.py`, `bin/loop_claude/loop/chunk_windows.py`):
2026-11-16, lilleman's second call of 2026-11-13 splitting item 361: lilleman knows tmux and prefers it. Each chunk runs in its own window of one tmux session per project, `loop-<key>`, up to the number the config's `parallel-chunks` sets, 1 by default. tmux runs even at 1, so every project runs the same workflow (goal 1.3). A window waiting for the human ends its name in ` ?` and rings the bell, and the DM names `<session>:<window>`. The worker's choices, for what the call left open (`bin/agent_cycle/tmux.py`, `bin/loop_claude/loop/chunk_windows.py`):
- **The window, in place of item 372's lock-file slot, names the claude session**, as `A <key> loop-claude item-372`. The loop-claude the human runs starts the windows and attaches; each window runs `loop-claude --chunk <window>`, so a loop knows its chunk before it names its claude session, and a rerun still resumes the chunk left open.
- **A finishing chunk starts the next; only the human restarts a stopped one.** As its chunk finishes, a window's loop starts each chunk that may start then and exits, so its window closes. `remain-on-exit failed` keeps the window of a loop that stopped any other way, Ctrl-C included, with its last lines, and its chunk keeps its items. A finishing chunk never restarts it, since the human may have stopped it on purpose; the next `loop-claude <task>` starts it again before any other chunk. One flock under `~/.local/state/loop-claude/<key>/` serializes the starts, so two chunks finishing together don't start one chunk twice.
@@ -245,7 +245,7 @@ Valid while score-outcomes reads the reversals from the archive.
2026-10-27, lilleman's yes to claude's evaluation through todo todo item 231. Serves goal 1.4; its counter-signal, review rounds and unfinished verdicts per chunk, is the check.
loop-claude hands each worker's claude `CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000` (`bin/loop_claude/cycle/worker.py`), and the session /talk opens gets it too. Claude Code compacts before a window fills: a 1M window at about 967k tokens, and in a probe on 2026-10-27 a 100k window at 65k and 80k, so a 200k window compacts at about 170k. The window is not set in `settings.json`, since the archive measured loop-claude's workers and interactive sessions are lilleman's. Subagents inherit the variable, which reaches every process of the session: 68 of the 994 subagent runs since 2026-10-21, 7%, passed 170k, 24 of them principles auditors, so about one in fourteen compacts once. Compacting subagents by choice would cost more than it saves, as below, but the variable cannot leave them out, and `CLAUDE.md` → "Compact instructions" has a reviewer keep the findings it has drafted. That section shapes the summary: in another probe that day, a session whose CLAUDE.md asked for its summary to end with a secret word got a summary ending with that word. Path-scoped rules leave the context at a compaction and return at the next matching read, and rule-hook holds each review launch to its rung whatever the summary keeps. `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`, handed the same way, would compact at the same point but also cap the window at 200k, so a run that Claude Code stops compacting, as it does when one tool result refills the context each time, would hit the limit instead of going on.
loop-claude hands each worker's claude `CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000` (`bin/agent_cycle/worker.py`), and the session /talk opens gets it too. Claude Code compacts before a window fills: a 1M window at about 967k tokens, and in a probe on 2026-10-27 a 100k window at 65k and 80k, so a 200k window compacts at about 170k. The window is not set in `settings.json`, since the archive measured loop-claude's workers and interactive sessions are lilleman's. Subagents inherit the variable, which reaches every process of the session: 68 of the 994 subagent runs since 2026-10-21, 7%, passed 170k, 24 of them principles auditors, so about one in fourteen compacts once. Compacting subagents by choice would cost more than it saves, as below, but the variable cannot leave them out, and `CLAUDE.md` → "Compact instructions" has a reviewer keep the findings it has drafted. That section shapes the summary: in another probe that day, a session whose CLAUDE.md asked for its summary to end with a secret word got a summary ending with that word. Path-scoped rules leave the context at a compaction and return at the next matching read, and rule-hook holds each review launch to its rung whatever the summary keeps. `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`, handed the same way, would compact at the same point but also cap the window at 200k, so a run that Claude Code stops compacting, as it does when one tool result refills the context each time, would hit the limit instead of going on.
Why 200k. Item 231 asked for the best means to lower what a chunk spends on context, in dollars, then hours, with no loss of quality. Measured from loop-claude's archive, the 90 chunks with messages after the routing figures' reset of 2026-10-21 cost $1,215 at the list prices read on 2026-10-26 (Opus 5.5: $4 per million input tokens, $5 and $8 for 5-minute and 1-hour cache writes, $0.20 for cache reads, $20 for output; no model but Haiku 5.5 charges more above 200k). That is 0.86 of what the chunks' `cost-state` entries sum to, since some chunks' subagent transcripts are not in the archive. Worker main threads cost $375 (31%): 1-hour cache writes $149, cache reads $153, output $74. Subagents cost $840: 5-minute cache writes $379, output $274, cache reads $187, with the principles auditors at $274 over 342 runs, the stability reviewers $179 and general-purpose subagents $192. A worker starts at 41k tokens of context and peaks at a median 167k, one in ten past 358k, the largest at 848k. The worker's messages above 200k were 32% of its messages and 55% of its cost.
@@ -272,7 +272,7 @@ Valid while cache reads cost a twentieth of input and Claude Code's compaction k
2026-11-18, claude, as the plan item that asked for the ceiling set out. Applies project principle 1; serves goal 1.4.
loop-claude hands each worker's claude `BASH_MAX_OUTPUT_LENGTH=6000` (`worker_environment` in `bin/loop_claude/cycle/run.py`, the value in `bin/claude_code/output_limits.py`). Claude Code then saves a longer Bash result to a file under `~/.claude/projects/<project>/<session>/tool-results/` and hands the model the path and the first 2,000 characters, which a probe on 2026-11-17 confirmed. A subagent inherits the variable, so every reviewer the worker launches gets it too. The archive held 7,870 Bash results over 3,000 characters in workers (about $305 of carried context) and about $145 more in stability reviewers; a ceiling of 6,000 characters would have removed $228 of the workers', 10,000 characters $122.
loop-claude hands each worker's claude `BASH_MAX_OUTPUT_LENGTH=6000` (`worker_environment` in `bin/agent_cycle/run.py`, the value in `bin/claude_code/output_limits.py`). Claude Code then saves a longer Bash result to a file under `~/.claude/projects/<project>/<session>/tool-results/` and hands the model the path and the first 2,000 characters, which a probe on 2026-11-17 confirmed. A subagent inherits the variable, so every reviewer the worker launches gets it too. The archive held 7,870 Bash results over 3,000 characters in workers (about $305 of carried context) and about $145 more in stability reviewers; a ceiling of 6,000 characters would have removed $228 of the workers', 10,000 characters $122.
rule-hook's `transcript-read` rule refuses a Read of a `.jsonl` file under `~/.claude/projects`: a session transcript holds every tool result of its session, and the archive's Reads of old ones cost $46. It doesn't refuse a Read of `tool-results/*.txt`, which the ceiling hands the model, and it checks no Grep or Bash command. It can't be overridden, since a Read carries no text for a marker.
@@ -584,7 +584,7 @@ Valid while delegated searches save more context than their reports cost.
Four escalation triggers in `CLAUDE.md` → "Working with the codebase" mark a task too hard: a re-score of the item on the project's rung or above picks a higher rung, the same failing test or finding survives two fix attempts, a pass reports a 🔴 in round 2 or later, or a reviewer or seat rules the work below standard, unless the fix changes only prose. When one fires, the worker hands the hard part to a subagent one rung above its own, edits included, though the delegation rule keeps edits in the worker's thread: the escalation exists because the worker could not get them right. Each further trigger on that task climbs one more rung. Without lilleman's yes the climb stops two rungs above the rung the chunk started on: the rung its item picks, or the project's rung when no item routed it. A step-up between cycles raises the worker but not that limit: lilleman set the limit from the rung the chunk started on, so a worker that has stepped up may need a yes for its first escalation.
loop-claude's prompt names the rungs a trigger opens, so the worker computes no rung positions, and tells the worker to open each escalated subagent's prompt with `Escalation trigger <n>:`. `bin/loop_claude/routing.py` holds the limit and `bin/model_routing/route.py` the marker. The archive keeps the raw transcript, which holds the marked prompt, and `bin/routing_figures/` counts the escalations by trigger in `routing-figures.md`, per starting rung for routed chunks and in total for every chunk.
loop-claude's prompt names the rungs a trigger opens, so the worker computes no rung positions, and tells the worker to open each escalated subagent's prompt with `Escalation trigger <n>:`. `bin/agent_cycle/routing.py` holds the limit and `bin/model_routing/route.py` the marker. The archive keeps the raw transcript, which holds the marked prompt, and `bin/routing_figures/` counts the escalations by trigger in `routing-figures.md`, per starting rung for routed chunks and in total for every chunk.
Valid while the ladder orders its rungs by competence.
@@ -650,7 +650,7 @@ Valid while workers write the line when asked, and while `todo.md` on the defaul
2026-10-15, lilleman's plan, settled by the replays below. Serves goals 1.1, 1.2 and 1.4, under the ladder and steps of `routing: one ladder`.
On a model listed in `JUDGE_REPLAYED` in `bin/loop_claude/routing.py`, the judge runs on its model's highest rung, whatever the chunk's items score: on an Opus 5.5 project, Opus 5.5 at xhigh. It keeps its rung when the worker steps up. Each archived verdict names the judge's rung on a `Judge:` line.
On a model listed in `JUDGE_REPLAYED` in `bin/agent_cycle/routing.py`, the judge runs on its model's highest rung, whatever the chunk's items score: on an Opus 5.5 project, Opus 5.5 at xhigh. It keeps its rung when the worker steps up. Each archived verdict names the judge's rung on a `Judge:` line.
On 2026-10-15, `bin/judge-replay claude-opus-5-5` replayed the latest 15 archived verdicts of each kind from the Opus 5.5 projects, 39 in all. The reference judge, Opus 5.5 at the xhigh effort `settings.json` gave every judge before, reproduced 31 of them. The other 8 may rest on records or judge rules that have changed since; either way no rung is held to them. On the 31, Haiku 5.5 missed 7 at xhigh and 8 at max. That run tried each judge once. 4 of Haiku's misses, 1 at xhigh and 3 at max, misquoted the transcript, which the loop and `judge-replay` now retry; without them it missed 6 and 5. Sonnet 5.5 at high returned another kind on 3 interrupts, and Opus 5.5 at medium missed none. A missed interrupt lets the worker settle a decision that is lilleman's (goal 1.2), so the judge never runs below the project's rung.
+34
View File
@@ -2691,3 +2691,37 @@ Read most (opens and searches):
- `bin/transcript_archive/outcomes.py` 2
- `bin/judge_replay/replay.py` 1
- `bin/rung_replay/archive.py` 1
## Reading cost, chunk f6452ae1f4d1, finished 2026-11-18T15:04:37Z
164779 new input tokens before the first commit.
Read most (opens and searches):
- `README.md` 5
- `CHANGELOG.md` 2
- `bin/claude_code/reply.py` 2
- `bin/do_epic/backend/contract.py` 2
- `bin/do_epic/backend/jira.py` 2
- `bin/do_epic/backend/test_jira.py` 2
- `docs/decisions.md` 2
- `bin/atlassian/client.py` 1
- `bin/do_epic/backend/fake.py` 1
- `bin/do_epic/backend/protocol.py` 1
## Reading cost, chunk a1d1adafc713, finished 2026-11-18T15:13:10Z
257245 new input tokens before the first commit.
Read most (opens and searches):
- `docs/decisions.md` 11
- `bin/review_replay/test_review_replay.py` 9
- `bin/review_replay/replay.py` 7
- `README.md` 6
- `bin/review_replay/change_comparison.py` 5
- `bin/rule_hook/test_rule_hook.py` 4
- `bin/loop_claude/cycle/run.py` 2
- `bin/loop_claude/test_loop_claude.py` 2
- `bin/review_replay/main.py` 2
- `bin/rule_hook/main.py` 2
+20 -20
View File
@@ -83,7 +83,7 @@
### 401. Move loop-claude's cycle, judge, interrupt, tmux and routing into a package a second entry point drives, with loop-claude's behaviour unchanged.
do-epic runs on these, not on a copy (`docs/decisions.md` → `do-epic: drives one Jira epic …`). Move the reusable modules into `bin/agent_cycle/`: `tmux`, `judge`, `interrupt`, `verdicts`, `retry`, `spend`, `worker`, `states`, `stop`, and the parts of `routing` that take a `ProjectRung` and a `Route`. Keep `routed_item`, `loop/`, `project/`, `escalation_mark` and `chunk_items` in `loop_claude`. Decouple `cycle/run.py`'s archive and `Chunk items:` handling, and `cycle/prompts.py`'s goals-file and `todo.md` names, behind parameters. The places the comprehension seats found hard here, `routing.py` `unfinished_route` and `cycle/judge.py` `quotes_checked`, must read no harder after the move.
do-epic runs on these, not on a copy (`docs/decisions.md` → `do-epic: drives one Jira epic …`). Move the reusable modules into `bin/agent_cycle/`: `tmux`, `judge`, `interrupt`, `verdicts`, `retry`, `spend`, `worker`, `states`, `stop`, and the parts of `routing` that take a `ProjectRung` and a `Route`. Keep `routed_item`, `loop/`, `project/`, `chunk_items` and `cycle/prompts.py` in `loop_claude`. `escalation_mark`, `quotes`, `hand_over` and `direct_message` move too, although this item first kept `escalation_mark`: the judge, `routing` and `interrupt` import them, so keeping them would make `agent_cycle` import `loop_claude`, and a second entry point could not drive it alone. `cycle/run.py` moves as well; the archive was already behind `Cycle.project_archive`, a path the entry point hands in. Decouple `cycle/run.py`'s archive and `Chunk items:` handling, and `cycle/prompts.py`'s goals-file and `todo.md` names, behind parameters. The places the comprehension seats found hard here, `routing.py` `unfinished_route` and `cycle/judge.py` `quotes_checked`, must read no harder after the move.
Touches:
@@ -126,7 +126,7 @@ The lock that keeps do-epic and loop-claude apart is the per-project `starting`
Touches:
- `bin/loop_claude/loop/chunk_windows.py`: `starting`, `start_chunks` (small)
- `bin/loop_claude/tmux.py`: `session_name` (small)
- `bin/agent_cycle/tmux.py`: `session_name` (small)
- `bin/do-epic`
- `bin/do_epic/main.py`
- `bin/do_epic/scheduler.py`
@@ -147,7 +147,7 @@ Touches:
- `bin/loop_claude/project/records.py`: `read_records` (small)
- `bin/loop_claude/project/premises.py`: `read_premises` (small)
- `bin/loop_claude/cycle/judge.py`: `judge_prompt` (small)
- `bin/agent_cycle/judge.py`: `judge_prompt` (small)
- `bin/loop_claude/cycle/prompts.py`: `ANSWER_DESTINATIONS` (small)
- `skills/larv-review/SKILL.md`: `## 3. Passes` (small)
- `bin/do_epic/findings.py`
@@ -226,7 +226,7 @@ A plain `do-epic <key>` resumes all of them, as after a reboot (`docs/decisions.
Touches:
- `bin/loop_claude/tmux.py`: `WAITS`, `mark` (small)
- `bin/agent_cycle/tmux.py`: `WAITS`, `mark` (small)
- `bin/do_epic/status.py`
### 414. DM the human through the notifier when a human-task issue blocks the epic's next item, and poll until it closes.
@@ -235,7 +235,7 @@ do-epic leaves the issue as the team filed it (`docs/decisions.md` → `do-epic:
Touches:
- `bin/loop_claude/direct_message.py`: `tell` (small)
- `bin/agent_cycle/direct_message.py`: `tell` (small)
- `bin/do_epic/human_tasks.py`
### 417. Run do-epic end to end against a sandbox epic on a real Jira site with a command of its own, outside `run-tests`.
@@ -291,7 +291,7 @@ lilleman, 2026-11-11: do it on a timer, so an answer that comes in time doesn't
Probe first that `claude -p "/compact" --resume <id>` compacts a session: the Agent SDK documents `/compact` as a prompt, the CLI pages don't show it. Claude Code compacts idle interactive sessions itself ("Compacted while idle"), but not `-p` runs. Check: the cost entries of 20 chunks with an interrupt, before and after.
Touches:
- `bin/loop_claude/cycle/interrupt.py`: `interrupt`, `answered`, `typed_answer`, `WorkerSession`
- `bin/agent_cycle/interrupt.py`: `interrupt`, `answered`, `typed_answer`, `WorkerSession`
- `bin/loop_effects/effects.py`: `Effects`, `system_effects`
- `bin/claude_code/tokens.py`: `tokens_of` (small)
- `bin/claude_code/reply.py`: `claude_reply` (small)
@@ -310,7 +310,7 @@ Run it first as a report that kills nothing, and turn the kill on once its verdi
Touches:
- `bin/loop_claude/loop/stuck_windows.py`
- `bin/loop_claude/tmux.py`: `Listed`, `listed`
- `bin/agent_cycle/tmux.py`: `Listed`, `listed`
- `README.md`: `## Tools` (small)
### 365. Have `score-outcomes` read the finished and dropped items of a plan outside the checkout, from the project repo's history or from Jira's issue changelogs.
@@ -369,12 +369,12 @@ One of 0.13.0's history ports, per lilleman's call of 2026-11-12.
### 339. Lower the reading cost of the files a chunk reads most before its first commit.
`reading-cost` printed `Rising:` on 2026-11-12: the last 5 chunks' median is 128,199 new input tokens before their first commit, the 5 before them 101,795. Read most over the last 5, as opens and searches: `todo.md` 34, `docs/decisions.md` 26, `README.md` 19, `skills/larv-review/SKILL.md` 13, `bin/loop_claude/routing.py` 8, `CHANGELOG.md` 6. The chunk that ships this runs `reading-cost --reset`.
`reading-cost` printed `Rising:` on 2026-11-12: the last 5 chunks' median is 128,199 new input tokens before their first commit, the 5 before them 101,795. Read most over the last 5, as opens and searches: `todo.md` 34, `docs/decisions.md` 26, `README.md` 19, `skills/larv-review/SKILL.md` 13, `bin/agent_cycle/routing.py` 8, `CHANGELOG.md` 6. The chunk that ships this runs `reading-cost --reset`.
Touches:
- `README.md`
- `skills/larv-review/SKILL.md`
- `bin/loop_claude/routing.py`
- `bin/agent_cycle/routing.py`
### 341. Hand each worker's claude a lower Read limit through `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS`, kept only where replays of the archived review rounds find what two unchanged replays find.
@@ -387,7 +387,7 @@ loop-claude can hand it as it hands `CLAUDE_CODE_AUTO_COMPACT_WINDOW`, and subag
The replay: `review-replay <pass> claude-opus-5-5 --read-limit` already replays a pass's archived rounds three times as archived and once at 5,000 tokens (`bin/review_replay/changes.py`, `bin/claude_code/output_limits.py`). Run it for the prose, stability, product-owner and principles rounds. Keeps quality where each pass finds every finding the two unchanged replays both find, or misses no more than the most an unchanged replay misses, as `--omit-claude-md` counts it. Keep it only where the replays' Read characters also fall; the archived runs hold each result. Then hand the variable over in `worker_environment` for what passes.
Touches:
- `bin/loop_claude/cycle/run.py`: `worker_environment` (small)
- `bin/agent_cycle/run.py`: `worker_environment` (small)
- `bin/loop_claude/loop/usage.py`: `HELP` (small)
- `bin/loop_claude/test_loop_claude.py`: `Cycles` (small), `HelpLimits` (small)
@@ -396,7 +396,7 @@ Touches:
153 `Judge cost:` entries total $109.76, a median of about $0.76 a verdict at every rung, and the cost follows the size of the records, not the transcript: about 76k characters in log and 188k in claude-config. In 224 of 251 recent verdicts (89%) the evidence sits in the worker's final message. A missed interrupt is the costly error, so the bar is zero changed interrupts and zero new rejections across the replay. The judge is about 4.5% of dollars, so the saving is small; each cycle also gets faster.
Touches:
- `bin/loop_claude/cycle/judge.py`: `Brief`, `judge_prompt`, `JUDGE_PROMPT_CHARS`
- `bin/agent_cycle/judge.py`: `Brief`, `judge_prompt`, `JUDGE_PROMPT_CHARS`
- `bin/loop_claude/project/records.py`: `read_records`
- `bin/judge_replay/main.py`: `rule` (small)
- `bin/judge_replay/replay.py`: `case_from` (small)
@@ -415,7 +415,7 @@ One of 0.13.0's history ports, per lilleman's call of 2026-11-12.
On 2026-11-18 lilleman ruled that the classifier's miss rate of about 1 in 100 decided is close enough to no missed interrupt (`docs/decisions.md` → `routing: the offline classifier may decide finished, since lilleman ruled a miss rate of about 1 in 100 decided close enough to none; the judge's model keeps every other verdict kind`).
Taking the item builds this: before the judge call, loop-claude runs the classifier trained on its archive over the worker's final message. Where the classifier decides finished, loop-claude skips the call. The classifier is re-trained as the archive grows. The judge call sits in `bin/loop_claude/cycle/run.py` → `rule`, a place the comprehension seats found hard, since the order of stamping, archiving and stepping matters across three functions: make it easier to read.
Taking the item builds this: before the judge call, loop-claude runs the classifier trained on its archive over the worker's final message. Where the classifier decides finished, loop-claude skips the call. The classifier is re-trained as the archive grows. The judge call sits in `bin/agent_cycle/run.py` → `rule`, a place the comprehension seats found hard, since the order of stamping, archiving and stepping matters across three functions: make it easier to read.
The judge's model still decides every verdict the classifier leaves, the escalation a worker quotes, and whether a release is ready to cut, since the replay didn't test the classifier on those.
@@ -472,7 +472,7 @@ The prose pass's replay under item 318's new bar, on 2026-11-12, qualified no ru
On 2026-11-08 the human answered notice only: the loop prints that the release is ready to cut and ends; no interrupt, and nothing waits in loop-inbox.
Releases are the human's, and `CLAUDE.md` → "Working loop" already ends the loop once a release is ready to cut, so the ask settles nothing. 15 interrupts in the archive ask whether the human will cut a release, and about 6 of the 45 interrupts from 2026-11-02 to 2026-11-10 said a release was ready to cut; log's 2.5.0 was asked twice within an hour on 2026-11-10. On 2026-11-08 one of the 4 questions waiting in `~/.local/state/loop-claude/` is such an ask, plainpages-plugin-fastjira's 0.3.0 since 2026-11-03. Today a release ready to cut opens claude's session at once (`bin/loop_claude/cycle/run.py` `ask`), and the loop stops if the human leaves it with nothing typed. The change also touches what an interrupt covers in `CLAUDE.md` → "Vocabulary". Where the change touches `ask`, make it easier to read, as the seats named it.
Releases are the human's, and `CLAUDE.md` → "Working loop" already ends the loop once a release is ready to cut, so the ask settles nothing. 15 interrupts in the archive ask whether the human will cut a release, and about 6 of the 45 interrupts from 2026-11-02 to 2026-11-10 said a release was ready to cut; log's 2.5.0 was asked twice within an hour on 2026-11-10. On 2026-11-08 one of the 4 questions waiting in `~/.local/state/loop-claude/` is such an ask, plainpages-plugin-fastjira's 0.3.0 since 2026-11-03. Today a release ready to cut opens claude's session at once (`bin/agent_cycle/run.py` `ask`), and the loop stops if the human leaves it with nothing typed. The change also touches what an interrupt covers in `CLAUDE.md` → "Vocabulary". Where the change touches `ask`, make it easier to read, as the seats named it.
### 171. Group the routing figures' review rounds by the reviewers' rung as well as the worker's, so a call blames a rung only for rounds its own reviews raised.
@@ -487,16 +487,16 @@ Aim: one ambitious refactor of the areas below, sized so every mean reaches 7.0
Places the seats named, hardest first (`larv-review places`), Locality first:
- Locality, Self-sufficiency: `bin/release_plan/release_standing.py:176` `next_release`, with `:162` `carried`: the cut from a tag, a dated heading or `BEFORE_FIRST_RELEASE`, release names replayed from the plan's history, and renames meet in the `is_earliest` test at `:198`; `carried` is reapplied in `chunk_item` and in `chunk_preflight/choices.py` `planned`, one relying on `zip` keeping order. All eight seats named it; four would least want to change it.
- Locality: `bin/loop_claude/routing.py:116` `unfinished_route`, with `:131` `escalated_route`: five rungs, the unfinished count and the escalation mark, which spans `escalation_mark.py`, `judge.py`, `verdicts.py`, `route.py` and `reload.py`. Seven seats named it; the module table is what makes it readable.
- Locality: `bin/agent_cycle/routing.py:116` `unfinished_route`, with `:131` `escalated_route`: five rungs, the unfinished count and the escalation mark, which spans `escalation_mark.py`, `judge.py`, `verdicts.py`, `route.py` and `reload.py`. Seven seats named it; the module table is what makes it readable.
- Locality: `bin/chunk_pr/main.py:298` `merged`, with `:384` `levelled_and_finished` and `:407` `finished`: a loop around the queue turn binds `done` only under some `if ready` branches, the approval wait is a fall-through, and `finished` destructures five subprocess results by position.
- Locality: `skills/larv-review/SKILL.md:82` "Round cap" and `:90` "Re-entry", with `bin/review_rules/round_titles.py:45` and `:63` `past_cap`, `bin/rule_hook/round_cap.py:10` and `bin/larv_review/reviewer_header.py:73`: the round cap lives in five places, and SKILL.md's Done, Cap, Re-entry and Mechanical answers point at each other as prose.
- Locality: `bin/loop_claude/loop/chunk_windows.py:107` `start_chunks`: under one flock it checks the session's owner, splits running from stopped windows, computes the room, reads the plan with a fallback, gathers held items and filters again, with the limit applied a second time in `may_start`.
- Shape, Locality: `bin/release_plan/ranking.py:239` `score`, `:144` `weigh` and `:250` `weight_of`: every function forks on `SHAPE` versus `OLD_SHAPE`, and one Score depends on five inputs held in other files.
- Locality, Shape: `bin/plan_store/stores.py:1` and `bin/release_plan/todo_table.py:1`: `release_plan` and `plan_store` import each other, the plan has three names, and the goals file sits under `release_plan`.
- Shape: `bin/larv_review/plan.py:22` `scoring_run_due`, with `owed.py`, `unmeasured.py` and `scoring.py`: the scoring-run trigger is spread over four modules, three of whose names don't say it, in a flat 14-module package that mixes rounds, the comprehension check and its triggers.
- Self-sufficiency: `bin/loop_claude/cycle/judge.py:22` `INTERRUPT_RULES`, with `:197` `quotes_checked`: the judge's behaviour is held partly in prompt text and field metadata and partly in Python checks.
- Self-sufficiency: `bin/agent_cycle/judge.py:22` `INTERRUPT_RULES`, with `:197` `quotes_checked`: the judge's behaviour is held partly in prompt text and field metadata and partly in Python checks.
- Shape: `bin/plan_store/jira_epic.py:356` `revision_of`: indexes the untyped tuple `scores` at `:530` returns by position.
- Shape: `bin/loop_claude/cycle/run.py:55` `Cycle.todo`, `bin/loop_claude/hand_over.py:23` `hand_over` and `bin/release_plan/named_code.py:5`: names that say todo.md where the plan may be a Jira epic, a handover that is not the reload's, and a module with no code in it.
- Shape: `bin/agent_cycle/run.py:55` `Cycle.todo`, `bin/agent_cycle/hand_over.py:23` `hand_over` and `bin/release_plan/named_code.py:5`: names that say todo.md where the plan may be a Jira epic, a handover that is not the reload's, and a module with no code in it.
- Navigation, Shape: `README.md:197` the `bin/` package list: 74 entries at one level, with the README's list as the only index.
- Self-sufficiency: every seat names the decision-log titles that code cites for a reason (`routing.py:1`, `ranking.py:20`, `loop/routing_check.py:1`) as a cost; state each reason beside its constant and keep the citation as a footnote.
@@ -597,7 +597,7 @@ Start once 20 chunks have run under the rule. The rule is `READING_RULE` in `bin
### 51. Hand loop-claude's terminal output to an injected effect, so no storage or retry function prints.
"Functional core, imperative shell", in `principles/technical-principles.md`: `say` in `bin/loop_effects/effects.py` takes the effects but prints to stderr itself, and `retried` and the rest print through `say`. Two bare `print(file=sys.stderr)` calls remain outside them, in `bin/loop_claude/cycle/interrupt.py` and `bin/loop_claude/project/model_choice.py`. The tests swap the global stream.
"Functional core, imperative shell", in `principles/technical-principles.md`: `say` in `bin/loop_effects/effects.py` takes the effects but prints to stderr itself, and `retried` and the rest print through `say`. Two bare `print(file=sys.stderr)` calls remain outside them, in `bin/agent_cycle/interrupt.py` and `bin/loop_claude/project/model_choice.py`. The tests swap the global stream.
### 201. Save the human's tmux setups and restore them after a reboot, so work is up and running again quickly.
@@ -613,7 +613,7 @@ Weigh the widely used tmux-resurrect and tmux-continuum plugins against a script
### 267. Keep waiting when an interrupt gets an empty answer, at the terminal or in the claude opened for it, in place of stopping the loop.
11 runs in the archive ended with "Stopped: the human is needed to answer the question above, but the interrupt ended without anything typed", each leaving its chunk open until the human restarted the loop. That stop comes from `human_typed` in `bin/loop_claude/cycle/interrupt.py`, after the claude opened for `/talk` or for a release ready to cut ends with no human turn. An empty line at the terminal stops the loop the same way, in `typed_answer`. Item 268 removes one of the cases that opens claude.
11 runs in the archive ended with "Stopped: the human is needed to answer the question above, but the interrupt ended without anything typed", each leaving its chunk open until the human restarted the loop. That stop comes from `human_typed` in `bin/agent_cycle/interrupt.py`, after the claude opened for `/talk` or for a release ready to cut ends with no human turn. An empty line at the terminal stops the loop the same way, in `typed_answer`. Item 268 removes one of the cases that opens claude.
### 4. Name each chunk's archive folder by the chunk's start time, so `<key>/` lists chunks in the order they ran.
@@ -645,7 +645,7 @@ Found by review of PR #317. The black-box test, `bin/loop_claude/test_black_box.
### 265. Archive each wait that costs a chunk wall time, for a usage limit, low memory, a failed worker start or a heavy slot, with its start and end stamps, so goal 1.5's hours split waiting from work.
No record holds these waits today. An outcomes file holds verdicts, stops, step-ups and the judge's cost (`bin/transcript_archive/outcomes.py`), and `~/.local/state/run-heavy/` holds only the slots' lock files. loop-claude waits out a usage limit and low memory in `bin/loop_claude/cycle/retry.py`; run-heavy waits for a slot in `bin/run_heavy/`. A heavy slot's wait happens inside a worker's Bash call, so loop-claude doesn't see it; run-heavy would write it where the archive can find it.
No record holds these waits today. An outcomes file holds verdicts, stops, step-ups and the judge's cost (`bin/transcript_archive/outcomes.py`), and `~/.local/state/run-heavy/` holds only the slots' lock files. loop-claude waits out a usage limit and low memory in `bin/agent_cycle/retry.py`; run-heavy waits for a slot in `bin/run_heavy/`. A heavy slot's wait happens inside a worker's Bash call, so loop-claude doesn't see it; run-heavy would write it where the archive can find it.
### 169. Have rule-hook's `todo-rank-check` catch a `todo.md` that the same Bash call edits and then commits.
@@ -653,7 +653,7 @@ The hook judges a call before it runs, and `changed` in `bin/rule_hook/todo_chec
### 197. Let the human edit what they type at loop-claude's terminal questions with the arrow keys, so Left moves the cursor in place of printing `^[[D`.
`bin/loop_effects/effects.py` hands loop-claude Python's builtin `input`, and nothing under `bin/` imports `readline`, so the terminal gets no line editing: fixing a typo means erasing back to it. loop-claude asks two questions at its terminal. Both read through `effects.input`: the pick of the project's model, in `project/model_choice.py`'s `ask_for_model`, and the interrupt's answer, in `cycle/interrupt.py`'s `typed_answer`. Importing `readline` in `effects.py` gives `input` line editing, at two costs. It moves the prompt from stderr to stdout, while the question above it stays on stderr. `test_black_box.py` waits for the prompt on stderr. `readline`'s bracketed paste takes a pasted block whole, so an answer can hold several lines. `prompts.typed_answer` ends the answer at its first blank line, so the judge would read the rest of such a paste as loop-claude's words. The product-owner review of PR #308 raised the interrupt's case. lilleman, 2026-10-18: "Not super-important, but a bit irritating."
`bin/loop_effects/effects.py` hands loop-claude Python's builtin `input`, and nothing under `bin/` imports `readline`, so the terminal gets no line editing: fixing a typo means erasing back to it. loop-claude asks two questions at its terminal. Both read through `effects.input`: the pick of the project's model, in `project/model_choice.py`'s `ask_for_model`, and the interrupt's answer, in `agent_cycle/interrupt.py`'s `typed_answer`. Importing `readline` in `effects.py` gives `input` line editing, at two costs. It moves the prompt from stderr to stdout, while the question above it stays on stderr. `test_black_box.py` waits for the prompt on stderr. `readline`'s bracketed paste takes a pasted block whole, so an answer can hold several lines. `prompts.typed_answer` ends the answer at its first blank line, so the judge would read the rest of such a paste as loop-claude's words. The product-owner review of PR #308 raised the interrupt's case. lilleman, 2026-10-18: "Not super-important, but a bit irritating."
### 1. Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.