Run do-epic <EPIC-KEY>: a tmux window per chunk, under the epic's cap and each repo's parallel-chunks, never beside loop-claude

This commit is contained in:
2026-11-18 20:49:12 +01:00
parent c4d06c55b5
commit 38e39c93d1
17 changed files with 961 additions and 67 deletions
+17 -2
View File
@@ -28,10 +28,10 @@ Each verdict then moves the rung by one rule, and the rung never falls. The rung
| interrupt or quoted answer without one | holds | holds | holds |
"""
import dataclasses
import typing
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 model_routing.route import Route
@@ -42,7 +42,22 @@ ESCALATION_CAP = 2
JUDGE_REPLAYED = ("claude-opus-5-5",)
def first_route(project: ProjectRung, item: Item | None) -> Route:
class Scored(typing.Protocol):
"""What routes a chunk: a plan item under loop-claude, an epic's issue under do-epic."""
@property
def id(self) -> int:
"""The number a Route keeps as its item."""
@property
def likelihood(self) -> int:
"""Its L."""
@property
def escape_and_impact(self) -> int:
"""Its E + I."""
def first_route(project: ProjectRung, item: Scored | 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:
return Route(project.rung)
+35 -5
View File
@@ -19,6 +19,8 @@ LOOP = "loop"
EPIC = "epic"
# The session option that names the checkout whose chunks the session runs, since two checkouts' keys may map to one session name.
OWNER = "@loop-root"
# The window option that names the folder a window's chunk works in, so that loop-claude and do-epic each see the chunks the other runs in a checkout.
ROOT = "@chunk-root"
@dataclasses.dataclass(frozen=True)
@@ -47,6 +49,15 @@ class Listed:
dead: bool
@dataclasses.dataclass(frozen=True)
class Placed:
"""A window of any session, as tmux lists it."""
session: str
window: Listed
# The folder its chunk works in, as ROOT names it; empty for a window started before ROOT was set.
root: str
def unusable(run: Tmux, driver: str) -> str | None:
"""Why driver, the entry point, cannot use this machine's tmux, naming the version found and the one needed; None where it is NEEDED or later."""
found = run(["-V"]).stdout.strip()
@@ -68,8 +79,15 @@ def listed(session: str, run: Tmux) -> list[Listed]:
return [Listed(row[0].removesuffix(WAITS), row[2], row[1] == "1") for row in rows if len(row) == 3]
def start_window(window: Window, cwd: str, env: typing.Mapping[str, str], command: list[str], first: bool, run: Tmux) -> Failure | None:
"""Starts command in a new window of window's session, in cwd with env added to its environment, and leaves the client where it is. first makes the session too. A Failure says why tmux started none, or why it could not mark a session it made as this checkout's."""
def everywhere(run: Tmux) -> list[Placed]:
"""The windows of every session; none where no tmux server runs."""
done = run(["list-windows", "-a", "-F", f"#{{session_name}}\t#{{window_name}}\t#{{pane_dead}}\t#{{window_id}}\t#{{{ROOT}}}"])
rows = [line.split("\t") for line in done.stdout.splitlines()] if done.returncode == 0 else []
return [Placed(row[0], Listed(row[1].removesuffix(WAITS), row[3], row[2] == "1"), row[4]) for row in rows if len(row) == 5]
def start_window(window: Window, cwd: str, env: typing.Mapping[str, str], command: list[str], first: bool, owned: bool, run: Tmux) -> Failure | None:
"""Starts command in a new window of window's session, in cwd with env added to its environment, and leaves the client where it is. first makes the session too, and owned marks a session it makes as running the chunks of the checkout cwd. A Failure says why tmux started none, or why it could not mark the session."""
make = ["new-session", "-d", "-s", window.session] if first else ["new-window", "-d", "-t", f"={window.session}:"]
variables = [flag for name, value in env.items() for flag in ("-e", f"{name}={value}")]
# tmux reads a `;` that ends an argument as the end of the command, unless a backslash precedes it.
@@ -78,15 +96,27 @@ def start_window(window: Window, cwd: str, env: typing.Mapping[str, str], comman
if done.returncode:
return Failure(f"tmux could not start the window {window.target}: {done.stderr.strip() or f'it exited {done.returncode}'}")
# set-option and show-options read a target as a pane's, so `=session` alone names no session.
owned = run(["set-option", "-t", f"={window.session}:", OWNER, cwd]) if first else None
marked = run(["set-option", "-t", f"={window.session}:", OWNER, cwd]) if first and owned else None
# A failure leaves the window unseen by the other entry point, which then may start a chunk beside it; the window still runs.
run(["set-option", "-w", "-t", done.stdout.strip(), ROOT, cwd])
# By the ID, since a window of the same name may still be closing. A failed remain-on-exit doesn't matter: a loop that fails before it is set closes its window, and its stop is still sent as a DM.
run(["set-option", "-w", "-t", done.stdout.strip(), "remain-on-exit", "failed"])
# Without the owner, start_chunks cannot tell this checkout's session from another's, so no further chunk may start in it.
if owned is not None and owned.returncode:
return Failure(f"tmux started the session {window.session} but could not mark it as this checkout's: {owned.stderr.strip() or f'it exited {owned.returncode}'}")
if marked is not None and marked.returncode:
return Failure(f"tmux started the session {window.session} but could not mark it as this checkout's: {marked.stderr.strip() or f'it exited {marked.returncode}'}")
return None
def start_chunk(window: Window, cwd: str, env: typing.Mapping[str, str], command: list[str], windows: list[Listed], owned: bool, run: Tmux) -> list[Listed] | Failure:
"""Starts a chunk's command in window, in place of each dead window of its name among windows, the session's; the session's windows afterwards, or why tmux started none. start_window says what cwd, env and owned do."""
stale = [listed for listed in windows if listed.name == window.name and listed.dead]
for listed in stale:
close(listed, run)
kept = [listed for listed in windows if listed not in stale]
failed = start_window(window, cwd, env, command, not kept, owned, run)
return failed or [*kept, Listed(window.name, "", False)]
def owner(session: str, run: Tmux) -> str:
"""The checkout whose chunks session runs, as OWNER names it; empty where it names none."""
return run(["show-options", "-qv", "-t", f"={session}:", OWNER]).stdout.strip()
+25
View File
@@ -0,0 +1,25 @@
"""What a do-epic cycle's worker is told: its task, from the issue, and its first prompt. The resumed prompt and the rung sentences are the ones loop-claude's cycles use, naming do-epic."""
from do_epic.backend.protocol import EpicIssue
from loop_claude.cycle import prompts
from model_routing.ladder import ProjectRung
from model_routing.route import Route
# The entry point's name as the worker, the judge and the human read it.
DRIVER = "do-epic"
def task(issue: EpicIssue, epic: str, checkout: str | None) -> str:
"""The task of the chunk that works issue, of the epic with the key epic: in checkout, or without a repo where it is None."""
where = f"in the checkout {checkout}, on the branch {issue.key}" if checkout else "which changes no repo: work in the folder you start in"
return f"Work the Jira issue {issue.key} of the epic {epic} as one chunk, {where}. Its summary: {issue.summary}" + (f"\n\nIts description:\n\n{issue.detail}" if issue.detail else "")
def fresh(task: str, premises: str, route: Route, project: ProjectRung | None, facts: str) -> str:
"""A chunk's first prompt. facts is empty: do-epic runs no preflight."""
routed = f"{DRIVER} runs you on {route.rung}, routed by the issue's L of {route.likelihood}. Where a sentence below names item {route.item}, it means the issue." if route.item else ""
opening = " ".join(filter(None, [routed, *prompts.rung_sentences(DRIVER, route, project)]))
return f"{task}\n\nContinue any open draft PR or worktree for the chunk before creating a new one. {prompts.READING_RULE}\n\n{opening and f'{opening}{chr(10)}{chr(10)}'}The issue sets the chunk's scope. The goals below choose between ways to deliver that scope, and never widen it: the epic's first, then code health (~/.claude/CLAUDE.md → \"Shared goal\"), then the repo's.\n\nFrom {premises}"
# The worker names no plan items: the chunk's one item is its issue.
WORKER = prompts.worker_prompts(DRIVER, fresh, "")
+19 -1
View File
@@ -1,6 +1,6 @@
"""A Jira epic's description as the record of do-epic, the tool that will drive one epic.
The description holds a language line and the sections Goals, Audience, Scoring (the formula and the bar) and Decisions. They are read and written one at a time through `EpicDescription`, and a write leaves every other line of the markdown as it was. Goals and Audience change only where the human approved in an interrupt, which `write_section` takes as `approved`; `EpicDescription` refuses the change otherwise."""
The description holds a language line, a line that caps the chunks running at once, and the sections Goals, Audience, Scoring (the formula and the bar) and Decisions. They are read and written one at a time through `EpicDescription`, and a write leaves every other line of the markdown as it was. Goals and Audience change only where the human approved in an interrupt, which `write_section` takes as `approved`; `EpicDescription` refuses the change otherwise."""
import dataclasses
import re
import typing
@@ -13,6 +13,9 @@ from project_config.settings import language_fault
SECTIONS = ("Goals", "Audience", "Scoring", "Decisions")
LANGUAGE_LINE = re.compile(r"^\*\*Language:\*\* (.*?)\s*$")
# The line that caps how many of the epic's chunks run at once. Three readers, seated as the human who writes an epic's description, picked this spelling from four candidates, 2-1 over `**Parallel chunks:**`, which reads as a count of what runs now.
CAP = "**Max parallel chunks:**"
CAP_LINE = re.compile(rf"^{re.escape(CAP)}(.*?)\s*$")
def read_section(text: str, name: str) -> str | Failure:
@@ -59,6 +62,17 @@ def language_in(text: str) -> str | None:
return None
def parallel_chunks_in(text: str) -> int | Failure:
"""How many of the epic's chunks may run at once, as the description's CAP line says; 1 where it has none, as a project's `parallel-chunks` is where its config leaves it out."""
for line, fenced in fenced_lines(text):
if not fenced and (found := CAP_LINE.match(line)):
value = found.group(1).strip()
if re.fullmatch(r"[1-9][0-9]*", value):
return int(value)
return Failure(f"the epic's description caps its chunks with `{CAP} {value}`, which is not a whole number of 1 or more, such as `{CAP} 2`")
return 1
def with_language(text: str, language: str) -> str | Failure:
"""text with its language line naming language, put first where there is none."""
if fault := language_fault(language):
@@ -84,6 +98,10 @@ class EpicRecord:
text = self.description.read()
return text if isinstance(text, Failure) else language_in(text)
def parallel_chunks(self) -> int | Failure:
text = self.description.read()
return text if isinstance(text, Failure) else parallel_chunks_in(text)
def write_section(self, name: str, body: str, approved: bool = False) -> Held | Failure:
"""Writes body as the ## name section. approved says the human approved the change in an interrupt, which Goals and Audience need."""
return self.written(lambda text: with_section(text, name, body), frozenset({name}) if approved else frozenset())
+270
View File
@@ -0,0 +1,270 @@
"""The do-epic command (docs/decisions.md → `do-epic: drives one Jira epic …`).
`do-epic <EPIC-KEY>` starts each of the epic's chunks that may start now, each in a window of the epic's tmux session, as `scheduler` picks them, and puts that session on the terminal. Each window runs `do-epic --chunk <ISSUE-KEY> <EPIC-KEY>`: the cycles of one issue's chunk, which loop-claude's cycles share (`agent_cycle`), until the judge rules it finished. Then it starts the chunks that may start now, and its window closes."""
import dataclasses
import pathlib
import typing
from agent_cycle import tmux
from agent_cycle.direct_message import tell
from agent_cycle.routing import judge_rung
from agent_cycle.run import Cycle, run_cycle
from agent_cycle.stop import Stop
from agent_cycle.verdicts import Finished, TakenIn
from claude_code.session import session_named
from do_epic import chunk_prompt, scheduler
from do_epic.backend.jira import JiraEpic
from do_epic.backend.protocol import EpicIssue, EpicStore
from do_epic.config import DoEpicConfig, load
from do_epic.epic_record import EpicRecord
from do_epic.repo_pick import recorded, Repo
from do_epic.repos import locate
from failure import Failure
from loop_claude.loop.chunk_start import archived_route, routed
from loop_claude.loop.close import closed_cycle
from loop_claude.loop.main import setup_version
from loop_claude.loop.reload import LoopRun
from loop_claude.loop.this_loop import Loop
from loop_claude.project.model_choice import get_or_ask_models, Models
from loop_claude.project.premises import read_premises
from loop_claude.project.records import read_records
from loop_effects.effects import Effects, say
from loop_state.paths import Paths
from model_routing.ladder_file import project_ladder_file, read_ladder, SHIPPED
from plan_store.jira_epic import ISSUE_KEY
from project_config.settings import Epic
from record_store.jira_description import EpicDescription
from transcript_archive.project_key import project_key
HELP = f"""usage: do-epic <EPIC-KEY>
Runs the chunks of one Jira epic, such as ABC-12, each in its own window of the tmux session epic-<EPIC-KEY>.
An open issue of the epic is a chunk once a label names its repo, or names it work without a repo, and nothing blocks it.
As many run at once as the epic's description allows with a line such as `**Max parallel chunks:** 2`, one where it has none.
A repo takes as many chunks as its `parallel-chunks`, and none while loop-claude runs chunks in it.
The Jira site and its credentials are set in ~/.claude-projects/do-epic/config.toml."""
# Under the home folder, where a chunk's cycles are archived, a folder per epic. Apart from loop-claude's archive, whose readers, such as judge-replay and the routing figures, read loop-claude's prompts.
ARCHIVE = ".claude/do-epic-transcripts"
# The store of an epic's issues and its record, for the epic with this key.
Backend = typing.Callable[[DoEpicConfig, str], tuple[EpicStore, EpicRecord]]
def jira_backend(config: DoEpicConfig, key: str) -> tuple[EpicStore, EpicRecord]:
epic = Epic(config.jira_url, key)
return JiraEpic(epic, config.env_file), EpicRecord(EpicDescription(epic, config.env_file))
@dataclasses.dataclass(frozen=True)
class EpicRun:
"""What stays the same through one run of do-epic on an epic."""
key: str
config: DoEpicConfig
store: EpicStore
record: EpicRecord
paths: Paths
env: typing.Mapping[str, str]
launcher: pathlib.Path
effects: Effects
@property
def session(self) -> str:
return tmux.session_name(tmux.EPIC, self.key)
def main(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher: pathlib.Path, effects: Effects, backend: Backend = jira_backend) -> int:
try:
stop = run(argv, env, paths, launcher, effects, backend)
except KeyboardInterrupt:
stop = Stop(130, "")
except Exception as crash:
tell(f"do-epic {' '.join(argv)} crashed: {crash!r}", effects)
raise
if stop.reason:
say(stop.reason, effects, stdout=not stop.code)
# A chunk's stop is DMed, as loop-claude's is, so a chunk left overnight never ends unseen.
if stop.reason and argv[:1] == [scheduler.CHUNK_FLAG]:
tell(f"do-epic {' '.join(argv)} stopped: {stop.reason}", effects)
return stop.code
def run(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher: pathlib.Path, effects: Effects, backend: Backend) -> Stop:
chunk, words = (argv[1], argv[2:]) if len(argv) >= 2 and argv[0] == scheduler.CHUNK_FLAG else (None, argv)
if len(words) != 1 or not ISSUE_KEY.fullmatch(words[0]) or (chunk is not None and not ISSUE_KEY.fullmatch(chunk)):
return Stop(0 if words in (["-h"], ["--help"]) else 1, HELP)
# Before anything starts: a clone, a claude session or a tmux window.
if reason := tmux.unusable(effects.tmux, chunk_prompt.DRIVER):
return Stop(1, reason)
config = load(paths.home)
if isinstance(config, Failure):
return Stop(1, config.reason)
store, record = backend(config, words[0])
epic = EpicRun(words[0], config, store, record, paths, env, launcher, effects)
return windows_opened(epic) if chunk is None else chunk_run(chunk, epic)
def windows_opened(epic: EpicRun) -> Stop:
"""What the do-epic the human runs does: starts each chunk that may start now, says why each other open issue waits, then puts the epic's session on the terminal until the human detaches."""
started = chunks_started(epic, None)
if isinstance(started, Failure):
return Stop(1, started.reason)
say(f"started {', '.join(started.started)} in the tmux session {epic.session}" if started.started else f"started no chunk in the tmux session {epic.session}", epic.effects, stdout=True)
for wait in started.waits:
say(f"{wait.issue} waits: {wait.reason}", epic.effects, stdout=True)
if not tmux.listed(epic.session, epic.effects.tmux):
return Stop(0, "")
if not epic.effects.on_terminal():
say(f"not on a terminal; see the chunks with `tmux attach -t ={epic.session}`", epic.effects, stdout=True)
return Stop(0, "")
shown = tmux.show(epic.session, "TMUX" in epic.env)
return Stop(1, f"`tmux {' '.join(shown)}` failed; the chunks go on in the tmux session") if epic.effects.tmux_on_terminal(shown) else Stop(0, "")
def chunks_started(epic: EpicRun, own: str | None) -> scheduler.Started | Failure:
"""scheduler.start_chunks on the epic's issues and cap, read afresh; own is the issue of the chunk that asks."""
issues = epic.store.read()
if isinstance(issues, Failure):
return issues
cap = epic.record.parallel_chunks()
if isinstance(cap, Failure):
return cap
# The checkouts located so far, from whose remotes repos.locate tells where to clone a repo that is missing.
seen: list[pathlib.Path] = []
def located(name: str) -> tuple[pathlib.Path, int] | Failure:
found = locate(name, [checkout for checkout in seen], epic.config, epic.paths.home, epic.effects.git)
if isinstance(found, Failure):
return found
seen.append(found.checkout)
return found.checkout, found.config.parallel_chunks
return scheduler.start_chunks(scheduler.Epic(epic.key, cap, located, epic.paths.home, epic.launcher, epic.env), issues, own, epic.effects.tmux)
@dataclasses.dataclass(frozen=True)
class RoutingIssue:
"""An issue as what routes its chunk (agent_cycle.routing.Scored)."""
issue: EpicIssue
@property
def id(self) -> int:
"""The number in the issue's key. A Route keeps a number, and one chunk's archive holds one issue, so the project's letters aren't needed to tell it."""
return int(self.issue.key.rpartition("-")[2])
@property
def likelihood(self) -> int:
return self.issue.scores["L"]
@property
def escape_and_impact(self) -> int:
return self.issue.scores.get("E", 0) + self.issue.scores.get("I", 0)
def chunk_run(key: str, epic: EpicRun) -> Stop:
"""Runs the cycles of the chunk of the issue called key until one stops the loop, or the judge rules the chunk finished."""
pane = epic.env.get("TMUX_PANE")
if not pane:
return Stop(1, f"{scheduler.CHUNK_FLAG} is how do-epic starts itself in a tmux window; run do-epic <EPIC-KEY>")
issue = issue_read(key, epic)
if isinstance(issue, Stop):
return issue
root = chunk_root(issue, epic)
if isinstance(root, Stop):
return root
session = session_named(f"A {epic.key} do-epic {key}", epic.paths.claude_code_transcripts)
loop = Loop(root=root, session=session, window=tmux.Window(epic.session, key, pane), paths=epic.paths, env=epic.env, launcher=epic.launcher, effects=epic.effects)
loop_run = LoopRun(0, root, "", "", chunk=key)
while True:
loop_run = dataclasses.replace(loop_run, cycle_number=loop_run.cycle_number + 1)
cycle = next_cycle(loop_run, loop, epic)
if isinstance(cycle, Stop):
return cycle
loop_run = dataclasses.replace(loop_run, task=cycle.task)
concluded = run_cycle(cycle)
if isinstance(concluded, Stop):
return concluded
closed = closed_cycle(loop_run, cycle.project, concluded, cycle.project_archive, chunk_prompt.DRIVER, loop)
if isinstance(closed, Stop):
return closed
loop_run = closed
if isinstance(concluded.verdict, Finished):
return handed_on(key, epic)
def issue_read(key: str, epic: EpicRun) -> EpicIssue | Stop:
"""The epic's issue called key, read afresh."""
issues = epic.store.read()
if isinstance(issues, Failure):
return Stop(1, issues.reason)
found = [issue for issue in issues if issue.key == key]
return found[0] if found else Stop(1, f"{key} is no issue of the epic {epic.key}")
def chunk_root(issue: EpicIssue, epic: EpicRun) -> str | Stop:
"""The folder the issue's chunk works in: its repo's checkout, or the epic's folder for work without a repo."""
pick = recorded(issue)
if isinstance(pick, Failure):
return Stop(1, pick.reason)
if not isinstance(pick, Repo):
folder = epic.paths.home / scheduler.STATE / epic.key
folder.mkdir(parents=True, exist_ok=True)
return str(folder)
found = locate(pick.name, [], epic.config, epic.paths.home, epic.effects.git)
return Stop(1, found.reason) if isinstance(found, Failure) else str(found.checkout)
def handed_on(key: str, epic: EpicRun) -> Stop:
"""The stop of a do-epic whose chunk finished, once it has started each chunk that may start now. Its window closes as it exits."""
started = chunks_started(epic, key)
if isinstance(started, Failure):
return Stop(1, f"the chunk finished, but the next could not start: {started.reason}")
say(f"the chunk finished; started {', '.join(started.started) or 'no other'}", epic.effects, stdout=True)
return Stop(0, "")
def next_cycle(loop_run: LoopRun, loop: Loop, epic: EpicRun) -> Cycle | Stop:
"""The cycle loop_run runs next, from the issue, the premises, the records, the models and the routing ladder read afresh; the stop where one of them cannot be read. A chunk in a repo routes on that repo's model and ladder, and one without a repo on the machine setting's model, `repoless-model`, and the shipped ladder."""
issue = issue_read(loop.window.name, epic)
if isinstance(issue, Stop):
return issue
in_repo = isinstance(recorded(issue), Repo)
premises = premises_read(loop.root if in_repo else None, epic)
if isinstance(premises, Failure):
return Stop(1, premises.reason)
# The epic's records join the repo's with todo.md item 413; until then a chunk without a repo has none.
records = read_records(loop.root, epic.paths.home, epic.paths.claude_dir) if in_repo else ""
if isinstance(records, Failure):
return Stop(1, records.reason)
models = get_or_ask_models(project_key(loop.root, epic.paths.home), epic.paths, epic.env, chunk_prompt.DRIVER, epic.effects) if in_repo else repoless_models(epic)
if isinstance(models, Stop):
return models
ladder_file = project_ladder_file(loop.root, epic.paths.home) if in_repo else SHIPPED
if isinstance(ladder_file, Failure):
return Stop(1, ladder_file.reason)
ladder = read_ladder(ladder_file)
if isinstance(ladder, Failure):
return Stop(1, ladder.reason)
archive_folder = epic.paths.home / ARCHIVE / epic.key
project = ladder.project_rung(models.worker)
route = routed(loop_run.route, project, models.worker, lambda: archived_route(archive_folder, loop), lambda: RoutingIssue(issue) if "L" in issue.scores else None)
say(f"\n=== cycle {loop_run.cycle_number}, worker on {route.rung} ===", epic.effects, stdout=True)
return Cycle(config=setup_version(epic.paths.claude_dir, epic.effects.git), effects=epic.effects, 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=chunk_prompt.task(issue, epic.key, loop.root if in_repo else None), prompts=chunk_prompt.WORKER, taken_in=lambda entries: TakenIn(), unfinished_evidence=loop_run.unfinished_evidence, window=loop.window)
def repoless_models(epic: EpicRun) -> Models:
"""The models of a chunk without a repo: `repoless-model`, unless the environment names another for the run, as it may for loop-claude."""
return Models(epic.env.get("LOOP_CLAUDE_JUDGE_MODEL") or epic.config.repoless_model, epic.env.get("LOOP_CLAUDE_WORKER_MODEL") or epic.config.repoless_model)
def premises_read(root: str | None, epic: EpicRun) -> str | Failure:
"""The epic's Goals and Audience, from its description, then those of the repo checked out at root, where the chunk has one."""
bodies: list[str] = []
for name in ("Goals", "Audience"):
body = epic.record.section(name)
if isinstance(body, Failure):
return Failure(f"the epic {epic.key}'s description: {body.reason} - no premises.")
bodies.append(body)
theirs = read_premises(root, epic.paths.home) if root else ""
if isinstance(theirs, Failure):
return theirs
return f"the epic {epic.key}'s description:\n## Goals\n{bodies[0]}\n\n## Audience\n{bodies[1]}" + (f"\n\nThe repo's goals, which rank after the epic's and after code health, are from {theirs}" if theirs else "")
+161
View File
@@ -0,0 +1,161 @@
"""Which of an epic's issues run as chunks now, each in its own window of the epic's tmux session (docs/decisions.md → `do-epic: drives one Jira epic …`).
Three limits hold a chunk back: the epic's cap of chunks at once, its repo's `parallel-chunks`, counted across every epic, and a loop-claude that runs chunks in its repo. do-epic checks a repo and starts a chunk in it while holding the lock loop-claude holds when it starts one (`chunk_windows.starting`), so the two never start chunks in one checkout together."""
import dataclasses
import pathlib
import typing
from agent_cycle import tmux
from do_epic.backend.protocol import EpicIssue
from do_epic.epic_record import CAP
from do_epic.repo_pick import HumanTask, recorded, Repo
from do_epic.split import SPLIT_LABEL
from failure import Failure
from loop_claude.loop.chunk_windows import epic_chunks, HANDED, LOCK, project_lock, starting
from project_config.settings import PARALLEL_CHUNKS
from transcript_archive.project_key import project_key
# Under the home folder, a folder per epic key holds the epic's LOCK. A chunk without a repo works there.
STATE = ".local/state/do-epic"
# The flag that tells the do-epic in a window its chunk, as `--chunk ABC-34 ABC-12`. Nobody types it, so no panel picked it.
CHUNK_FLAG = "--chunk"
@dataclasses.dataclass(frozen=True)
class Chunk:
"""An issue to work as one chunk, in the window named for its key."""
issue: str
# The name of the repo it changes; None for work without a repo.
repo: str | None
@dataclasses.dataclass(frozen=True)
class Waits:
"""An open issue that doesn't run now, and why."""
issue: str
reason: str
@dataclasses.dataclass(frozen=True)
class Started:
# The issues whose chunks started.
started: list[str]
waits: list[Waits]
@dataclasses.dataclass(frozen=True)
class RepoRoom:
"""What limits the chunks in one repo's checkout."""
# The repo's `parallel-chunks`.
limit: int
# How many chunks of any epic run there.
running: int
# Whether a loop-claude runs chunks there.
loop_claude: bool
@dataclasses.dataclass(frozen=True)
class Epic:
"""The epic whose chunks start."""
key: str
# How many of its chunks may run at once.
cap: int
# The checkout of the repo with this name and its `parallel-chunks`, or why the repo cannot be used.
locate: typing.Callable[[str], tuple[pathlib.Path, int] | Failure]
home: pathlib.Path
# The do-epic script each window runs.
launcher: pathlib.Path
env: typing.Mapping[str, str]
@property
def folder(self) -> pathlib.Path:
return self.home / STATE / self.key
def chunks(issues: list[EpicIssue]) -> tuple[list[Chunk], list[Waits]]:
"""The open issues to work as chunks, in the tracker's rank order, and those that wait. An item split by repo is worked through its sub-tasks, and what blocks it blocks them. A blocker outside the epic blocks, since its state is unknown."""
by_key = {issue.key: issue for issue in issues}
found: list[Chunk] = []
waits: list[Waits] = []
for issue in issues:
if issue.done or SPLIT_LABEL in issue.labels:
continue
pick = recorded(issue)
parent = by_key.get(issue.parent)
blocking = [key for key in (*issue.blockers, *(parent.blockers if parent else ())) if key not in by_key or not by_key[key].done]
if isinstance(pick, Failure):
waits.append(Waits(issue.key, pick.reason))
elif pick is None:
waits.append(Waits(issue.key, "no label names its repo"))
elif isinstance(pick, HumanTask):
waits.append(Waits(issue.key, "it is a human's task"))
elif blocking:
waits.append(Waits(issue.key, f"{' and '.join(blocking)} block{'s' if len(blocking) == 1 else ''} it"))
else:
found.append(Chunk(issue.key, pick.name if isinstance(pick, Repo) else None))
return found, waits
def refusal(repo: str, room: RepoRoom) -> str | None:
"""Why the repo takes no further chunk; None where it takes one."""
if room.loop_claude:
return f"loop-claude runs chunks in {repo}"
if room.running >= room.limit:
return f"{repo} runs as many chunks as its `{PARALLEL_CHUNKS}` allows: {room.limit}"
return None
def start_chunks(epic: Epic, issues: list[EpicIssue], own: str | None, run: tmux.Tmux) -> Started | Failure:
"""Starts a do-epic in a new window for each of the epic's chunks that may start now. own is the issue of the chunk that asks, which has finished: it counts as running nowhere, and no stopped chunk starts again. None is the human's `do-epic <EPIC-KEY>`, which restarts each stopped chunk. A Failure says why a window could not start; those before it run."""
session = tmux.session_name(tmux.EPIC, epic.key)
found, waits = chunks(issues)
started: list[str] = []
try:
with starting(epic.folder):
windows = tmux.listed(session, run)
running = {window.name for window in windows if not window.dead} - {own}
stopped = {window.name for window in windows if window.dead} - running
for chunk in found:
if chunk.issue in running or chunk.issue == own:
continue
if own and chunk.issue in stopped:
waits.append(Waits(chunk.issue, f"its window stopped; run `do-epic {epic.key}` to start it again"))
elif len(running) + len(started) >= epic.cap:
waits.append(Waits(chunk.issue, f"the epic runs as many chunks as its `{CAP}` line allows: {epic.cap}"))
else:
now = start_chunk(epic, chunk, own, windows, run)
if isinstance(now, Failure):
return now
if isinstance(now, str):
waits.append(Waits(chunk.issue, now))
else:
windows = now
started.append(chunk.issue)
except OSError as failure:
return Failure(f"cannot lock {failure.filename or epic.folder / LOCK}: {failure.strerror}")
return Started(started, sorted(waits, key=lambda wait: [issue.key for issue in issues].index(wait.issue)))
def start_chunk(epic: Epic, chunk: Chunk, own: str | None, windows: list[tmux.Listed], run: tmux.Tmux) -> list[tmux.Listed] | str | Failure:
"""Starts chunk's window beside windows, the epic's session's, and returns the session's windows afterwards; the reason where its repo takes no chunk now, and a Failure where tmux started none. It holds the repo's lock from the check to the start. Raises OSError where that lock cannot be taken."""
session = tmux.session_name(tmux.EPIC, epic.key)
handed = {name: value for name, value in epic.env.items() if name.startswith(HANDED)}
command = [str(epic.launcher), CHUNK_FLAG, chunk.issue, epic.key]
if chunk.repo is None:
return tmux.start_chunk(tmux.Window(session, chunk.issue, ""), str(epic.folder), handed, command, windows, False, run)
located = epic.locate(chunk.repo)
if isinstance(located, Failure):
return located.reason
checkout, limit = located
with starting(project_lock(str(checkout), epic.home)):
if reason := refusal(chunk.repo, room_in(str(checkout), limit, (session, own), epic.home, run)):
return reason
return tmux.start_chunk(tmux.Window(session, chunk.issue, ""), str(checkout), handed, command, windows, False, run)
def room_in(checkout: str, limit: int, leaving: tuple[str, str | None], home: pathlib.Path, run: tmux.Tmux) -> RepoRoom:
"""The room in a repo's checkout under its limit. leaving is the session and name of a window whose chunk finished, which no longer counts."""
theirs = [placed for placed in epic_chunks(checkout, run) if (placed.session, placed.window.name) != leaving]
loop_session = tmux.session_name(tmux.LOOP, project_key(checkout, home))
loops = any(not window.dead for window in tmux.listed(loop_session, run)) and tmux.owner(loop_session, run) == checkout
return RepoRoom(limit, len(theirs), loops)
+165
View File
@@ -0,0 +1,165 @@
import contextlib
import dataclasses
import io
import pathlib
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from agent_cycle import escalation_mark, judge, tmux
from do_epic import chunk_prompt, main
from do_epic.backend.fake import MemoryEpic
from do_epic.backend.protocol import EpicIssue
from do_epic.epic_record import EpicRecord
from do_epic.test_do_epic import SETTINGS
from do_epic.test_scheduler import issue
from failure import Failure
from loop_claude.loop.reload import LoopRun
from loop_claude.loop.this_loop import Loop
from loop_claude.test_loop_claude import FakeEffects
from loop_state.paths import paths_from
from model_routing.ladder import Rung
from model_routing.route import Route
DESCRIPTION = "**Max parallel chunks:** 2\n\n## Goals\nShip the import.\n\n## Audience\nThe client's team.\n"
@dataclasses.dataclass(frozen=True)
class Description:
"""Stands in for an epic's description in Jira."""
text: str | Failure
def read(self) -> str | Failure:
return self.text
class DoEpicTest(unittest.TestCase):
def setUp(self) -> None:
made = tempfile.TemporaryDirectory()
self.addCleanup(made.cleanup)
self.home = pathlib.Path(made.name).resolve()
folder = self.home / ".claude-projects" / "do-epic"
folder.mkdir(parents=True)
(folder / "config.toml").write_text(SETTINGS, encoding="utf-8")
(folder / "repo-rule.md").write_text("A label that equals a repo's name names that repo.\n", encoding="utf-8")
self.issues = [issue("ABC-20"), dataclasses.replace(issue("ABC-21", "do-epic-claude"), detail="Tidy the docs.", scores={"L": 3, "E": 2, "I": 3})]
self.description: str | Failure = DESCRIPTION
def backend(self, config: object, key: str) -> tuple[MemoryEpic, EpicRecord]:
return MemoryEpic(key, list(self.issues)), EpicRecord(Description(self.description)) # type: ignore[arg-type]
def run_main(self, argv: list[str], fake: FakeEffects, env: dict[str, str] | None = None) -> tuple[int, str, str]:
out, err = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
code = main.main(argv, env or {}, paths_from(self.home), pathlib.Path("/b/do-epic"), fake.effects(), self.backend)
return code, out.getvalue(), err.getvalue()
class TheCommand(DoEpicTest):
def test_prints_the_help_for_anything_but_one_epic_key(self) -> None:
for argv, code in ((["--help"], 0), (["-h"], 0), ([], 1), (["abc"], 1), (["ABC-12", "ABC-13"], 1), (["--chunk", "x", "ABC-12"], 1)):
with self.subTest(argv=argv):
ran_code, out, err = self.run_main(argv, FakeEffects())
self.assertEqual((ran_code, (err if code else out).split(" ", 1)[1]), (code, main.HELP + "\n"))
def test_refuses_a_tmux_too_old_naming_do_epic(self) -> None:
code, _, err = self.run_main(["ABC-12"], FakeEffects(tmux_version="tmux 3.1"))
self.assertEqual(code, 1)
self.assertIn("do-epic runs each chunk in a tmux window, and needs tmux 3.2 or later; it found tmux 3.1", err)
def test_starts_the_chunks_and_says_why_each_other_issue_waits(self) -> None:
fake = FakeEffects(on_terminal=False)
code, out, _ = self.run_main(["ABC-12"], fake, {"LOOP_CLAUDE_WORKER_MODEL": "m"})
self.assertEqual(code, 0)
self.assertIn("started ABC-21 in the tmux session epic-ABC-12\n", out)
self.assertIn("ABC-20 waits: no label names its repo\n", out)
started = [args for args in fake.tmux_calls if args[0] == "new-session"]
self.assertEqual(started, [["new-session", "-d", "-s", "epic-ABC-12", "-n", "ABC-21", "-c", str(self.home / ".local/state/do-epic/ABC-12"), "-e", "LOOP_CLAUDE_WORKER_MODEL=m", "-P", "-F", "#{window_id}", "--", "/b/do-epic", "--chunk", "ABC-21", "ABC-12"]])
# The session is no checkout's, so nothing marks it as one's.
self.assertNotIn(tmux.OWNER, [args[3] for args in fake.tmux_calls if args[0] == "set-option"])
def test_stops_on_an_epic_it_cannot_read(self) -> None:
self.description = Failure("Jira answered 401")
code, _, err = self.run_main(["ABC-12"], FakeEffects())
self.assertEqual(code, 1)
self.assertIn("Jira answered 401\n", err)
def test_a_chunk_outside_a_tmux_window_says_how_to_run_do_epic(self) -> None:
fake = FakeEffects()
code, _, err = self.run_main(["--chunk", "ABC-21", "ABC-12"], fake)
self.assertEqual(code, 1)
self.assertIn("--chunk is how do-epic starts itself in a tmux window; run do-epic <EPIC-KEY>\n", err)
self.assertEqual(fake.dms, ["do-epic --chunk ABC-21 ABC-12 stopped: --chunk is how do-epic starts itself in a tmux window; run do-epic <EPIC-KEY>"])
def test_a_chunk_of_an_issue_the_epic_lacks_stops(self) -> None:
code, _, err = self.run_main(["--chunk", "ABC-99", "ABC-12"], FakeEffects(), {"TMUX_PANE": "%1"})
self.assertEqual(code, 1)
self.assertIn("ABC-99 is no issue of the epic ABC-12\n", err)
class ACycleOfAChunkWithoutARepo(DoEpicTest):
def cycle(self, env: dict[str, str] | None = None) -> main.Cycle:
fake = FakeEffects(git=[Failure("no git"), Failure("no git")])
paths = paths_from(self.home)
config = main.load(self.home)
assert not isinstance(config, Failure)
store, record = self.backend(config, "ABC-12")
epic = main.EpicRun("ABC-12", config, store, record, paths, env or {}, pathlib.Path("/b/do-epic"), fake.effects())
root = main.chunk_root(self.issues[1], epic)
assert isinstance(root, str)
loop = Loop(root=root, session=main.session_named("A ABC-12 do-epic ABC-21", paths.claude_code_transcripts), window=tmux.Window("epic-ABC-12", "ABC-21", "%1"), paths=paths, env=env or {}, launcher=pathlib.Path("/b/do-epic"), effects=fake.effects())
with contextlib.redirect_stdout(io.StringIO()):
found = main.next_cycle(LoopRun(1, root, "", "", chunk="ABC-21"), loop, epic)
assert isinstance(found, main.Cycle), found
return found
def test_routes_on_the_repoless_model_by_the_issues_scores(self) -> None:
cycle = self.cycle()
assert cycle.project is not None
self.assertEqual(cycle.project.rung.model, "claude-opus-5-5")
self.assertEqual(cycle.route, Route(cycle.project.worker_rung(3), 21, 3, 5))
self.assertEqual(cycle.judge.model, "claude-opus-5-5")
self.assertEqual(self.cycle({"LOOP_CLAUDE_WORKER_MODEL": "off-the-ladder"}).route, Route(Rung("off-the-ladder")))
def test_works_in_the_epics_folder_and_archives_apart_from_loop_claude(self) -> None:
cycle = self.cycle()
self.assertEqual((cycle.root, cycle.project_archive, cycle.records), (str(self.home / ".local/state/do-epic/ABC-12"), self.home / ".claude/do-epic-transcripts/ABC-12", ""))
def test_the_premises_are_the_epics_goals_and_audience(self) -> None:
self.assertEqual(self.cycle().premises, "the epic ABC-12's description:\n## Goals\nShip the import.\n\n## Audience\nThe client's team.")
def test_the_task_is_the_issue(self) -> None:
self.assertEqual(self.cycle().task, "Work the Jira issue ABC-21 of the epic ABC-12 as one chunk, which changes no repo: work in the folder you start in. Its summary: Do ABC-21\n\nIts description:\n\nTidy the docs.")
def test_an_issue_without_scores_runs_on_the_projects_rung(self) -> None:
self.issues[1] = dataclasses.replace(self.issues[1], scores={})
cycle = self.cycle()
assert cycle.project is not None
self.assertEqual(cycle.route, Route(cycle.project.rung))
class WhatAWorkerJudgeAndHumanRead(DoEpicTest):
def test_every_prompt_names_do_epic_and_never_loop_claude(self) -> None:
cycle = ACycleOfAChunkWithoutARepo.cycle(self) # type: ignore[arg-type]
prompts = cycle.prompts
texts = [
prompts.fresh(cycle.task, cycle.premises, cycle.route, cycle.project, ""),
prompts.resumed("the work remaining", cycle.route, cycle.project),
prompts.typed("Which one?", "The first.", cycle.route, cycle.project, True),
judge.judge_rules(prompts.answer_destinations, prompts.driver),
str(judge.judge_schema(prompts.driver)),
]
for text in texts:
self.assertNotIn("loop-claude", text)
self.assertIn(f"do-epic runs you on {cycle.route.rung}, routed by the issue's L of 3. Where a sentence below names item 21, it means the issue.", texts[0])
self.assertNotIn("Chunk items:", texts[1])
# The worker's prompt and the judge's rules word the request for a higher rung alike, from one place.
for text in (texts[0], texts[3]):
self.assertIn(escalation_mark.asks_higher_rung(chunk_prompt.DRIVER), text)
self.assertEqual(escalation_mark.asks_higher_rung(chunk_prompt.DRIVER), "asking do-epic for a higher rung")
if __name__ == "__main__":
unittest.main()
+171
View File
@@ -0,0 +1,171 @@
import pathlib
import subprocess
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from agent_cycle import tmux
from do_epic.backend.protocol import EpicIssue
from do_epic.epic_record import parallel_chunks_in
from do_epic.scheduler import Chunk, chunks, CHUNK_FLAG, Epic, RepoRoom, refusal, start_chunks, Started, Waits
from failure import Failure
def issue(key: str, *labels: str, done: bool = False, blockers: tuple[str, ...] = (), parent: str = "ABC-12") -> EpicIssue:
return EpicIssue(key, f"Do {key}", "", tuple(sorted(labels)), None, "Done" if done else "To Do", done, parent, blockers=blockers)
class TheCapLine(unittest.TestCase):
def test_reads_the_epics_cap(self) -> None:
self.assertEqual(parallel_chunks_in("**Language:** Swedish\n**Max parallel chunks:** 3\n\n## Goals\nShip.\n"), 3)
def test_an_epic_without_the_line_runs_one_chunk_at_once(self) -> None:
self.assertEqual(parallel_chunks_in("## Goals\nShip.\n"), 1)
self.assertEqual(parallel_chunks_in("```\n**Max parallel chunks:** 3\n```\n"), 1)
def test_refuses_a_cap_that_is_no_whole_number_of_1_or_more(self) -> None:
for value in ("0", "many", "2.5", "-1", ""):
found = parallel_chunks_in(f"**Max parallel chunks:** {value}\n")
assert isinstance(found, Failure)
self.assertEqual(found.reason, f"the epic's description caps its chunks with `**Max parallel chunks:** {value}`, which is not a whole number of 1 or more, such as `**Max parallel chunks:** 2`")
class WhichIssuesAreChunks(unittest.TestCase):
def test_an_open_issue_with_a_repo_or_claude_work_is_a_chunk_in_rank_order(self) -> None:
found = chunks([issue("ABC-20", "repo:api"), issue("ABC-21", "do-epic-claude"), issue("ABC-22", "repo:web", done=True)])
self.assertEqual(found, ([Chunk("ABC-20", "api"), Chunk("ABC-21", None)], []))
def test_a_split_item_is_no_chunk_but_its_sub_tasks_are(self) -> None:
found = chunks([issue("ABC-20", "split-by-repo"), issue("ABC-23", "repo:api", parent="ABC-20"), issue("ABC-24", "repo:web", parent="ABC-20")])
self.assertEqual(found, ([Chunk("ABC-23", "api"), Chunk("ABC-24", "web")], []))
def test_an_issue_waits_for_its_pick_its_human_and_its_blockers(self) -> None:
found = chunks([
issue("ABC-20"),
issue("ABC-21", "do-epic-human"),
issue("ABC-22", "repo:api", "repo:web"),
issue("ABC-23", "repo:api", blockers=("ABC-20", "ABC-30", "XYZ-1")),
issue("ABC-30", "repo:api", done=True),
])
self.assertEqual(found, ([], [
Waits("ABC-20", "no label names its repo"),
Waits("ABC-21", "it is a human's task"),
Waits("ABC-22", "ABC-22 is labelled with 2 picks: repo:api, repo:web; remove all but the right one"),
Waits("ABC-23", "ABC-20 and XYZ-1 block it"),
]))
class RoomInARepo(unittest.TestCase):
def test_a_repo_with_room_and_no_loop_claude_takes_a_chunk(self) -> None:
self.assertIsNone(refusal("api", RepoRoom(limit=2, running=1, loop_claude=False)))
def test_a_full_repo_takes_none(self) -> None:
self.assertEqual(refusal("api", RepoRoom(limit=2, running=2, loop_claude=False)), "api runs as many chunks as its `parallel-chunks` allows: 2")
def test_a_repo_loop_claude_runs_chunks_in_takes_none(self) -> None:
self.assertEqual(refusal("api", RepoRoom(limit=2, running=0, loop_claude=True)), "loop-claude runs chunks in api")
class Tmux:
"""Stands in for tmux: `windows` are the rows of `list-windows -a`, as session, name, dead and root; a started window joins them."""
def __init__(self, *windows: tuple[str, str, bool, str], owners: dict[str, str] | None = None) -> None:
self.windows, self.owners, self.calls = list(windows), owners or {}, []
def __call__(self, args: list[str]) -> subprocess.CompletedProcess[str]:
self.calls.append(args)
out = ""
if args[0] == "list-windows" and "-a" in args:
out = "".join(f"{session}\t{name}\t{int(dead)}\t@{at}\t{root}\n" for at, (session, name, dead, root) in enumerate(self.windows))
elif args[0] == "list-windows":
out = "".join(f"{name}\t{int(dead)}\t@{at}\n" for at, (session, name, dead, _) in enumerate(self.windows) if f"={session}" == args[2])
elif args[0] == "show-options":
out = self.owners.get(args[3].removeprefix("=").removesuffix(":"), "") + "\n"
elif args[0] in ("new-session", "new-window"):
session = args[args.index("-s") + 1] if args[0] == "new-session" else args[args.index("-t") + 1].removeprefix("=").removesuffix(":")
self.windows.append((session, args[args.index("-n") + 1], False, args[args.index("-c") + 1]))
out = f"@{len(self.windows) - 1}\n"
elif args[0] == "kill-window":
self.windows[int(args[2].removeprefix("@"))] = ("", "", True, "")
return subprocess.CompletedProcess(args, 0, out, "")
def started(self) -> list[tuple[str, str, str]]:
"""Each window started, as its session, its name and its command's words after the launcher."""
return [(args[3].removeprefix("=").removesuffix(":"), args[args.index("-n") + 1], " ".join(args[args.index("--") + 2:])) for args in self.calls if args[0] in ("new-session", "new-window")]
class StartingAnEpicsChunks(unittest.TestCase):
def setUp(self) -> None:
folder = tempfile.TemporaryDirectory()
self.addCleanup(folder.cleanup)
self.home = pathlib.Path(folder.name)
def epic(self, cap: int, **limits: int) -> Epic:
"""An epic whose repos are checked out under the home folder, each with its `parallel-chunks`."""
def locate(name: str) -> tuple[pathlib.Path, int] | Failure:
return (self.home / "code" / name, limits[name]) if name in limits else Failure(f"no project config names {name}")
return Epic("ABC-12", cap, locate, self.home, pathlib.Path("/bin/do-epic"), {"LOOP_CLAUDE_X": "1", "OTHER": "2"})
def start(self, epic: Epic, issues: list[EpicIssue], run: Tmux, own: str | None = None) -> Started:
found = start_chunks(epic, issues, own, run)
assert not isinstance(found, Failure), found
return found
def test_starts_a_window_per_chunk_up_to_the_epics_cap(self) -> None:
run = Tmux()
found = self.start(self.epic(2, api=1, web=1), [issue("ABC-20", "repo:api"), issue("ABC-21", "do-epic-claude"), issue("ABC-22", "repo:web")], run)
self.assertEqual(found, Started(["ABC-20", "ABC-21"], [Waits("ABC-22", "the epic runs as many chunks as its `**Max parallel chunks:**` line allows: 2")]))
self.assertEqual(run.started(), [("epic-ABC-12", "ABC-20", f"{CHUNK_FLAG} ABC-20 ABC-12"), ("epic-ABC-12", "ABC-21", f"{CHUNK_FLAG} ABC-21 ABC-12")])
self.assertEqual([args[args.index("-c") + 1] for args in run.calls if args[0] in ("new-session", "new-window")], [str(self.home / "code/api"), str(self.home / ".local/state/do-epic/ABC-12")])
self.assertIn("LOOP_CLAUDE_X=1", run.calls[[args[0] for args in run.calls].index("new-session")])
self.assertNotIn("OTHER=2", run.calls[[args[0] for args in run.calls].index("new-session")])
def test_a_running_chunk_counts_and_is_not_started_twice(self) -> None:
run = Tmux(("epic-ABC-12", "ABC-20 ?", False, str(self.home / "code/api")))
found = self.start(self.epic(2, api=2), [issue("ABC-20", "repo:api"), issue("ABC-21", "repo:api"), issue("ABC-22", "repo:api")], run)
self.assertEqual(found, Started(["ABC-21"], [Waits("ABC-22", "the epic runs as many chunks as its `**Max parallel chunks:**` line allows: 2")]))
def test_a_repo_takes_its_parallel_chunks_across_epics(self) -> None:
run = Tmux(("epic-XYZ-1", "XYZ-5", False, str(self.home / "code/api")))
found = self.start(self.epic(3, api=1, web=1), [issue("ABC-20", "repo:api"), issue("ABC-21", "repo:web")], run)
self.assertEqual(found, Started(["ABC-21"], [Waits("ABC-20", "api runs as many chunks as its `parallel-chunks` allows: 1")]))
def test_never_starts_in_a_repo_loop_claude_runs_chunks_in(self) -> None:
run = Tmux(("loop-api", "item-3", False, str(self.home / "code/api")), owners={"loop-api": str(self.home / "code/api")})
found = self.start(self.epic(3, api=2), [issue("ABC-20", "repo:api")], run)
self.assertEqual(found, Started([], [Waits("ABC-20", "loop-claude runs chunks in api")]))
def test_a_stopped_loop_claude_window_keeps_no_repo(self) -> None:
run = Tmux(("loop-api", "item-3", True, str(self.home / "code/api")), owners={"loop-api": str(self.home / "code/api")})
self.assertEqual(self.start(self.epic(3, api=2), [issue("ABC-20", "repo:api")], run).started, ["ABC-20"])
def test_a_repo_that_cannot_be_located_waits_with_the_reason(self) -> None:
found = self.start(self.epic(3), [issue("ABC-20", "repo:api")], Tmux())
self.assertEqual(found, Started([], [Waits("ABC-20", "no project config names api")]))
def test_the_human_restarts_a_stopped_chunk_in_place_of_its_window(self) -> None:
run = Tmux(("epic-ABC-12", "ABC-20", True, str(self.home / "code/api")))
self.assertEqual(self.start(self.epic(1, api=1), [issue("ABC-20", "repo:api")], run).started, ["ABC-20"])
self.assertIn(["kill-window", "-t", "@0"], run.calls)
def test_a_finished_chunk_leaves_its_room_and_restarts_no_stopped_chunk(self) -> None:
run = Tmux(("epic-ABC-12", "ABC-20", False, str(self.home / "code/api")), ("epic-ABC-12", "ABC-21", True, str(self.home / "code/api")))
found = self.start(self.epic(1, api=1), [issue("ABC-20", "repo:api"), issue("ABC-21", "repo:api"), issue("ABC-22", "repo:api")], run, own="ABC-20")
self.assertEqual(found, Started(["ABC-22"], [Waits("ABC-21", "its window stopped; run `do-epic ABC-12` to start it again")]))
def test_holds_each_repos_starting_lock_that_loop_claude_holds(self) -> None:
self.start(self.epic(1, api=1), [issue("ABC-20", "repo:api")], Tmux())
self.assertTrue((self.home / ".local/state/loop-claude/api/starting").is_file())
self.assertTrue((self.home / ".local/state/do-epic/ABC-12/starting").is_file())
class WindowsAcrossSessions(unittest.TestCase):
def test_lists_each_window_with_its_session_and_root(self) -> None:
run = Tmux(("epic-ABC-12", "ABC-20 ?", False, "/code/api"), ("loop-api", "item-3", True, ""))
self.assertEqual(tmux.everywhere(run), [tmux.Placed("epic-ABC-12", tmux.Listed("ABC-20", "@0", False), "/code/api"), tmux.Placed("loop-api", tmux.Listed("item-3", "@1", True), "")])
if __name__ == "__main__":
unittest.main()
+7 -7
View File
@@ -169,11 +169,11 @@ def reruns(route: Route, project: ProjectRung | None) -> list[str]:
return [f"A reviewer that asks for a rerun one rung up reruns with the Agent tool set to `{rerun['reviewer'].agent_args()}`, and a comprehension seat with `{rerun['comprehension seat'].agent_args()}`."]
def resumed(driver: str, unfinished_evidence: str, route: Route, project: ProjectRung | None) -> str:
"""Names the worker's rung, so it learns whether its request for a higher rung went through, and the project's again, since a step-up between cycles may have taken the worker above it."""
def resumed(driver: str, naming: str, unfinished_evidence: str, route: Route, project: ProjectRung | None) -> str:
"""naming is the sentence that asks the worker to name its chunk's items, empty where the entry point reads none. Names the worker's rung, so it learns whether its request for a higher rung went through, and the project's again, since a step-up between cycles may have taken the worker above it."""
on = f" {driver} runs you on {route.rung}." if project else ""
ruled = f" A judge ruled the chunk unfinished, quoting this passage of your transcript as the work remaining:\n\n{quoted(unfinished_evidence)}\n\n" if unfinished_evidence else " "
return f"Continue the task; the previous run ended before the chunk was finished.{ruled}The chunk is finished once it is merged, or nothing remains that you could do on your own. Even then, it is finished only once {ANSWERS_RECORDED}. {NAME_THE_ITEMS}{on}{rungs_held(driver, route, project)}"
return f"Continue the task; the previous run ended before the chunk was finished.{ruled}The chunk is finished once it is merged, or nothing remains that you could do on your own. Even then, it is finished only once {ANSWERS_RECORDED}.{naming and f' {naming}'}{on}{rungs_held(driver, route, project)}"
def rung_sentences(driver: str, route: Route, project: ProjectRung | None) -> list[str]:
@@ -186,9 +186,9 @@ def rungs_held(driver: str, route: Route, project: ProjectRung | None) -> str:
return "".join(f" {sentence}" for sentence in rung_sentences(driver, route, project))
def worker_prompts(driver: str, fresh: typing.Callable[[str, str, Route, ProjectRung | None, str], str]) -> WorkerPrompts:
"""The prompts of an entry point's cycles: its own fresh prompt, and the resumed prompt and rung sentences every entry point shares, each naming driver."""
return WorkerPrompts(driver, fresh, functools.partial(resumed, driver), functools.partial(rungs_held, driver), QUOTE_SOURCES, ANSWER_DESTINATIONS)
def worker_prompts(driver: str, fresh: typing.Callable[[str, str, Route, ProjectRung | None, str], str], naming: str) -> WorkerPrompts:
"""The prompts of an entry point's cycles: its own fresh prompt, and the resumed prompt and rung sentences every entry point shares, each naming driver. resumed says what naming is."""
return WorkerPrompts(driver, fresh, functools.partial(resumed, driver, naming), functools.partial(rungs_held, driver), QUOTE_SOURCES, ANSWER_DESTINATIONS)
WORKER = worker_prompts(DRIVER, functools.partial(fresh, DRIVER))
WORKER = worker_prompts(DRIVER, functools.partial(fresh, DRIVER), NAME_THE_ITEMS)
+2 -2
View File
@@ -6,7 +6,7 @@ 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 agent_cycle.routing import first_route, kept
from agent_cycle.routing import first_route, kept, Scored
from loop_claude.loop.chunk_windows import held_beside, item_of
from chunk_preflight.main import ITEM
from plan.todo_table import Item
@@ -32,7 +32,7 @@ def scored_plan(default: DefaultPlan | Failure, effects: Effects) -> Plan | Fail
return plan
def routed(route: Route | None, project: ProjectRung | None, model: str, archived: typing.Callable[[], Route | None], item: typing.Callable[[], Item | None]) -> Route:
def routed(route: Route | None, project: ProjectRung | None, model: str, archived: typing.Callable[[], Route | None], item: typing.Callable[[], Scored | None]) -> Route:
"""The route the cycle runs on. project is the project's rung, and model the project's model.
Where project is None, the model is off the ladder, and the worker runs on it. Otherwise the chunk keeps route, or on a rerun the route its archive last names, as routing.kept allows. Else the plan item routes the chunk afresh.
+49 -30
View File
@@ -24,7 +24,7 @@ from agent_cycle import tmux
# Under the home folder, a folder per project key holds LOCK.
STATE = ".local/state/loop-claude"
# The file a loop keeps locked with flock while it lists the project's windows and starts new ones, so two loops whose chunks finish together don't start a chunk twice.
# The file an entry point keeps locked with flock while it lists the windows of a project's chunks and starts new ones. Two loops whose chunks finish together then don't start a chunk twice, and do-epic, which holds the same lock, never starts a chunk in a checkout while loop-claude does.
LOCK = "starting"
# The flag that tells the loop in a window its chunk, as `--chunk item-372`. Nobody types it, so no panel picked it.
CHUNK_FLAG = "--chunk"
@@ -52,15 +52,24 @@ def chunk_session(key: str, chunk: str, claude_code_transcripts: pathlib.Path) -
@contextlib.contextmanager
def starting(home: pathlib.Path, key: str) -> typing.Iterator[None]:
"""Holds the project's LOCK. Raises OSError where the file cannot be opened or locked."""
folder = home / STATE / key
def starting(folder: pathlib.Path) -> typing.Iterator[None]:
"""Holds the LOCK in folder: project_lock's for a project, or do-epic's for an epic. Raises OSError where the file cannot be opened or locked."""
folder.mkdir(parents=True, exist_ok=True)
with open(folder / LOCK, "a") as lock:
fcntl.flock(lock, fcntl.LOCK_EX)
yield
def project_lock(root: str, home: pathlib.Path) -> pathlib.Path:
"""The folder of the LOCK that everything starting a chunk in the checkout root holds."""
return home / STATE / project_key(root, home)
def epic_chunks(root: str, run: tmux.Tmux) -> list[tmux.Placed]:
"""The windows of do-epic's sessions whose chunks run in the checkout root."""
return [placed for placed in tmux.everywhere(run) if placed.session.startswith(f"{tmux.EPIC}-") and placed.root == root and not placed.window.dead]
def held_items(chunks: typing.Iterable[str], key: str, claude_code_transcripts: pathlib.Path) -> set[int]:
"""The plan items these chunks hold: the one each started from, and those its worker names on its latest `Chunk items:` line so far. A chunk whose transcript cannot be read holds the item it started from."""
held: set[int] = set()
@@ -128,40 +137,50 @@ def next_plan(root: str, home: pathlib.Path, effects: Effects) -> NextChunk | No
def start_chunks(loop_run: LoopRun, leaving: bool, paths: Paths, env: typing.Mapping[str, str], launcher: pathlib.Path, effects: Effects) -> list[str] | Failure:
"""Starts a loop-claude in a new window for each chunk of loop_run's project that may start now, and returns the chunks started. leaving says that loop_run's own chunk finished, so its window no longer counts as running; without it, the human started loop-claude. A plan that cannot be read starts NO_ITEM, as a plan without an item does. A Failure says why a chunk could not start; those before it run."""
"""Starts a loop-claude in a new window for each chunk of loop_run's project that may start now, and returns the chunks started. leaving says that loop_run's own chunk finished, so its window no longer counts as running; without it, the human started loop-claude. A Failure says why no chunk may start, or why one could not; those before it run."""
config = located(loop_run.root, paths.home)
if isinstance(config, Failure):
return config
key = project_key(loop_run.root, paths.home)
session = tmux.session_name(tmux.LOOP, key)
session = tmux.session_name(tmux.LOOP, project_key(loop_run.root, paths.home))
handed = {name: value for name, value in env.items() if name.startswith(HANDED)}
lock = project_lock(loop_run.root, paths.home)
try:
with starting(paths.home, key):
with starting(lock):
windows = tmux.listed(session, effects.tmux)
if windows and (owned := tmux.owner(session, effects.tmux)) != loop_run.root:
return Failure(f"the tmux session {session} runs the chunks of {owned or 'another checkout'}, whose key maps to the same session name; rename one of the two checkouts' folders")
room = room_of(windows, loop_run.chunk, leaving, config.parallel_chunks)
chunks = list(room.restart)
if room.left:
plan = next_plan(loop_run.root, paths.home, effects)
if isinstance(plan, Failure):
# Such as in a checkout without a default branch, where chunk-preflight fails too: the worker is told why and finds the facts itself.
say(f"starting a chunk without a plan item, since the plan cannot be read: {plan.reason}", effects)
plan = NoItem(plan.reason)
held = held_items(room.running + room.stopped, key, paths.claude_code_transcripts)
chunks += [chunk for chunk in may_start(plan, room.running + room.restart, held, room.left) if chunk not in room.stopped]
if refused := refusal(session, windows, loop_run.root, effects.tmux):
return refused
chunks = chunks_to_start(windows, loop_run, leaving, config.parallel_chunks, paths, effects)
for chunk in chunks:
stale = [window for window in windows if window.name == chunk and window.dead]
for window in stale:
tmux.close(window, effects.tmux)
windows = [window for window in windows if window not in stale]
command = [str(launcher), CHUNK_FLAG, chunk, loop_run.task]
if failed := tmux.start_window(tmux.Window(session, chunk, ""), loop_run.root, handed, command, not windows, effects.tmux):
return failed
windows.append(tmux.Listed(chunk, "", False))
started = tmux.start_chunk(tmux.Window(session, chunk, ""), loop_run.root, handed, [str(launcher), CHUNK_FLAG, chunk, loop_run.task], windows, True, effects.tmux)
if isinstance(started, Failure):
return started
windows = started
return chunks
except OSError as failure:
return Failure(f"cannot lock {paths.home / STATE / key / LOCK}: {failure.strerror}")
return Failure(f"cannot lock {lock / LOCK}: {failure.strerror}")
def refusal(session: str, windows: list[tmux.Listed], root: str, run: tmux.Tmux) -> Failure | None:
"""Why no chunk of the checkout root may start in session, whose windows are windows: another checkout's chunks run in the session, or do-epic runs chunks in root."""
if windows and (owned := tmux.owner(session, run)) != root:
return Failure(f"the tmux session {session} runs the chunks of {owned or 'another checkout'}, whose key maps to the same session name; rename one of the two checkouts' folders")
if theirs := epic_chunks(root, run):
return Failure(f"do-epic runs chunks in {root}: {', '.join(f'{placed.window.name} of {placed.session}' for placed in theirs)}; loop-claude starts none there until they finish")
return None
def chunks_to_start(windows: list[tmux.Listed], loop_run: LoopRun, leaving: bool, limit: int, paths: Paths, effects: Effects) -> list[str]:
"""The chunks to start beside windows, the session's: the stopped ones room_of restarts, then those of the plan that may_start picks. A plan that cannot be read starts NO_ITEM, as a plan without an item does."""
room = room_of(windows, loop_run.chunk, leaving, limit)
if not room.left:
return room.restart
plan = next_plan(loop_run.root, paths.home, effects)
if isinstance(plan, Failure):
# Such as in a checkout without a default branch, where chunk-preflight fails too: the worker is told why and finds the facts itself.
say(f"starting a chunk without a plan item, since the plan cannot be read: {plan.reason}", effects)
plan = NoItem(plan.reason)
held = held_items(room.running + room.stopped, project_key(loop_run.root, paths.home), paths.claude_code_transcripts)
return room.restart + [chunk for chunk in may_start(plan, room.running + room.restart, held, room.left) if chunk not in room.stopped]
def held_beside(chunk: str, root: str, paths: Paths, effects: Effects) -> list[int]:
@@ -174,5 +193,5 @@ def held_beside(chunk: str, root: str, paths: Paths, effects: Effects) -> list[i
def wait_for_starts(home: pathlib.Path, key: str) -> None:
"""Returns once no loop of the project is starting windows: start_chunks holds LOCK while it starts them. Where the lock cannot be taken, it returns at once."""
with contextlib.suppress(OSError), starting(home, key):
with contextlib.suppress(OSError), starting(home / STATE / key):
pass
+5 -5
View File
@@ -15,8 +15,8 @@ from claude_code.session import transcript_file
UNFINISHED_LIMIT = 6
def closed_cycle(loop_run: LoopRun, project: ProjectRung | None, concluded: Concluded, archive_folder: pathlib.Path, loop: Loop) -> LoopRun | Stop:
"""The loop run after a cycle concluded, with the step-up archived; the stop that needs the human, archived, once the chunk has had UNFINISHED_LIMIT unfinished verdicts running."""
def closed_cycle(loop_run: LoopRun, project: ProjectRung | None, concluded: Concluded, archive_folder: pathlib.Path, driver: str, loop: Loop) -> LoopRun | Stop:
"""The loop run after a cycle of driver, the entry point, concluded, with the step-up archived; the stop that needs the human, archived, once the chunk has had UNFINISHED_LIMIT unfinished verdicts running."""
after = after_verdict(loop_run, project, concluded)
# A finished chunk drops its route, so it has no step-up, and its run of unfinished verdicts restarts.
if after.route is None:
@@ -25,17 +25,17 @@ def closed_cycle(loop_run: LoopRun, project: ProjectRung | None, concluded: Conc
path = transcript_file(loop.session)
if path and (failure := archived_step(archive_folder, path, after.task, step_up(concluded.route, after.route), loop.effects)):
return Stop(1, failure.reason)
if limit := reached_limit(after):
if limit := reached_limit(after, driver):
# Archived with the route the next cycle would run on, so a rerun resumes there.
return archived_stop(archive_folder, loop.session, after.task, after.route, limit, limit.reason, loop.effects)
return after
def reached_limit(loop_run: LoopRun) -> Stop | None:
def reached_limit(loop_run: LoopRun, driver: str) -> Stop | None:
"""The stop that needs the human once the loop run holds UNFINISHED_LIMIT unfinished verdicts running."""
if loop_run.unfinished_run < UNFINISHED_LIMIT:
return None
return needs_human("go on with the chunk", f"the judge ruled it unfinished {loop_run.unfinished_run} cycles running; finish the chunk yourself, or rerun loop-claude to give it {UNFINISHED_LIMIT} more cycles")
return needs_human("go on with the chunk", f"the judge ruled it unfinished {loop_run.unfinished_run} cycles running; finish the chunk yourself, or rerun {driver} to give it {UNFINISHED_LIMIT} more cycles")
def after_verdict(loop_run: LoopRun, project: ProjectRung | None, concluded: Concluded) -> LoopRun:
+1 -1
View File
@@ -71,7 +71,7 @@ def run_loop(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launc
concluded = run_cycle(cycle)
if isinstance(concluded, Stop):
return concluded
closed = closed_cycle(loop_run, cycle.project, concluded, cycle.project_archive, loop)
closed = closed_cycle(loop_run, cycle.project, concluded, cycle.project_archive, prompts.DRIVER, loop)
if isinstance(closed, Stop):
return closed
loop_run = closed
+3 -1
View File
@@ -831,8 +831,10 @@ class Windows(unittest.TestCase):
self.assertEqual(run.tmux, [
["-V"],
["list-windows", "-t", "=loop-proj", "-F", "#{window_name}\t#{pane_dead}\t#{window_id}"],
["list-windows", "-a", "-F", "#{session_name}\t#{window_name}\t#{pane_dead}\t#{window_id}\t#{@chunk-root}"],
["new-session", "-d", "-s", "loop-proj", "-n", "item-4", "-c", str(checkout.root), "-e", "LOOP_CLAUDE_JUDGE_MODEL=judge-model", "-e", "LOOP_CLAUDE_WORKER_MODEL=worker-model", "-P", "-F", "#{window_id}", "--", str(checkout.script), "--chunk", "item-4", "ship it"],
["set-option", "-t", "=loop-proj:", "@loop-root", str(checkout.root)],
["set-option", "-w", "-t", "@7", "@chunk-root", str(checkout.root)],
["set-option", "-w", "-t", "@7", "remain-on-exit", "failed"],
])
self.assertEqual(run.stdout, "started item-4 in the tmux session loop-proj\nnot on a terminal; see the chunks with `tmux attach -t =loop-proj`\n")
@@ -1127,7 +1129,7 @@ class Reload(unittest.TestCase):
state = {"cycle_number": 3, "root": str(checkout.root), "task": TASK, "unfinished_evidence": "", "route": None, "slot": 0}
run = checkout.run([worker()], argv=["--reloaded", json.dumps(state)])
self.assertEqual((run.code, run.calls), (0, []))
self.assertEqual([command[0] for command in run.tmux], ["-V", "list-windows", "new-session", "set-option", "set-option"])
self.assertEqual([command[0] for command in run.tmux], ["-V", "list-windows", "list-windows", "new-session", "set-option", "set-option", "set-option"])
self.assertIn("started no-item in the tmux session loop-proj\n", run.stdout)
def test_stops_where_a_reload_hands_no_state(self):
+18 -11
View File
@@ -1328,13 +1328,15 @@ class TmuxCommands(unittest.TestCase):
def test_the_first_window_makes_the_session_and_each_later_one_joins_it(self):
fake = FakeEffects()
window = tmux.Window("loop-proj", "item-7", "")
self.assertIsNone(tmux.start_window(window, "/r", {"LOOP_CLAUDE_X": "1"}, ["/b/loop-claude", "--chunk", "item-7", "ship it;"], True, fake.tmux))
self.assertIsNone(tmux.start_window(window, "/r", {}, ["/b/loop-claude"], False, fake.tmux))
self.assertIsNone(tmux.start_window(window, "/r", {"LOOP_CLAUDE_X": "1"}, ["/b/loop-claude", "--chunk", "item-7", "ship it;"], True, True, fake.tmux))
self.assertIsNone(tmux.start_window(window, "/r", {}, ["/b/loop-claude"], False, True, fake.tmux))
self.assertEqual(fake.tmux_calls, [
["new-session", "-d", "-s", "loop-proj", "-n", "item-7", "-c", "/r", "-e", "LOOP_CLAUDE_X=1", "-P", "-F", "#{window_id}", "--", "/b/loop-claude", "--chunk", "item-7", "ship it\;"],
["set-option", "-t", "=loop-proj:", "@loop-root", "/r"],
["set-option", "-w", "-t", "@9", "@chunk-root", "/r"],
["set-option", "-w", "-t", "@9", "remain-on-exit", "failed"],
["new-window", "-d", "-t", "=loop-proj:", "-n", "item-7", "-c", "/r", "-P", "-F", "#{window_id}", "--", "/b/loop-claude"],
["set-option", "-w", "-t", "@9", "@chunk-root", "/r"],
["set-option", "-w", "-t", "@9", "remain-on-exit", "failed"],
])
@@ -1342,8 +1344,8 @@ class TmuxCommands(unittest.TestCase):
failed = lambda args: subprocess.CompletedProcess(args, 1, "", "duplicate session: loop-proj\n")
silent = lambda args: subprocess.CompletedProcess(args, 2, "", "")
window = tmux.Window("loop-proj", "item-7", "")
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, failed), Failure("tmux could not start the window loop-proj:item-7: duplicate session: loop-proj"))
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, silent), Failure("tmux could not start the window loop-proj:item-7: it exited 2"))
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, True, failed), Failure("tmux could not start the window loop-proj:item-7: duplicate session: loop-proj"))
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, True, silent), Failure("tmux could not start the window loop-proj:item-7: it exited 2"))
def test_fails_where_it_cannot_mark_a_session_it_made_as_the_checkouts_but_not_where_remain_on_exit_fails(self):
def answering(failing: str):
@@ -1352,9 +1354,9 @@ class TmuxCommands(unittest.TestCase):
return subprocess.CompletedProcess(args, 1 if fails else 0, "" if fails else "@9\n", "no such session\n" if fails else "")
return run
window = tmux.Window("loop-proj", "item-7", "")
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, answering(tmux.OWNER)), Failure("tmux started the session loop-proj but could not mark it as this checkout's: no such session"))
self.assertIsNone(tmux.start_window(window, "/r", {}, ["x"], True, answering("remain-on-exit")))
self.assertIsNone(tmux.start_window(window, "/r", {}, ["x"], False, answering(tmux.OWNER)))
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, True, answering(tmux.OWNER)), Failure("tmux started the session loop-proj but could not mark it as this checkout's: no such session"))
self.assertIsNone(tmux.start_window(window, "/r", {}, ["x"], True, True, answering("remain-on-exit")))
self.assertIsNone(tmux.start_window(window, "/r", {}, ["x"], False, True, answering(tmux.OWNER)))
def test_reads_the_checkout_the_session_names(self):
fake = FakeEffects(owner="/c/proj")
@@ -1511,6 +1513,11 @@ class StartChunks(unittest.TestCase):
self.assertEqual(self.starts(fake), [])
self.assertIn(["show-options", "-qv", "-t", f"={self.session}:", "@loop-root"], fake.tmux_calls)
def test_refuses_a_checkout_do_epic_runs_chunks_in(self):
fake = FakeEffects(windows=f"epic-ABC-12\tABC-34 ?\t0\t@4\t{self.root}\nepic-ABC-12\tABC-35\t0\t@5\t/c/other\nepic-ABC-12\tABC-36\t1\t@6\t{self.root}\nloop-x\titem-1\t0\t@7\t{self.root}\n")
self.assertEqual(self.start(fake), Failure(f"do-epic runs chunks in {self.root}: ABC-34 of epic-ABC-12; loop-claude starts none there until they finish"))
self.assertEqual(self.starts(fake), [])
def test_leaves_out_the_items_a_running_chunk_names_on_its_chunk_items_line(self):
self.limit(2)
transcripts = paths.paths_from(self.home).claude_code_transcripts
@@ -1634,14 +1641,14 @@ class Steps(unittest.TestCase):
before = Route(self.FABLE_LOW, 3, 3, 4)
with contextlib.redirect_stderr(io.StringIO()):
self.assertIsNone(write.archive(archive, str(transcript), "Do it.", outcomes.unfinished(before.worker_line(), "working", "j", ""), NOW))
after = close.closed_cycle(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_likelihood=4)), before), archive, a_loop(FakeEffects().effects(), session=opened))
after = close.closed_cycle(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_likelihood=4)), before), archive, prompts.DRIVER, a_loop(FakeEffects().effects(), session=opened))
self.assertEqual(chunk_start.archived_route(archive, a_loop(FakeEffects().effects(), session=opened)), Route(self.FABLE_MEDIUM, 3, 3, 4))
with contextlib.redirect_stderr(io.StringIO()):
close.closed_cycle(after, OPUS_PROJECT, run.Concluded(Finished("done"), after.route), archive, a_loop(FakeEffects().effects(), session=opened))
close.closed_cycle(after, OPUS_PROJECT, run.Concluded(Finished("done"), after.route), archive, prompts.DRIVER, a_loop(FakeEffects().effects(), session=opened))
self.assertEqual(chunk_start.archived_route(archive, a_loop(FakeEffects().effects(), session=opened)), Route(self.FABLE_MEDIUM, 3, 3, 4))
blocked = pathlib.Path(home, "blocked")
blocked.write_text("")
stop = close.closed_cycle(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_likelihood=4)), before), blocked, a_loop(FakeEffects().effects(), session=opened))
stop = close.closed_cycle(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_likelihood=4)), before), blocked, prompts.DRIVER, a_loop(FakeEffects().effects(), session=opened))
self.assertEqual((stop.code, stop.reason.split(":")[0]), (1, "could not archive the transcript"))
def test_names_no_step_up_where_only_the_count_of_unfinished_verdicts_changed(self):
@@ -1659,7 +1666,7 @@ class Steps(unittest.TestCase):
before = Route(self.FABLE_LOW, 3, 3, 4)
with contextlib.redirect_stderr(io.StringIO()):
self.assertIsNone(write.archive(archive, str(transcript), "Do it.", outcomes.unfinished(before.worker_line(), "working", "j", ""), NOW))
close.closed_cycle(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_escape_and_impact=6)), before), archive, a_loop(FakeEffects().effects(), session=opened))
close.closed_cycle(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_escape_and_impact=6)), before), archive, prompts.DRIVER, a_loop(FakeEffects().effects(), session=opened))
self.assertEqual(chunk_start.archived_route(archive, a_loop(FakeEffects().effects(), session=opened)), Route(self.FABLE_LOW, 3, 3, 4, escape_and_impact_taken_in=6))
+1 -1
View File
@@ -152,7 +152,7 @@ Valid while `~/.claude` is a checkout of this repo.
- **Ranking.** Score, then Blocked by, in one weight chain: the epic's achieve goals, then code health, then the repo's goals. Where the epic and a repo disagree, the epic wins. do-epic re-ranks Jira's backlog to match, and people's issues keep their rank.
- **Releases.** An epic item has no release. It ships into its repo's unreleased work: a bullet under `CHANGELOG.md` → `## Unreleased`, or nothing where the repo's plan is in Jira.
- **Repos.** A repo's name is its main checkout's folder name, and a project config names that checkout. A missing checkout is cloned from the host of the epic's other repos; where unsure, do-epic asks. Unsure means the other repos don't all sit under one host and owner (the same host spelt as https and as ssh counts as two), an origin can't be read or isn't an https, ssh or scp-style address, the folder to clone into holds something else, or the clone fails. A repo no config names is cloned into the clone folder, and the human is asked to write its config. Each chunk uses its repo's model, routing, and language for commits and PRs. Jira text is in the epic's language, or else the machine's default.
- **Running.** The epic caps the chunks running at once, and each repo's `parallel-chunks` still applies. do-epic and loop-claude never run chunks in the same repo at once.
- **Running.** The epic caps the chunks running at once, and each repo's `parallel-chunks` still applies. do-epic and loop-claude never run chunks in the same repo at once. The cap is a line of the epic's description, `**Max parallel chunks:** 2`, and 1 without it, as `parallel-chunks` is; three readers seated as the human who writes the description picked the spelling, 2-1 over `**Parallel chunks:**`. A repo's `parallel-chunks` counts the chunks of every epic in its checkout. Each window is named for its issue's key, and a tmux window option, `@chunk-root`, names the folder its chunk works in, which is how loop-claude sees do-epic's chunks in a checkout. Both hold the checkout's `starting` lock from that check to the start of a window. A chunk without a repo works in `~/.local/state/do-epic/<EPIC-KEY>/`. do-epic archives its cycles under `~/.claude/do-epic-transcripts/`, apart from loop-claude's, whose readers parse loop-claude's prompts. An open issue runs once a label records its repo; until do-epic picks repos itself, an issue without one waits, and `do-epic <EPIC-KEY>` says so.
- **Long gates.** A chunk whose PR waits on a gate, such as a human approval, parks. It keeps its worktree, PR and session, and its state is in a file that survives a reboot. A parked chunk takes no running slot, and the items it blocks wait. do-epic polls the forge and resumes the chunk's session when the gate passes or a reviewer comments. It fixes reasonable feedback, replies to the rest, and changes the setup so review would have caught it. `do-epic <key> --status` and the tmux window names show what each chunk waits on.
- **Human tasks.** do-epic DMs the human when one blocks the next item, and polls until its issue closes.
- **Findings.** A finding about the epic's goals is filed in the epic. A finding about a repo's goals follows that repo's rules. Where unsure which, do-epic asks. A set of new items toward an epic goal needs the human's approval before work starts; a finding filed during a chunk doesn't.
+12 -1
View File
@@ -6,7 +6,7 @@
`Bar = 0.1`
`Next ID = 439`
`Next ID = 440`
## Items
@@ -23,6 +23,7 @@
| 414 | 0.12.0 | 410 | | **DM the human through the notifier when a human-task issue blocks the epic's next item, and poll until it closes.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
| 417 | 0.12.0 | 410 | | **Run do-epic end to end against a sandbox epic on a real Jira site with a command of its own, outside `run-tests`.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
| 421 | 0.12.0 | | | **Refuse in rule-hook a Bash or Monitor wait that has no end: a loop without a time or count cap, and a `pgrep -f` or `pkill -f` whose pattern the same command line contains.** | 2 | 2 | 3 | 5 | 3 | 1.5 by 4 | 1.3 |
| 439 | 0.12.0 | 410 | | **Have `do-epic <EPIC-KEY>` split each open issue by repo, pick the repo of each issue that no label names one for, asking the human where unclear, and re-rank the epic, before it starts chunks.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
| 429 | 0.12.0 | | | **Bring nine lessons from a client setup into the principles, the reviewers, larv-review and the project config, and rank a deterministic tool first where an outside reviewer's finding changes the setup.** | 4 | 2 | 3 | 7 | 7 | 1.1 by 5, 1.6 by 5 | 0.9 |
| 310 | 0.12.0 | | | **Compact a waiting worker's session shortly before its prompt cache expires, only when the human has not answered an interrupt by then.** | 3 | 2 | 3 | 6 | 4 | 1.4 by 3 | 0.9 |
| 422 | 0.12.0 | 420 | | **Check every 5 minutes whether a tmux window of the loop looks stuck by other signs than a lingering worker, investigate it with a headless claude, and kill only the process the investigation names.** | 3 | 2 | 3 | 6 | 5 | 1.5 by 4 | 0.8 |
@@ -209,6 +210,16 @@ Touches:
- `bin/rule_hook/test_rule_hook.py`: `CommandBreaches` (small)
- `settings.json`
### 439. Have `do-epic <EPIC-KEY>` split each open issue by repo, pick the repo of each issue that no label names one for, asking the human where unclear, and re-rank the epic, before it starts chunks.
Today `do-epic <EPIC-KEY>` starts only an issue whose label already records its repo, and prints that every other one waits (`bin/do_epic/scheduler.py` → `chunks`). `split.split`, `repo_pick.picked` and `ranking` exist and nothing calls them. Each is a headless claude call on a rung: route it on `repoless-model`'s rung of the shipped ladder. An `Unclear` pick is an interrupt on the terminal of the `do-epic <EPIC-KEY>` the human runs. A chunk that finishes starts the next chunks without planning again, so no window waits on a question.
Touches:
- `bin/do_epic/main.py`: `windows_opened`, `chunks_started`
- `bin/do_epic/planning.py`
- `bin/do_epic/test_main.py`
### 429. Bring nine lessons from a client setup into the principles, the reviewers, larv-review and the project config, and rank a deterministic tool first where an outside reviewer's finding changes the setup.
Lessons from running this setup in a client's repo, shipped as one chunk. Each part names the gap it closes; none names the client, its code or its reviewers' text.