Merge remote-tracking branch 'origin/main' into item-417
CI / tests (pull_request) Has been cancelled

# Conflicts:
#	README.md
#	docs/reading-cost.md
This commit is contained in:
2026-11-19 05:20:20 +01:00
26 changed files with 712 additions and 134 deletions
+3
View File
@@ -2,6 +2,9 @@
## Unreleased
- loop-claude compacts a waiting worker's session 10 minutes before its hour-long prompt cache expires, where no answer to an interrupt has come and the context holds at least 60k tokens, so the resume doesn't write the whole context again.
- do-epic gives a `do-epic-human` issue that blocks another its own window: it DMs you once through the notifier of one of the epic's repos, takes no running slot, and polls until you close the issue in Jira, when the issues it held up may start.
- do-epic tells an epic chunk's worker how its repo ships the change: a bullet under the repo's changelog where the repo publishes something, none where its plan is in Jira, and no `--finish` for `chunk-pr merge`.
- `do-epic <EPIC-KEY> --status` says which chunk asks you a question, and since when each parked chunk has awaited its gate.
- do-epic moves a chunk's issue to done in Jira when the chunk finishes, and the split item it belongs to once its last sub-task is done, so no finished chunk starts again and the chunks it blocks start. It moves them by the transition `jira-finish-transition` and `jira-finish-status` name, so set both; without them a finishing chunk stops with that reason.
- Describe do-epic in the README: its entry under Tools, and its machine settings and `repo-rule.md` under Set up a project.
+1 -1
View File
@@ -190,7 +190,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `command-patterns [<version>] [--calls <file>]` prints a table of the shell command patterns a release's archived chunks ran, such as `tea pr create`, for an audit of the release, and with `--calls <file>` saves each call as a JSON line; `command-patterns --help` states the columns and the line's keys.
- `compress-archives` gzips each transcript in loop-claude's archive and each file in the review folders 30 days after it last changed, keeping all of them; Install's crontab line runs it daily.
- `deploy-release [--cut] [<checkout>]` moves `~/.claude`, or the checkout named, to the newest release, as Update says; with `--cut`, run in the development clone, it first cuts the next release, as Release says.
- `do-epic <EPIC-KEY>` runs the chunks of one Jira epic whose items span repos, or have none, each in its own window of the tmux session `epic-<EPIC-KEY>`, on the same cycle, judge and interrupt as loop-claude. The epic's description is its record: goals, audience, scoring and decisions. An open issue runs once a label names its repo, in Jira's backlog order, as many at once as a line such as `**Max parallel chunks:** 2` in the epic's description allows, 1 without it, and as each repo's `parallel-chunks` allows. A chunk whose pull request waits on a gate parks. do-epic closes the epic only once you confirm every goal. Install → "Set up a project" says how to set it up; `do-epic --help` states the flags and the contract.
- `do-epic <EPIC-KEY>` runs the chunks of one Jira epic whose items span repos, or have none, each in its own window of the tmux session `epic-<EPIC-KEY>`, on the same cycle, judge and interrupt as loop-claude. The epic's description is its record: goals, audience, scoring and decisions. An open issue runs once a label names its repo, in Jira's backlog order, as many at once as a line such as `**Max parallel chunks:** 2` in the epic's description allows, 1 without it, and as each repo's `parallel-chunks` allows. A chunk whose pull request waits on a gate parks. An open task of yours that blocks another issue gets a window that DMs you once and reads the epic every minute; once you close the task, the issues it blocked may start. do-epic closes the epic only once you confirm every goal. Install → "Set up a project" says how to set it up; `do-epic --help` states the flags and the contract.
- `do-epic-e2e` runs `do-epic` against a sandbox epic on a real Jira site, as Test says.
- `judge-replay <model> [--offline]` replays loop-claude's judge on archived verdicts of the projects run on the model. It prints what each rung a review climbs to misses, and the lowest rung below those that returns every verdict, as each candidate above it does. With `--offline` it doesn't call a judge: it counts what a "?" rule, a decision table and a classifier trained on the archive decide of each verdict's kind from the worker's final message, and how many interrupts each misses. `judge-replay --help` states both replays.
- `larv-review <command>` holds larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's round count and the opening of its round commit's title, the scoring run's trigger and setup; the comprehension history's format, its latest places and its count of how often seats agree; and each reviewer's prompt header. `larv-review --help` states them. `settings.json` → `hooks` runs `larv-review reviewer-context` as each subagent starts. A reviewer under `agents/` whose frontmatter has `omitClaudeMd: true` starts without `CLAUDE.md`, and the command hands it that file's "Shared goal", "Prose" and "Vocabulary" sections.
+4 -3
View File
@@ -1,7 +1,8 @@
from loop_effects.effects import Effects, say
def tell(text: str, effects: Effects) -> None:
"""DMs text to the human. Where the DM fails, it says why on stderr and goes on: the DM only copies what the terminal shows, so its failure never stops the loop."""
if failed := effects.dm(text):
def tell(text: str, effects: Effects, directory: str | None = None) -> bool:
"""DMs text to the human through the notifier of the project whose checkout holds directory, else the current directory, and returns whether it went out. Where the DM fails, it says why on stderr and goes on: the DM only copies what the terminal shows, so its failure never stops the loop."""
if failed := effects.dm(text, directory):
say(f"could not DM you: {failed.reason}", effects)
return not failed
+57 -1
View File
@@ -1,21 +1,30 @@
import dataclasses
import datetime
import sys
import typing
import uuid
from claude_code.entries import AssistantTurn, Entry
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 claude_code.reply import Limited
from agent_cycle.stop import needs_human, needs_terminal, Stop
from agent_cycle.worker import run_claude
from model_routing.ladder import Rung
from agent_cycle.direct_message import tell
from agent_cycle import tmux
from claude_code.tokens import tokens_of
ANSWER_QUESTION = "answer the question above"
# TALK, what the human types at the entry point'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.
TALK = "/talk"
ASK_ANSWER = f"Answer ({TALK} opens claude, Enter stops the loop): "
# While the human hasn't answered, the worker's session is compacted CACHE_MARGIN seconds before its hour-long prompt cache expires: compacting reads the context from the cache, while resuming after it expired writes the whole context again. Below COMPACT_FLOOR tokens of context, that write costs less than compacting. A five-minute cache expires within the margin, so a session that last wrote one isn't compacted. lilleman chose this on 2026-11-11.
HOUR_CACHE = 3600
CACHE_MARGIN = 600
COMPACT_FLOOR = 60_000
@dataclasses.dataclass(frozen=True)
@@ -24,6 +33,8 @@ class WorkerSession:
root: str
id: uuid.UUID
rung: Rung
# The rung the worker last ran on: below rung where the ruling that interrupts stepped the worker up.
ran_on: Rung
transcript_path: str
# Added to the environment of the worker's claude, and of the claude /talk opens.
env: dict[str, str]
@@ -57,12 +68,57 @@ def interrupt(question: str, answer_here: bool, session: WorkerSession, window:
def answered(answer_here: bool, session: WorkerSession, effects: Effects) -> str | Talked | Stop:
"""The human's answer, as interrupt returns it."""
answer = typed_answer(effects) if answer_here else TALK
answer = waited_answer(session, effects) if answer_here else TALK
if answer != TALK:
return answer
return human_typed(session.transcript_path, lambda: claude_open(session, effects)) or Talked()
def waited_answer(session: WorkerSession, effects: Effects) -> str | Stop:
"""typed_answer, compacting the worker's session where no answer has come by CACHE_MARGIN seconds before its prompt cache expires. /talk needs no compaction: the claude it opens compacts an idle session itself."""
entries = read_transcript(session.transcript_path)
now = effects.now()
delay = None if isinstance(entries, Failure) else compaction_delay(entries, now)
if delay is None:
return typed_answer(effects)
stop_timer = effects.timer(delay, lambda: compact(session, now + delay + CACHE_MARGIN, effects))
try:
return typed_answer(effects)
finally:
# Waits for a compaction under way, so the worker doesn't resume the session while it is compacted.
stop_timer()
def compaction_delay(entries: list[Entry], now: float) -> float | None:
"""Seconds from now until CACHE_MARGIN before the session's prompt cache expires. None where its context is under COMPACT_FLOOR tokens, its cache lasts five minutes, or the margin has begun."""
turns = [entry for entry in entries if isinstance(entry, AssistantTurn) and entry.usage]
if not turns or tokens_of(turns[-1].usage).context() < COMPACT_FLOOR:
return None
# A read refreshes the cache for the lifetime it was written with.
written = next((tokens for turn in reversed(turns) if (tokens := tokens_of(turn.usage)).write_5m or tokens.write_1h), None)
if written is None or not written.write_1h:
return None
try:
last_read = datetime.datetime.fromisoformat(turns[-1].timestamp).timestamp()
except ValueError:
return None
delay = last_read + HOUR_CACHE - CACHE_MARGIN - now
return delay if delay > 0 else None
def compact(session: WorkerSession, expires: float, effects: Effects) -> None:
"""Compacts the worker's session with `claude -p /compact`, saying that it starts and how it went. Each line opens on a line of its own, below the open ASK_ANSWER. From expires on, when the prompt cache has expired, it doesn't do anything: a timer fires late where the machine was suspended."""
if effects.now() >= expires:
return
say("\ncompacting the worker's claude session before its prompt cache expires; an answer typed meanwhile is read once that ends", effects)
# On the rung the worker ran on, not the one a ruling stepped it up to: the prompt cache is kept per model, and another effort may miss it too, so another rung would read the whole context at full price. Without run_worker's wait for memory, which could outlast the cache.
outcome = run_claude(session.root, claude_args(session.ran_on, ["-p", "/compact", "--resume", str(session.id), "--output-format", "stream-json", "--verbose"]), session.env, effects)
if outcome is None:
say("\ncompacted the worker's claude session", effects)
else:
say(f"\ncould not compact the worker's claude session: {outcome.said if isinstance(outcome, Limited) else outcome.reason}", effects)
def typed_answer(effects: Effects) -> str | Stop:
"""The line typed at the entry point's terminal, stripped. A Stop where they type no answer, or the input ends."""
try:
+10 -10
View File
@@ -75,8 +75,8 @@ def run_cycle(cycle: Cycle) -> Stop | Concluded:
if isinstance(event, Stop):
return stopped(cycle, event, event.reason)
# Only a ruling's step-up changes the route within a cycle, here, once rule has archived the ruling on the route before it. No transition reads the current route, so Cycle holds it, not the states.
if isinstance(event, Ruled) and event.stepped_to:
cycle = dataclasses.replace(cycle, route=event.stepped_to)
if isinstance(event, Ruled) and event.stepped:
cycle = dataclasses.replace(cycle, route=event.stepped.after)
state = transition(state, event)
except KeyboardInterrupt:
return stopped(cycle, Stop(130, ""), "Ctrl-C")
@@ -110,8 +110,8 @@ def step(cycle: Cycle, state: Active) -> Event | Stop:
return work(cycle, answered, stepped)
case Judging(transcript_path, quoted_answers):
return rule(cycle, transcript_path, quoted_answers)
case Interrupting(transcript_path, ruling, _, _):
return ask(cycle, transcript_path, ruling)
case Interrupting(transcript_path, ruling, _, stepped_from):
return ask(cycle, transcript_path, ruling, stepped_from)
case Closing(transcript_path, verdict):
return close(cycle, transcript_path, verdict)
case _:
@@ -133,8 +133,8 @@ def worker_environment(cycle: Cycle) -> dict[str, str]:
return {**worker_rungs.environment(cycle.project, cycle.route), AUTO_COMPACT_WINDOW: str(COMPACT_WINDOW), BASH_CEILING: str(BASH_CEILING_CHARACTERS)}
def worker_session(cycle: Cycle, transcript_path: str) -> WorkerSession:
return WorkerSession(cycle.root, cycle.session.id, cycle.route.rung, transcript_path, worker_environment(cycle))
def worker_session(cycle: Cycle, transcript_path: str, stepped_from: Rung | None) -> WorkerSession:
return WorkerSession(cycle.root, cycle.session.id, cycle.route.rung, stepped_from or cycle.route.rung, transcript_path, worker_environment(cycle))
def worker_start(cycle: Cycle, answered: QuotedAnswer | TypedAnswer | None, stepped: bool) -> list[str]:
@@ -175,7 +175,7 @@ def rule(cycle: Cycle, transcript_path: str, quoted_answers: int) -> Ruled | Sto
stepped = ruling_step_up(cycle, verdict)
if failure := archive_stepped(cycle, transcript_path, ruling_outcome(cycle, verdict, quoted_answers, annotation), stepped, verdict.judged.run):
return Stop(1, failure.reason)
return Ruled(verdict, stepped.after if stepped else None)
return Ruled(verdict, stepped)
def annotation_of(cycle: Cycle, transcript_path: str, entries: list[Entry], judged: Judged) -> outcomes.Annotation | Failure:
@@ -204,10 +204,10 @@ def keep_rejection(cycle: Cycle, transcript_path: str, rejected: Rejected) -> St
return None
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."""
def ask(cycle: Cycle, transcript_path: str, ruling: Interrupt | QuotedAnswer, stepped_from: Rung | None) -> HumanTyped | HumanTalked | Stop:
"""The human's answer to a ruling that rule archived as it ruled; the human's answer then grows the transcript. stepped_from is the rung the worker ran on, where the ruling stepped it up."""
# Only the human may cut a release, so a release ready to cut opens claude's session at once.
answer = interrupt(question_for(cycle, ruling), not (isinstance(ruling, Interrupt) and ruling.release_ready), worker_session(cycle, transcript_path), cycle.window, cycle.prompts.driver, cycle.effects)
answer = interrupt(question_for(cycle, ruling), not (isinstance(ruling, Interrupt) and ruling.release_ready), worker_session(cycle, transcript_path, stepped_from), cycle.window, cycle.prompts.driver, cycle.effects)
match answer:
case Stop():
return answer
+12 -11
View File
@@ -1,7 +1,8 @@
import dataclasses
from agent_cycle.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
from model_routing.route import Route
from model_routing.ladder import Rung
from agent_cycle.routing import StepUp
# 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.
QUOTED_ANSWERS_PER_CYCLE = 3
@@ -36,8 +37,8 @@ class Interrupting:
transcript_path: str
ruling: Interrupt | QuotedAnswer
quoted_answers: int = 0
# Whether the ruling stepped the worker up a rung. It holds through the answer the human types, and drops on /talk.
stepped: bool = False
# The rung the worker ran on, where the ruling stepped it up from there; None where the rung holds. It holds through the answer the human types, and drops on /talk.
stepped_from: Rung | None = None
@dataclasses.dataclass(frozen=True)
@@ -63,8 +64,8 @@ class WorkerRan:
@dataclasses.dataclass(frozen=True)
class Ruled:
verdict: Verdict
# The route an interrupt's or a quoted answer's escalation stepped the worker up to, which the cycle runs on from here; None where the route holds, and always for a finished or unfinished verdict.
stepped_to: Route | None = None
# The step-up an interrupt's or a quoted answer's escalation made, whose `after` the cycle runs on from here; None where the route holds, and always for a finished or unfinished verdict.
stepped: StepUp | None = None
@dataclasses.dataclass(frozen=True)
@@ -94,14 +95,14 @@ def transition(state: State, event: Event) -> State:
match state, event:
case Working(_, quoted_answers), WorkerRan(transcript_path):
return Judging(transcript_path, quoted_answers)
case Judging(transcript_path, quoted_answers), Ruled(Interrupt() | QuotedAnswer() as ruling, stepped_to) if to_the_human(ruling, quoted_answers):
return Interrupting(transcript_path, ruling, quoted_answers, stepped_to is not None)
case Judging(_, quoted_answers), Ruled(QuotedAnswer() as answered, stepped_to):
return Working(answered, quoted_answers + 1, stepped_to is not None)
case Judging(transcript_path, quoted_answers), Ruled(Interrupt() | QuotedAnswer() as ruling, stepped) if to_the_human(ruling, quoted_answers):
return Interrupting(transcript_path, ruling, quoted_answers, stepped.before.rung if stepped else None)
case Judging(_, quoted_answers), Ruled(QuotedAnswer() as answered, stepped):
return Working(answered, quoted_answers + 1, stepped is not None)
case Judging(transcript_path, _), Ruled(Finished() | Unfinished() as verdict):
return Closing(transcript_path, verdict)
case Interrupting(_, _, quoted_answers, stepped), HumanTyped(typed):
return Working(typed, quoted_answers, stepped)
case Interrupting(_, _, quoted_answers, stepped_from), HumanTyped(typed):
return Working(typed, quoted_answers, stepped_from is not None)
# The human worked in the worker's claude session, so the judge rules again on the transcript it leaves.
case Interrupting(transcript_path, _, quoted_answers), HumanTalked():
return Judging(transcript_path, quoted_answers)
+5
View File
@@ -17,6 +17,11 @@ COMPACT_WINDOW = 200_000
def run_worker(root: str, args: list[str], env: dict[str, str], effects: Effects) -> Failure | Limited | None:
wait_for_memory(effects)
return run_claude(root, args, env, effects)
def run_claude(root: str, args: list[str], env: dict[str, str], effects: Effects) -> Failure | Limited | None:
"""Runs a headless claude at once, printing what it says, and returns how it failed, or None."""
try:
proc = effects.stream_claude(args, root, env)
except OSError as failure:
+4
View File
@@ -13,6 +13,10 @@ class Tokens:
read: int = 0
output: int = 0
def context(self) -> int:
"""The tokens of the prompt the message answered: its context."""
return self.input + self.write_5m + self.write_1h + self.read
def plus(self, other: "Tokens") -> "Tokens":
return Tokens(*(mine + theirs for mine, theirs in zip(dataclasses.astuple(self), dataclasses.astuple(other))))
+14 -3
View File
@@ -6,6 +6,7 @@ from do_epic import findings
from loop_claude.project.records import HUMAN_RULE_NAMES, RECORD_FILES
from text_files.markdown_text import listed
import pathlib
from project_config.settings import ProjectConfig
from model_routing.ladder import ProjectRung
from loop_claude.cycle import prompts
from model_routing.route import Route
@@ -15,10 +16,20 @@ from agent_cycle.worker_prompts import WorkerPrompts
DRIVER = "do-epic"
def task(issue: EpicIssue, epic: str, checkout: str | None, launcher: pathlib.Path, language: str) -> 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. launcher is the do-epic that runs the chunk, and language the one the epic's Jira text is in."""
def shipping(config: ProjectConfig) -> str:
"""How a chunk in the repo that config names ships its change. An epic's issue isn't an item of the repo's plan, so `chunk-pr merge --finish`, which adds a finished item's changelog bullet, doesn't apply: the worker writes the bullet itself, where the repo publishes something others consume (docs/decisions.md → `do-epic: drives one Jira epic …`, "Releases")."""
opening = "The issue isn't an item of the repo's plan, so run `chunk-pr merge` without `--finish`."
if config.epic:
return f"{opening} The repo's plan is a Jira epic, and the history of its issues serves as the changelog, so leave the changelog as it is."
changelog = config.paths["changelog"].relative_to(config.top) if "changelog" in config.paths and config.paths["changelog"].is_relative_to(config.top) else config.places["changelog"]
return f"{opening} Where the repo publishes something others consume, add one bullet to `## Unreleased` in `{changelog}` that tells the repo's consumers what changed; otherwise leave the changelog as it is."
def task(issue: EpicIssue, epic: str, checkout: str | None, launcher: pathlib.Path, language: str, config: ProjectConfig | 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. launcher is the do-epic that runs the chunk, language the one the epic's Jira text is in, and config the project config of the repo's checkout, None without a repo."""
shipped = shipping(config) if config else ""
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}. {findings.instructions(epic, launcher, language)} Its summary: {issue.summary}" + (f"\n\nIts description:\n\n{issue.detail}" if issue.detail else "")
return f"Work the Jira issue {issue.key} of the epic {epic} as one chunk, {where}. {" ".join(filter(None, [findings.instructions(epic, launcher, language), shipped]))} Its summary: {issue.summary}" + (f"\n\nIts description:\n\n{issue.detail}" if issue.detail else "")
CODE_HEALTH = '~/.claude/CLAUDE.md → "Shared goal"'
+60
View File
@@ -0,0 +1,60 @@
"""A human's task that holds up other issues of an epic (docs/decisions.md → `do-epic: drives one Jira epic …`, "Human tasks").
A window that starts again, as after a reboot, DMs again, and so does one whose DM failed, on its next read."""
import pathlib
from project_config.settings import by_name, ProjectConfig
from loop_effects.effects import Effects, say
from do_epic.backend.protocol import EpicIssue, EpicStore
from failure import Failure
from do_epic.repo_pick import recorded, Repo
from do_epic import scheduler
from agent_cycle.direct_message import tell
from agent_cycle import tmux
# What the window of a human's task awaits, in its name.
AWAITS = "a human's task"
def holds_up(key: str, issues: list[EpicIssue]) -> list[str]:
"""The keys of the open issues that the human's task called key holds up; none where it is no such task, is closed, or an issue blocks it."""
if not any(chunk.human and chunk.issue == key for chunk in scheduler.chunks(issues)[0]):
return []
return scheduler.held_up(issues)[key]
def message(task: EpicIssue, epic: str, held: list[str]) -> str:
return f"do-epic {epic} awaits you: {task.key}, \"{task.summary}\", blocks {' and '.join(held)}. do-epic goes on once you close {task.key} in Jira."
def notifier_checkout(issues: list[EpicIssue], home: pathlib.Path) -> str | None:
"""The checkout of the first of issues whose repo has a git checkout and a project config that names a notifier: where the DM finds that notifier, since the window runs in no checkout. None where there is none."""
for issue in issues:
pick = recorded(issue)
found = by_name(pick.name, home) if isinstance(pick, Repo) else None
if isinstance(found, ProjectConfig) and found.notifier and (found.top / ".git").exists():
return str(found.top)
return None
def awaited(task: EpicIssue, epic: str, store: EpicStore, window: tmux.Window, poll: int, home: pathlib.Path, effects: Effects) -> None:
"""Waits in window for the human to close the human's task `task` of the epic called epic, and returns once it no longer holds up any issue. A read of the epic that fails is said once and tried again."""
tmux.park(window, AWAITS, effects.tmux)
told, said = False, None
while True:
issues = store.read()
if isinstance(issues, Failure):
if issues.reason != said:
say(f"cannot read the epic, so cannot tell whether {task.key} is closed; trying again every {poll} seconds: {issues.reason}", effects, stdout=True)
said = issues.reason
elif not (held := holds_up(task.key, issues)):
return
elif not told:
text = message(task, epic, held)
say(text, effects, stdout=True)
# The issues it holds up come first; any other issue of the epic may do where they have no repo with a notifier.
where = notifier_checkout(sorted(issues, key=lambda issue: issue.key not in held), home)
if where is None:
say("no DM went out: no issue of the epic has a repo whose project config names a notifier and whose checkout exists", effects, stdout=True)
told = where is None or tell(text, effects, where)
effects.sleep(poll)
+21 -12
View File
@@ -1,6 +1,6 @@
"""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, run by the code that runs loop-claude's (`agent_cycle`), until the judge rules it finished. Then it starts the chunks that may start now, and its window closes.
`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, run by the code that runs loop-claude's (`agent_cycle`), until the judge rules it finished. Then it starts the chunks that may start now, and its window closes. The window of a human's task runs no cycle: it waits until the task no longer holds up an issue (`human_tasks`), then does the same.
After each cycle of a chunk in a repo, the window reads what the chunk's pull request waits on (`gates`). While that is a gate only time or a person passes, the chunk is parked (`parked`): the window frees its running slot and polls the forge, and the chunk's next cycle starts once the worker has something to do and a slot is free. `do-epic <EPIC-KEY> --status` prints what each open issue does."""
import dataclasses
@@ -9,9 +9,10 @@ import sys
import typing
from loop_claude.loop.chunk_start import archived_route, routed
from do_epic import chunk_prompt, findings, finish, gates, parked, scheduler, split, status
from do_epic import chunk_prompt, findings, finish, gates, human_tasks, parked, scheduler, split, status
from do_epic.repo_pick import ClaudeWork, HumanTask, recorded, Repo
from loop_claude.loop.close import closed_cycle
from project_config.main import located as config_located
from loop_claude.project.records import CONSEQUENCE, read_records
from agent_cycle.run import Cycle, run_cycle
from do_epic.config import DoEpicConfig, load
@@ -47,6 +48,7 @@ HELP = f"""usage: do-epic <EPIC-KEY> [--status]
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 runs as a chunk once it has a label and no issue blocks it.
The label names the issue's repo, or says the work changes no repo.
A `do-epic-human` issue that blocks another gets a window too. The window DMs you once, then waits without taking a place until you close the issue in Jira.
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.
A chunk whose worker ends its run while its pull request waits on its checks, an approval or a new review
@@ -61,7 +63,7 @@ The Jira site and its credentials are set in ~/.claude-projects/do-epic/config.t
ARCHIVE = ".claude/do-epic-transcripts"
# The flag that prints what each open issue does.
STATUS_FLAG = "--status"
# How often a parked chunk reads its pull request's gate: a reviewer answers in hours, and each read is three or four calls to the forge.
# How often a parked chunk reads its pull request's gate, and a human task's window reads the epic: a person answers in hours, and each read is a few calls.
POLL_SECONDS = 60
# The store of an epic's issues and its record, for the epic with this key.
@@ -224,11 +226,18 @@ def real(checkout: pathlib.Path) -> pathlib.Path:
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. A chunk in a repo parks after each cycle that leaves its pull request waiting on a gate, and before its first where it was parked when its window last ended, as at a reboot."""
"""Runs the cycles of the chunk of the issue called key until one stops the loop, or the judge rules the chunk finished. For a human's task it runs no cycle: it waits until the task no longer holds up an issue (`human_tasks.awaited`), then starts the next chunks. A chunk in a repo parks after each cycle that leaves its pull request waiting on a gate, and before its first where it was parked when its window last ended, as at a reboot."""
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>")
place = chunk_root(key, epic)
# None for the epic's finishing, which is no issue.
issue = None if key == epic.key else issue_read(key, epic)
if isinstance(issue, Stop):
return issue
if issue and isinstance(recorded(issue), HumanTask):
human_tasks.awaited(issue, epic.key, epic.store, tmux.Window(epic.session, key, pane), POLL_SECONDS, epic.paths.home, epic.effects)
return handed_on(key, epic)
place = chunk_root(key, issue, epic)
if isinstance(place, Stop):
return place
root, repo = place
@@ -330,11 +339,8 @@ def issue_read(key: str, epic: EpicRun) -> EpicIssue | Stop:
return found[0] if found else Stop(1, f"{key} is no issue of the epic {epic.key}")
def chunk_root(key: str, epic: EpicRun) -> tuple[str, str | None] | Stop:
"""The folder the chunk called key works in, and the name of the repo whose checkout it is: None for the epic's folder, which holds work without a repo, as the epic's finishing is. The chunk keeps both to its end, whatever its issue's labels become. The stop where the labels make the issue no chunk."""
issue = None if key == epic.key else issue_read(key, epic)
if isinstance(issue, Stop):
return issue
def chunk_root(key: str, issue: EpicIssue | None, epic: EpicRun) -> tuple[str, str | None] | Stop:
"""The folder the chunk called key works in, and the name of the repo whose checkout it is: None for the epic's folder, which holds work without a repo, as the epic's finishing is. issue is None for the epic's finishing. The chunk keeps both to its end, whatever its issue's labels become. The stop where the labels make the issue no chunk."""
pick = recorded(issue) if issue else ClaudeWork()
if isinstance(pick, Failure):
return Stop(1, pick.reason)
@@ -343,7 +349,7 @@ def chunk_root(key: str, epic: EpicRun) -> tuple[str, str | None] | Stop:
folder.mkdir(parents=True, exist_ok=True)
return str(folder), None
if not isinstance(pick, Repo):
return Stop(1, f"{key} is no chunk: {'it is a human\'s task' if isinstance(pick, HumanTask) else 'no label names its repo'}")
return Stop(1, f"{key} is no chunk: no label names its repo")
found = locate(pick.name, [], epic.config, epic.paths.home, epic.effects.git)
return Stop(1, found.reason) if isinstance(found, Failure) else (str(real(found.checkout)), pick.name)
@@ -417,7 +423,10 @@ def chunk_work(key: str, checkout: str | None, language: str, epic: EpicRun) ->
issue = issue_read(key, epic)
if isinstance(issue, Stop):
return issue
return chunk_prompt.task(issue, epic.key, checkout, epic.launcher, language), RoutingIssue(issue) if "L" in issue.scores else None
config = config_located(checkout, epic.paths.home) if checkout else None
if isinstance(config, Failure):
return Stop(1, config.reason)
return chunk_prompt.task(issue, epic.key, checkout, epic.launcher, language, config), RoutingIssue(issue) if "L" in issue.scores else None
issues = epic.store.read()
if isinstance(issues, Failure):
return Stop(1, issues.reason)
+33 -7
View File
@@ -19,6 +19,8 @@ from agent_cycle import tmux
# 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"
# Why a human's task with a live window waits, as the epic's status says.
HUMAN_WAIT = "it is a human's task; do-epic polls Jira until you close it"
# 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"
@@ -29,6 +31,8 @@ class Chunk:
issue: str
# The name of the repo it changes; None for work without a repo.
repo: str | None
# Whether it is a human's task that holds up another open issue: its window only waits for the human to close the issue (`human_tasks`), and doesn't take a running slot.
human: bool = False
@dataclasses.dataclass(frozen=True)
@@ -76,22 +80,41 @@ class Epic:
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 until the human removes the link, since its state is unknown."""
def open_blockers(issue: EpicIssue, by_key: dict[str, EpicIssue]) -> list[str]:
"""The keys of the issues that block issue, or its parent, that are not done. A blocker outside the epic counts, since its state is unknown."""
parent = by_key.get(issue.parent)
return [key for key in (*issue.blockers, *(parent.blockers if parent else ())) if key not in by_key or not by_key[key].done]
def held_up(issues: list[EpicIssue]) -> dict[str, list[str]]:
"""Each blocker's key, mapped to the keys of the open issues it holds up, in the tracker's rank order. A split item's blocker holds up the item's sub-tasks."""
by_key = {issue.key: issue for issue in issues}
held: dict[str, list[str]] = {}
for issue in issues:
if not issue.done and SPLIT_LABEL not in issue.labels:
for key in open_blockers(issue, by_key):
held.setdefault(key, []).append(issue.key)
return held
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 until the human removes the link, since its state is unknown. A human's task gets a window only while it holds up another issue and nothing holds it up; that window waits for the human."""
by_key = {issue.key: issue for issue in issues}
holding = held_up(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]
blocking = open_blockers(issue, by_key)
outside = [key for key in blocking if key not in by_key]
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) and not blocking and issue.key in holding:
found.append(Chunk(issue.key, None, human=True))
elif isinstance(pick, HumanTask):
waits.append(Waits(issue.key, "it is a human's task"))
elif blocking:
@@ -131,11 +154,14 @@ def start_chunks(epic: Epic, issues: list[EpicIssue], finishing: bool, own: str
for chunk in found:
if chunk.issue in running or chunk.issue == own:
continue
if chunk.issue in parked and chunk.issue in live:
slot = chunk.issue not in parked and not chunk.human
if chunk.human and chunk.issue in live:
waits.append(Waits(chunk.issue, HUMAN_WAIT))
elif chunk.issue in parked and chunk.issue in live:
waits.append(Waits(chunk.issue, parked[chunk.issue].waits(live[chunk.issue].awaits)))
elif own and (chunk.issue in stopped or chunk.issue in parked):
waits.append(Waits(chunk.issue, f"its window stopped; run `do-epic {epic.key}` to start it again"))
elif chunk.issue not in parked and len(running) + taken >= epic.cap:
elif slot and len(running) + taken >= 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 if chunk.issue not in parked else Chunk(chunk.issue, None), own, windows, run)
@@ -146,7 +172,7 @@ def start_chunks(epic: Epic, issues: list[EpicIssue], finishing: bool, own: str
else:
windows = now
started.append(chunk.issue)
taken += chunk.issue not in parked
taken += slot
except OSError as failure:
return Failure(f"cannot lock {failure.filename or epic.folder / LOCK}: {failure.strerror}")
# The epic's finishing is no issue: its wait is listed after every issue's.
+4 -2
View File
@@ -2,7 +2,7 @@
import datetime
import pathlib
from do_epic.scheduler import chunks, STATE
from do_epic.scheduler import chunks, HUMAN_WAIT, STATE
from do_epic.backend.protocol import EpicIssue
from failure import Failure
from do_epic.parked import file_of, Parked, parked_chunks, SLOT
@@ -36,8 +36,10 @@ def lines(key: str, home: pathlib.Path, issues: list[EpicIssue], run: tmux.Tmux)
when = "" if shown == SLOT else since(folder, parked[chunk.issue])
stopped = "" if chunk.issue in live else f", and its window stopped; {again}"
reasons[chunk.issue] = parked[chunk.issue].waits(shown) + when + stopped
elif chunk.human and chunk.issue in live:
reasons[chunk.issue] = HUMAN_WAIT
elif chunk.issue not in live:
reasons[chunk.issue] = f"its window stopped; {again}" if chunk.issue in {window.name for window in windows} else f"it has not started; `do-epic {key}` starts it once the epic and its repo have room"
reasons[chunk.issue] = f"its window stopped; {again}" if chunk.issue in {window.name for window in windows} else f"it has not started; `do-epic {key}` starts it" + ("" if chunk.human else " once the epic and its repo have room")
return [line(issue.key, reasons, live, session) for issue in issues if issue.key in reasons or issue.key in live]
+166
View File
@@ -0,0 +1,166 @@
import dataclasses
import pathlib
import shutil
import sys
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from project_config.test_project_config import configured
from do_epic.test_main import DESCRIPTION, Description, DoEpicTest, MODELS, UNREAD
from do_epic.epic_record import EpicRecord
from failure import Failure
from loop_claude.test_loop_claude import FakeEffects
from do_epic.scheduler import HUMAN_WAIT
from do_epic.test_scheduler import issue
from do_epic.backend.fake import MemoryEpic
# The window of ABC-19, a human's task that blocks ABC-21.
WINDOW = "ABC-19\t0\t@9\n"
class AHumanTaskThatBlocksAnIssue(DoEpicTest):
def setUp(self) -> None:
super().setUp()
self.issues = [issue("ABC-19", "do-epic-human"), issue("ABC-21", "repo:api", blockers=("ABC-19",))]
self.issues[0] = dataclasses.replace(self.issues[0], summary="Order the test certificate")
self.epic = MemoryEpic("ABC-12", self.issues)
self.backend = lambda config, key: (self.epic, EpicRecord(Description(self.description))) # type: ignore[method-assign, arg-type]
self.api = self.repo("api", notifier=True)
def repo(self, name: str, notifier: bool) -> pathlib.Path:
"""Makes the checkout of the repo called name that a project config names, with a notifier where notifier."""
checkout = self.home / "code" / name
folder = configured(self, checkout, home=self.home)
if notifier:
with (folder / "config.toml").open("a") as config:
config.write('env-file = "~/.claude-projects/notifier.env"\nnotifier = "slack"\n')
return checkout
def awaited(self, fake: FakeEffects, closes_after: int) -> tuple[int, str, str]:
"""The window's run, where the human closes the task once the window has slept closes_after times."""
slept: list[int] = []
def sleep(seconds: int) -> None:
slept.append(seconds)
if len(slept) == closes_after:
self.epic.change("ABC-19", done=True, status="Done")
fake.effects = lambda made=fake.effects(): dataclasses.replace(made, sleep=sleep) # type: ignore[method-assign]
self.slept = slept
return self.run_main(["--chunk", "ABC-19", "ABC-12"], fake, MODELS)
def test_dms_the_human_once_parks_its_window_and_polls_until_the_issue_closes_then_starts_the_next(self) -> None:
fake = FakeEffects(git=UNREAD, windows=WINDOW)
code, out, err = self.awaited(fake, closes_after=3)
self.assertEqual((code, err), (0, ""))
self.assertEqual(self.slept, [60, 60, 60])
self.assertEqual(len(fake.dms), 1)
for fact in ("ABC-12", "ABC-19", "Order the test certificate", "ABC-21"):
self.assertIn(fact, fake.dms[0])
self.assertEqual([args for args in fake.tmux_calls if args[0] == "rename-window"], [["rename-window", "-t", "%1", "ABC-19 awaits a human's task"]])
self.assertIn("the chunk finished; started ABC-21\n", out)
self.assertEqual([seam for seam, _ in fake.calls if seam == "stream_claude"], [])
self.assertEqual(fake.dm_directories, [str(self.api)])
self.assertIn(fake.dms[0], out)
def test_a_dm_that_failed_is_sent_again_on_the_next_read(self) -> None:
fake = FakeEffects(git=UNREAD, windows=WINDOW, dm_failures=[Failure("the notifier answered 503")])
self.awaited(fake, closes_after=2)
self.assertEqual(len(fake.dms), 2)
def test_the_dm_goes_through_the_notifier_of_the_repo_of_an_issue_it_holds_up_before_any_other_repo(self) -> None:
self.repo("web", notifier=True)
self.epic.issues.append(issue("ABC-40", "repo:web"))
fake = FakeEffects(git=UNREAD, windows=WINDOW)
self.awaited(fake, closes_after=1)
self.assertEqual(fake.dm_directories, [str(self.api)])
def test_the_dm_goes_through_the_notifier_of_another_open_issues_repo_where_the_held_up_issue_has_none(self) -> None:
self.epic.change("ABC-21", labels=("do-epic-claude",))
self.epic.issues.append(issue("ABC-40", "repo:api"))
fake = FakeEffects(git=UNREAD, windows=WINDOW)
self.awaited(fake, closes_after=1)
self.assertEqual(fake.dm_directories, [str(self.api)])
def test_says_in_the_window_that_no_dm_went_out_where_no_repo_of_the_epic_names_a_notifier(self) -> None:
self.epic.change("ABC-21", labels=("repo:web",))
self.repo("web", notifier=False)
shutil.rmtree(self.api)
fake = FakeEffects(git=UNREAD, windows=WINDOW)
code, out, err = self.awaited(fake, closes_after=1)
self.assertEqual((code, err, fake.dms), (0, "", []))
self.assertEqual(out.count("<1790000000> no DM went out"), 1, out)
def test_the_window_of_a_closed_task_goes_on_while_another_human_task_still_holds_an_issue_up(self) -> None:
self.epic.issues.extend([issue("ABC-30", "do-epic-human"), issue("ABC-31", "do-epic-claude", blockers=("ABC-30",))])
fake = FakeEffects(git=UNREAD, windows=WINDOW)
code, out, err = self.awaited(fake, closes_after=1)
self.assertEqual((code, err), (0, ""))
self.assertEqual(len(fake.dms), 1)
self.assertIn("the chunk finished; started ABC-21, ABC-30\n", out)
def test_the_window_leaves_itself_out_of_the_running_chunks_when_it_starts_the_next(self) -> None:
self.description = DESCRIPTION.replace("2", "1")
fake = FakeEffects(git=UNREAD, windows=WINDOW)
code, out, err = self.awaited(fake, closes_after=1)
self.assertEqual((code, err), (0, ""))
self.assertIn("the chunk finished; started ABC-21\n", out)
def test_the_status_says_that_a_task_without_a_window_starts_at_once(self) -> None:
fake = FakeEffects(windows="")
code, out, err = self.run_main(["ABC-12", "--status"], fake)
self.assertEqual((code, err), (0, ""))
self.assertEqual(out.replace("<1790000000> ", "").splitlines()[0], "ABC-19 waits: it has not started; `do-epic ABC-12` starts it")
def test_a_task_that_blocks_two_issues_names_both(self) -> None:
self.epic.issues.append(issue("ABC-22", "do-epic-claude", blockers=("ABC-19",)))
fake = FakeEffects(git=UNREAD, windows=WINDOW)
self.awaited(fake, closes_after=1)
self.assertIn("blocks ABC-21 and ABC-22. ", fake.dms[0])
def test_goes_on_where_the_task_blocks_nothing_any_more(self) -> None:
fake = FakeEffects(git=UNREAD, windows=WINDOW)
fake.effects = lambda made=fake.effects(): dataclasses.replace(made, sleep=lambda seconds: self.epic.change("ABC-21", blockers=())) # type: ignore[method-assign]
code, out, err = self.run_main(["--chunk", "ABC-19", "ABC-12"], fake, MODELS)
self.assertEqual((code, err), (0, ""))
self.assertIn("the chunk finished; started ABC-21\n", out)
def test_says_once_why_a_read_failed_and_keeps_polling(self) -> None:
fake = FakeEffects(git=UNREAD, windows=WINDOW)
slept: list[int] = []
def sleep(seconds: int) -> None:
slept.append(seconds)
self.epic.fails = "Jira answered 503" if len(slept) < 3 else None
if len(slept) == 4:
self.epic.change("ABC-19", done=True)
fake.effects = lambda made=fake.effects(): dataclasses.replace(made, sleep=sleep) # type: ignore[method-assign]
code, out, err = self.run_main(["--chunk", "ABC-19", "ABC-12"], fake, MODELS)
self.assertEqual((code, err), (0, ""))
self.assertEqual(out.count("Jira answered 503"), 1, out)
self.assertEqual(len(fake.dms), 1)
def test_a_task_that_holds_nothing_up_at_its_start_hands_on_without_a_dm(self) -> None:
self.epic.change("ABC-21", blockers=())
fake = FakeEffects(git=UNREAD, windows=WINDOW)
code, out, err = self.run_main(["--chunk", "ABC-19", "ABC-12"], fake, MODELS)
self.assertEqual((code, err, fake.dms), (0, "", []))
self.assertIn("the chunk finished; started ABC-21\n", out)
def test_the_status_says_that_the_task_is_awaited(self) -> None:
fake = FakeEffects(windows="ABC-19 awaits a human's task\t0\t@9\n")
code, out, err = self.run_main(["ABC-12", "--status"], fake)
self.assertEqual((code, err), (0, ""))
self.assertEqual(out.replace("<1790000000> ", "").splitlines(), [f"ABC-19 waits: {HUMAN_WAIT}", "ABC-21 waits: ABC-19 blocks it"])
def test_the_epic_starts_a_window_for_the_task_and_none_for_the_issue_it_blocks(self) -> None:
fake = FakeEffects(windows="")
code, out, err = self.run_main(["ABC-12"], fake, {"TMUX_PANE": "%1"})
self.assertEqual((code, err), (0, ""))
self.assertIn("started ABC-19 in the tmux session epic-ABC-12\n", out)
self.assertIn("ABC-21 waits: ABC-19 blocks it\n", out)
self.assertEqual(fake.dms, [])
if __name__ == "__main__":
unittest.main()
+23 -14
View File
@@ -79,6 +79,12 @@ class DoEpicTest(unittest.TestCase):
self.issues = [issue("ABC-20", "repo:api")]
return folder
def epic_run(self, fake: FakeEffects, env: dict[str, str] | None = None) -> main.EpicRun:
config = main.load(self.home)
assert not isinstance(config, Failure)
store, record = self.backend(config, "ABC-12")
return main.EpicRun("ABC-12", config, store, record, paths_from(self.home), env or {}, pathlib.Path("/b/do-epic"), fake.effects())
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):
@@ -149,11 +155,8 @@ 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())
place = main.chunk_root("ABC-21", epic)
epic = self.epic_run(fake, env)
place = main.chunk_root("ABC-21", self.issues[1], epic)
assert isinstance(place, tuple)
root, repo = place
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())
@@ -409,6 +412,12 @@ class AChunksRun(DoEpicTest):
self.assertEqual(code, 1)
self.assertIn("the chunk finished, but the next could not start: Jira answered 503\n", err)
def test_a_chunk_in_a_folder_no_project_config_names_stops_with_gits_reason(self) -> None:
stopped = main.chunk_work("ABC-21", str(self.home), "English", self.epic_run(FakeEffects()))
assert isinstance(stopped, main.Stop)
self.assertEqual(stopped.code, 1)
self.assertIn("rev-parse", stopped.reason) # git's reason, since no project config can be found without a checkout
def test_a_chunk_in_a_repo_works_in_its_checkout_on_the_repos_premises_and_records(self) -> None:
checkout = self.home / "code" / "api"
configured(self, checkout, home=self.home)
@@ -424,6 +433,8 @@ class AChunksRun(DoEpicTest):
self.assertIn("Ship the import.", prompt)
self.assertIn("The repo's goals, which rank after the epic's and after code health, are from", prompt)
self.assertIn("Serve the API.", prompt)
self.assertIn("without `--finish`", prompt)
self.assertIn("add one bullet to `## Unreleased` in `CHANGELOG.md`", prompt)
self.assertIn("the chunk finished; started ABC-12\n", out)
judge_prompt = [what[1] for seam, what in fake.calls if seam == "claude"][0]
self.assertIn("The records: the epic's scoring and decisions, then the repo's working rules and decisions, then the human's rules for every project:\nFrom the epic ABC-12's description, ## Decisions:\nKeep the v1 endpoints.\n\nFrom AGENTS.md:\nSquash every merge.", judge_prompt)
@@ -459,15 +470,13 @@ class AChunksRun(DoEpicTest):
self.assertIn("decisions.md", err.strip().splitlines()[-1])
self.assertIn("decisions.md", fake.dms[0])
def test_an_issue_that_is_a_humans_or_names_no_repo_is_no_chunk(self) -> None:
for labels, why in ((("do-epic-human",), "it is a human's task"), ((), "no label names its repo")):
with self.subTest(labels):
self.issues = [issue("ABC-20", *labels)]
fake = FakeEffects(git=UNREAD)
code, _, err = self.run_main(["--chunk", "ABC-20", "ABC-12"], fake, MODELS)
self.assertEqual(code, 1)
self.assertIn(f"ABC-20 is no chunk: {why}\n", err)
self.assertEqual([seam for seam, _ in fake.calls if seam == "stream_claude"], [])
def test_an_issue_that_names_no_repo_is_no_chunk(self) -> None:
self.issues = [issue("ABC-20")]
fake = FakeEffects(git=UNREAD)
code, _, err = self.run_main(["--chunk", "ABC-20", "ABC-12"], fake, MODELS)
self.assertEqual(code, 1)
self.assertIn("ABC-20 is no chunk: no label names its repo\n", err)
self.assertEqual([seam for seam, _ in fake.calls if seam == "stream_claude"], [])
def test_a_chunk_stays_in_its_repo_when_its_labels_change_under_it(self) -> None:
self.repo_chunk()
+54 -2
View File
@@ -6,7 +6,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic.scheduler import Chunk, CHUNK_FLAG, chunks, Epic, refusal, RepoRoom, resume, start_chunks, Started, Waits
from do_epic.scheduler import Chunk, CHUNK_FLAG, chunks, Epic, HUMAN_WAIT, refusal, RepoRoom, resume, start_chunks, Started, Waits
from do_epic import chunk_prompt
from do_epic.backend.protocol import EpicIssue
from failure import Failure
@@ -15,6 +15,7 @@ from do_epic.epic_record import parallel_chunks_in
from loop_claude.cycle import prompts
from model_routing.route import Route
from model_routing.ladder import Rung
from project_config import settings
from agent_cycle import tmux
@@ -68,6 +69,18 @@ class WhichIssuesAreChunks(unittest.TestCase):
Waits("ABC-23", "ABC-20 and XYZ-1 block it; do-epic cannot see XYZ-1, outside the epic, finish: remove such a link in Jira once its issue is done"),
]))
def test_a_human_task_that_blocks_an_open_issue_is_a_chunk_to_await_and_one_that_blocks_none_waits(self) -> None:
found = chunks([issue("ABC-20", "do-epic-human"), issue("ABC-21", "repo:api", blockers=("ABC-20",)), issue("ABC-22", "do-epic-human")])
self.assertEqual(found, ([Chunk("ABC-20", None, human=True)], [Waits("ABC-21", "ABC-20 blocks it"), Waits("ABC-22", "it is a human's task")]))
def test_a_human_task_is_awaited_while_it_blocks_a_sub_task_through_its_split_parent(self) -> None:
found = chunks([issue("ABC-19", "do-epic-human"), issue("ABC-20", "split-by-repo", blockers=("ABC-19",)), issue("ABC-23", "repo:api", parent="ABC-20")])
self.assertEqual(found, ([Chunk("ABC-19", None, human=True)], [Waits("ABC-23", "ABC-19 blocks it")]))
def test_a_human_task_that_is_blocked_itself_or_blocks_only_done_issues_waits(self) -> None:
found = chunks([issue("ABC-19", "repo:api"), issue("ABC-20", "do-epic-human", blockers=("ABC-19",)), issue("ABC-21", "repo:api", blockers=("ABC-20",)), issue("ABC-22", "do-epic-human"), issue("ABC-23", "repo:api", done=True, blockers=("ABC-22",))])
self.assertEqual(found, ([Chunk("ABC-19", "api")], [Waits("ABC-20", "it is a human's task"), Waits("ABC-21", "ABC-20 blocks it"), Waits("ABC-22", "it is a human's task")]))
def test_what_blocks_a_split_item_blocks_its_sub_tasks(self) -> None:
found = chunks([issue("ABC-19", "repo:api"), issue("ABC-20", "split-by-repo", blockers=("ABC-19",)), issue("ABC-23", "repo:api", parent="ABC-20")])
self.assertEqual(found, ([Chunk("ABC-19", "api")], [Waits("ABC-23", "ABC-19 blocks it")]))
@@ -169,6 +182,17 @@ class StartingAnEpicsChunks(unittest.TestCase):
self.assertEqual(run.windows[-1], ("epic-ABC-12", "ABC-20", False, str(self.home / ".local/state/do-epic/ABC-12")))
self.assertEqual([name for _, name, dead, _ in run.windows if dead], [""] * len(windows))
def test_a_human_task_that_blocks_an_issue_gets_a_window_that_takes_no_slot_of_the_epics_cap(self) -> None:
run = Tmux()
found = self.start(self.epic(1, api=1), [issue("ABC-19", "do-epic-human"), issue("ABC-20", "do-epic-claude"), issue("ABC-21", "repo:api", blockers=("ABC-19",))], run)
self.assertEqual(found, Started(["ABC-19", "ABC-20"], [Waits("ABC-21", "ABC-19 blocks it")]))
def test_a_human_task_with_a_window_that_awaits_it_starts_no_second_window(self) -> None:
run = Tmux(("epic-ABC-12", "ABC-19 awaits a human's task", False, ""))
found = self.start(self.epic(1, api=1), [issue("ABC-19", "do-epic-human"), issue("ABC-21", "repo:api", blockers=("ABC-19",))], run)
self.assertEqual(found, Started([], [Waits("ABC-19", HUMAN_WAIT), Waits("ABC-21", "ABC-19 blocks it")]))
self.assertEqual(run.started(), [])
def test_a_parked_chunk_that_starts_again_leaves_the_epics_cap_to_the_others(self) -> None:
self.parked("ABC-20")
found = self.start(self.epic(1, api=2), [issue("ABC-20", "repo:api"), issue("ABC-21", "repo:api")], Tmux())
@@ -291,6 +315,9 @@ class StartingAnEpicsChunks(unittest.TestCase):
self.assertRegex(found.reason, f"^cannot lock {self.home}/.local/state/do-epic/ABC-12: \\w")
CONFIG = settings.ProjectConfig("api", pathlib.Path("/c/api"), pathlib.Path("/code/api"), {"changelog": pathlib.Path("/code/api/CHANGELOG.md")}, epic=settings.Epic("https://acme.atlassian.net", "API-1"))
class TheFirstPrompt(unittest.TestCase):
def test_the_task_names_the_checkout_and_branch_and_quotes_a_description_only_where_there_is_one(self) -> None:
labels = "`repo:<name>` for the repo that works it, `do-epic-claude` for work of Claude's that changes no repo, or `do-epic-human` for a task of the human's"
@@ -299,7 +326,32 @@ class TheFirstPrompt(unittest.TestCase):
"Where filing fails and says the issue may exist, ask the human to look before you file it again. File a finding about a repo's goals by that repo's rules. Where unsure which, ask the human. "
"Record a decision that governs the epic, such as an answer the human typed, with `/b/do-epic ABC-12 --record-decision \"<title>\"` and its text on stdin. Write the issue and the decision in Swedish, the epic's language."
)
self.assertEqual(chunk_prompt.task(issue("ABC-20"), "ABC-12", "/code/api", pathlib.Path("/b/do-epic"), "Swedish"), f"Work the Jira issue ABC-20 of the epic ABC-12 as one chunk, in the checkout /code/api, on the branch ABC-20. {told} Its summary: Do ABC-20")
task = chunk_prompt.task(issue("ABC-20"), "ABC-12", "/code/api", pathlib.Path("/b/do-epic"), "Swedish", CONFIG)
self.assertTrue(task.startswith(f"Work the Jira issue ABC-20 of the epic ABC-12 as one chunk, in the checkout /code/api, on the branch ABC-20. {told} "))
self.assertTrue(task.endswith(" Its summary: Do ABC-20"))
def test_a_chunk_without_a_repo_is_told_nothing_of_shipping(self) -> None:
task = chunk_prompt.task(issue("ABC-20"), "ABC-12", None, pathlib.Path("/b/do-epic"), "Swedish", None)
self.assertTrue(task.endswith("Swedish, the epic's language. Its summary: Do ABC-20"))
self.assertNotIn("--finish", task)
def test_a_repo_with_a_plan_file_is_told_to_add_a_bullet_to_its_changelog_where_it_publishes(self) -> None:
config = settings.ProjectConfig("api", pathlib.Path("/c/api"), pathlib.Path("/code/api"), {"changelog": pathlib.Path("/code/api/CHANGELOG.md")})
told = chunk_prompt.shipping(config)
self.assertTrue(told.startswith("The issue isn't an item of the repo's plan, so run `chunk-pr merge` without `--finish`."))
self.assertIn("Where the repo publishes something others consume, add one bullet to `## Unreleased` in `CHANGELOG.md`", told)
def test_a_changelog_outside_the_checkout_or_on_a_page_is_named_as_the_config_spells_it(self) -> None:
config = settings.ProjectConfig("api", pathlib.Path("/c/api"), pathlib.Path("/code/api"), {"changelog": pathlib.Path("/c/api/CHANGELOG.md")})
self.assertIn("in `/c/api/CHANGELOG.md`", chunk_prompt.shipping(config))
paged = settings.ProjectConfig("api", pathlib.Path("/c/api"), pathlib.Path("/code/api"), {}, pages={"changelog": settings.Page("https://acme.atlassian.net", "7", "confluence:https://acme.atlassian.net/wiki/pages/7")})
self.assertIn("in `confluence:https://acme.atlassian.net/wiki/pages/7`", chunk_prompt.shipping(paged))
def test_a_repo_with_its_plan_in_jira_is_told_to_leave_the_changelog_as_it_is(self) -> None:
told = chunk_prompt.shipping(CONFIG)
self.assertTrue(told.startswith("The issue isn't an item of the repo's plan, so run `chunk-pr merge` without `--finish`."))
self.assertIn("leave the changelog as it is", told)
self.assertNotIn("## Unreleased", told)
def test_an_answer_the_judge_quoted_names_the_epics_description_first(self) -> None:
self.assertTrue(chunk_prompt.WORKER.answered("Q", "A", Route(Rung("off-the-ladder")), None, False).startswith("Your question: Q\n\nthe epic's description, "))
+2 -2
View File
@@ -141,7 +141,7 @@ class Main(unittest.TestCase):
result = reply(Rung(args[args.index("--model") + 1], args[args.index("--effort") + 1]), "said Verdict: interrupt" in prompt.rsplit("latest last:", 1)[-1])
return subprocess.CompletedProcess(args, 0, json.dumps(result), "")
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=unused, input=unused, local_time=unused, memory=unused, now=lambda: 1790000000.0, on_terminal=unused, python=unused, sleep=unused, stream_claude=unused, tmux=unused, tmux_on_terminal=unused)
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=unused, input=unused, local_time=unused, memory=unused, now=lambda: 1790000000.0, on_terminal=unused, python=unused, sleep=unused, stream_claude=unused, timer=unused, tmux=unused, tmux_on_terminal=unused)
out, err = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
code = main.main(argv, {}, self.home, effects)
@@ -342,7 +342,7 @@ class JudgeArchivedRuns(unittest.TestCase):
cwds.append(cwd)
return subprocess.CompletedProcess(args, 0, json.dumps({"type": "result", "structured_output": output, "total_cost_usd": 0.25}), "")
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=unused, input=unused, local_time=unused, memory=unused, now=lambda: 1790000000.0, on_terminal=unused, python=unused, sleep=unused, stream_claude=unused, tmux=unused, tmux_on_terminal=unused)
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=unused, input=unused, local_time=unused, memory=unused, now=lambda: 1790000000.0, on_terminal=unused, python=unused, sleep=unused, stream_claude=unused, timer=unused, tmux=unused, tmux_on_terminal=unused)
grounds = grounds_of(prompt, self.ENTRIES)
return (grounds if isinstance(grounds, Failure) else judge_archived("/code/p", prompt, grounds, len(self.ENTRIES), REFERENCE, DRIVER, effects)), cwds
+4 -1
View File
@@ -64,7 +64,10 @@ config sets notifier, loop-claude also sends the human each question, naming its
<session>:<window>, each release ready to cut and each stop as a DM, as bin/notify sends it. Four
stops are left out: Ctrl-C, printing this help, the loop-claude that started the windows once it
attaches or prints how to, and a loop whose chunk finished once it started the next chunks. A DM
that fails is said on stderr, and the loop goes on.
that fails is said on stderr, and the loop goes on. Where no answer has come 10 minutes before the
worker's hour-long prompt cache expires, and the worker's context holds at least 60k tokens,
loop-claude compacts the worker's session with `claude -p /compact` and keeps waiting, so the resume
doesn't write the whole context again.
As a chunk starts, before it is routed, loop-claude runs bin/chunk-preflight --worktree, adding
--item <ID> in a window named for an item, and quotes what it prints in the first prompt
+162 -10
View File
@@ -109,14 +109,19 @@ class FakeEffects:
self.owner = owner
# Each direct message sent. They stay out of self.calls, so a test that lists every call doesn't list them. Without a script, each is sent.
self.dms = []
# The directory each DM named, in the order of self.dms; None where it named none.
self.dm_directories = []
self.dm_failures = list(dm_failures)
self.scripts = {"claude": list(claude), "claude_on_terminal": list(on_terminal_claude), "git": list(git), "input": list(inputs), "python": list(python), "stream_claude": list(streams)}
# Without a script, every read finds all memory available.
self.free_memory = list(free_memory)
self.terminal = on_terminal
self.worker_environments = []
self.worker_folders = []
self.terminal_environments = []
self.terminal_folders = []
# Each timer started, as its delay and action, which a test runs where the timer fires.
self.timers = []
def effects(self):
return Effects(
@@ -134,18 +139,24 @@ class FakeEffects:
python=lambda args, cwd: self.answer("python", (args, cwd)),
sleep=lambda seconds: self.calls.append(("sleep", seconds)),
stream_claude=self.stream,
timer=self.timer,
tmux=self.tmux,
tmux_on_terminal=lambda args: self.tmux(args).returncode,
)
def timer(self, delay, action):
self.timers.append((delay, action))
return lambda: self.calls.append(("stop_timer", delay))
def tmux(self, args):
self.tmux_calls.append(args)
if args[0] == "list-windows":
return subprocess.CompletedProcess(args, 1 if self.windows is None else 0, self.windows or "", "no server")
return subprocess.CompletedProcess(args, 0, {"-V": self.tmux_version + "\n", "show-options": self.owner + "\n"}.get(args[0], "@9\n"), "")
def dm(self, text):
def dm(self, text, directory):
self.dms.append(text)
self.dm_directories.append(directory)
return self.dm_failures.pop(0) if self.dm_failures else None
def memory(self):
@@ -159,6 +170,7 @@ class FakeEffects:
def stream(self, args, cwd, env):
self.worker_environments.append(env)
self.worker_folders.append(cwd)
return self.answer("stream_claude", args)
def answer(self, seam, what):
@@ -191,13 +203,15 @@ def judged(verdict, evidence="working", answer="", escalation="", release_ready=
class Worker:
"""A worker claude: writes a line to the session's transcript, then streams a result."""
def __init__(self, home, prompted=False, text="working", usage=None):
def __init__(self, home, prompted=False, text="working", usage=None, sent=None):
self.home = home
# Whether it records its -p prompt in the transcript first, as claude does.
self.prompted = prompted
self.text = text
# The usage its message records, twice as Claude Code writes a message of two blocks; none where None.
self.usage = usage
# The time its message records, as utc() writes it; none where None.
self.sent = sent
def __call__(self, args):
flag = "--session-id" if "--session-id" in args else "--resume"
@@ -211,6 +225,8 @@ class Worker:
said = assistant({"type": "text", "text": self.text})
if self.usage is not None:
said["message"] |= {"id": "msg-1", "model": "claude-opus-5-5", "usage": self.usage}
if self.sent is not None:
said["timestamp"] = self.sent
handle.write((json.dumps(said) + "\n") * (1 if self.usage is None else 2))
return Streamed(0)
@@ -265,14 +281,15 @@ class Transitions(unittest.TestCase):
states.transition(state, event)
def test_a_rulings_step_up_reaches_the_worker_it_resumes_through_the_answer_the_human_types_and_no_further(self):
stepped_to = Route(Rung("claude-fable-5-2", "low"), escalated_at=3)
ran_on = Rung("claude-opus-5-5", "xhigh")
stepped = routing.StepUp(Route(ran_on), Route(Rung("claude-fable-5-2", "low"), escalated_at=3))
interrupt, quoted = Interrupt("e", "q", "round 2: 🔴"), QuotedAnswer("e", "q", "A.", "round 2: 🔴")
for state, event, after in (
(states.Judging("/t"), states.Ruled(quoted, stepped_to), states.Working(quoted, 1, True)),
(states.Judging("/t", 3), states.Ruled(quoted, stepped_to), states.Interrupting("/t", quoted, 3, True)),
(states.Judging("/t"), states.Ruled(interrupt, stepped_to), states.Interrupting("/t", interrupt, 0, True)),
(states.Interrupting("/t", interrupt, 0, True), states.HumanTyped(TYPED), states.Working(TYPED, 0, True)),
(states.Interrupting("/t", interrupt, 0, True), states.HumanTalked(), states.Judging("/t")),
(states.Judging("/t"), states.Ruled(quoted, stepped), states.Working(quoted, 1, True)),
(states.Judging("/t", 3), states.Ruled(quoted, stepped), states.Interrupting("/t", quoted, 3, ran_on)),
(states.Judging("/t"), states.Ruled(interrupt, stepped), states.Interrupting("/t", interrupt, 0, ran_on)),
(states.Interrupting("/t", interrupt, 0, ran_on), states.HumanTyped(TYPED), states.Working(TYPED, 0, True)),
(states.Interrupting("/t", interrupt, 0, ran_on), states.HumanTalked(), states.Judging("/t")),
(states.Working(TYPED, 0, True), states.WorkerRan("/t"), states.Judging("/t")),
):
with self.subTest(state=state, event=event):
@@ -645,6 +662,23 @@ Spent since 2026-09-21T14:13:20Z, in tokens of input, cache write 5m, cache writ
self.assertIn(" Launch each reviewer with the Agent tool set to model fable, effort low, the rung item 179's E + I of 5 picks.", typed)
self.assertNotIn("went through", first[first.index("-p") + 1])
def test_an_interrupt_that_steps_the_worker_up_compacts_its_session_on_the_rung_it_ran_on(self):
usage = {"input_tokens": 2, "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 5000}, "cache_read_input_tokens": 70000, "output_tokens": 100}
worker = Worker(self.paths.claude_code_transcripts.parent, usage=usage, sent=utc(NOW - 600))
fake = FakeEffects(streams=[worker, Streamed(0), worker], claude=[judged("interrupt", escalation="working"), judged("finished")])
def typed(prompt):
for _, action in fake.timers:
action()
return "Use B."
fake.scripts["input"] = [typed]
cycle = dataclasses.replace(self.cycle(fake), project=OPUS_PROJECT, route=Route(Routing.SONNET, 179, 2, 5))
with contextlib.redirect_stderr(io.StringIO()):
run.run_cycle(cycle)
_, compaction, resumed = fake.made("stream_claude")
self.assertEqual(compaction[compaction.index("-p") + 1], "/compact")
self.assertEqual([(args[args.index("--model") + 1], args[args.index("--effort") + 1]) for args in (compaction, resumed)], [("claude-sonnet-5-5", "high"), ("claude-opus-5-5", "medium")])
def test_a_typed_answer_past_the_quoted_answers_cap_reaches_the_worker_with_its_own_question(self):
worker = Worker(self.paths.claude_code_transcripts.parent)
fake = FakeEffects(streams=[worker] * 5, claude=[judged("quoted", answer="Use A.")] * 4 + [judged("finished")], inputs=["Use B."])
@@ -790,7 +824,7 @@ class Interrupts(unittest.TestCase):
self.paths = paths.paths_from(self.home)
self.transcript = self.home / "t.jsonl"
self.transcript.write_text(json.dumps(human("a")) + "\n")
self.session = interrupt.WorkerSession(str(self.home), uuid.uuid7(), Rung("m", "high"), str(self.transcript), {"LOOP_CLAUDE_WORKER_RUNG": "m at high effort"})
self.session = interrupt.WorkerSession(str(self.home), uuid.uuid7(), Rung("m", "high"), Rung("m", "high"), str(self.transcript), {"LOOP_CLAUDE_WORKER_RUNG": "m at high effort"})
def put(self, fake, answer_here=True, effects=None, question="Which one?"):
"""interrupt's answer and what it said, without the bell it rang, which self.bells counts."""
@@ -805,6 +839,121 @@ class Interrupts(unittest.TestCase):
handle.write(json.dumps(human("cut it")) + "\n")
return 0
def worked(self, minutes_ago, written_1h=5000, read=70000, written_5m=0):
"""Appends the worker's last message, sent minutes_ago before NOW, whose usage wrote written_1h tokens to the hour-long cache, written_5m to the five-minute one, and read read tokens from the cache."""
said = assistant({"type": "text", "text": "Which one?"})
said["timestamp"] = utc(NOW - minutes_ago * 60)
said["message"] |= {"id": "msg-1", "model": "m", "usage": {"input_tokens": 2, "cache_creation": {"ephemeral_5m_input_tokens": written_5m, "ephemeral_1h_input_tokens": written_1h}, "cache_read_input_tokens": read, "output_tokens": 100}}
with open(self.transcript, "a") as handle:
handle.write(json.dumps(said) + "\n")
def fired(self, fake, answer):
"""An input that first fires every timer started, then returns answer as the line the human typed."""
def typed(prompt):
for _, action in fake.timers:
action()
return answer
return typed
def test_compacts_the_workers_session_ten_minutes_before_its_hour_long_prompt_cache_expires_and_keeps_waiting(self):
self.worked(minutes_ago=10)
fake = FakeEffects(streams=[Streamed(0)])
fake.scripts["input"] = [self.fired(fake, "Use B.")]
answer, said = self.put(fake)
self.assertEqual(answer, "Use B.")
self.assertEqual([delay for delay, _ in fake.timers], [40 * 60])
self.assertEqual([what for seam, what in fake.calls if seam == "stream_claude"], [["--model", "m", "--effort", "high", "--permission-mode", "bypassPermissions", "-p", "/compact", "--resume", str(self.session.id), "--output-format", "stream-json", "--verbose"]])
self.assertEqual(fake.worker_environments, [self.session.env])
self.assertEqual(fake.worker_folders, [self.session.root])
self.assertIn(f"\n{STAMP} compacting the worker's claude session before its prompt cache expires; an answer typed meanwhile is read once that ends\n\n{STAMP} compacted the worker's claude session\n", said)
self.assertNotIn("still waiting", said)
def test_compacts_on_the_rung_the_worker_ran_on_where_a_ruling_stepped_it_up_and_talk_opens_claude_on_the_new_rung(self):
self.worked(minutes_ago=10)
self.session = dataclasses.replace(self.session, rung=Rung("n", "medium"))
fake = FakeEffects(streams=[Streamed(0)], on_terminal_claude=[self.typed_there])
fake.scripts["input"] = [self.fired(fake, "/talk")]
self.assertEqual(self.put(fake)[0], interrupt.Talked())
(compaction,), (opened,) = fake.made("stream_claude"), fake.made("claude_on_terminal")
self.assertEqual(compaction[:4], ["--model", "m", "--effort", "high"])
self.assertEqual(opened[:4], ["--model", "n", "--effort", "medium"])
def test_compacts_until_the_prompt_cache_expires_and_not_from_then_on(self):
for name, late, compactions in (("a second before", 50 * 60 - 1, 1), ("as it expires", 50 * 60, 0)):
with self.subTest(name):
self.transcript.write_text(json.dumps(human("a")) + "\n")
self.worked(minutes_ago=10)
fake = FakeEffects(streams=[Streamed(0)])
clock = [NOW]
def typed(prompt):
clock[0] = NOW + late
for _, action in fake.timers:
action()
return "Use B."
fake.scripts["input"] = [typed]
answer, said = self.put(fake, effects=dataclasses.replace(fake.effects(), now=lambda: clock[0]))
self.assertEqual(answer, "Use B.")
self.assertEqual(len(fake.made("stream_claude")), compactions)
self.assertEqual(said.count("compact"), 2 * compactions, said)
def test_a_compaction_doesnt_wait_for_memory(self):
self.worked(minutes_ago=10)
fake = FakeEffects(streams=[Streamed(0)], free_memory=[memory.Memory(available=3, total=16)])
fake.scripts["input"] = [self.fired(fake, "Use B.")]
said = self.put(fake)[1]
self.assertEqual([seam for seam, _ in fake.calls if seam in ("memory", "sleep", "stream_claude")], ["stream_claude"])
self.assertNotIn("waiting to start the worker", said)
def test_an_answer_before_the_timer_fires_stops_it_and_doesnt_compact_anything(self):
self.worked(minutes_ago=10)
fake = FakeEffects(inputs=["Use B."])
self.assertEqual(self.put(fake)[0], "Use B.")
self.assertEqual([call for call in fake.calls if call[0] in ("stop_timer", "stream_claude")], [("stop_timer", 40 * 60)])
def test_stops_the_timer_before_talk_opens_the_workers_session(self):
self.worked(minutes_ago=10)
fake = FakeEffects(inputs=["/talk"], on_terminal_claude=[self.typed_there])
self.assertEqual(self.put(fake)[0], interrupt.Talked())
self.assertEqual([call[0] for call in fake.calls if call[0] in ("stop_timer", "claude_on_terminal")], ["stop_timer", "claude_on_terminal"])
def test_starts_no_timer_under_60k_tokens_of_context_past_the_margin_on_a_five_minute_cache_or_where_claude_opens_at_once(self):
for name, minutes_ago, written_1h, written_5m, read, answer_here in (("small", 10, 5000, 0, 54997, True), ("margin begun", 50, 5000, 0, 70000, True), ("five minutes", 1, 0, 5000, 70000, True), ("nothing written", 1, 0, 0, 70000, True), ("opens at once", 10, 5000, 0, 70000, False)):
with self.subTest(name):
self.transcript.write_text(json.dumps(human("a")) + "\n")
self.worked(minutes_ago, written_1h, read, written_5m)
fake = FakeEffects(inputs=["Use B."], on_terminal_claude=[self.typed_there])
self.put(fake, answer_here=answer_here)
self.assertEqual(fake.timers, [])
def test_starts_the_timer_at_60k_tokens_of_context(self):
self.worked(minutes_ago=10, read=54998)
fake = FakeEffects(inputs=["Use B."])
self.put(fake)
self.assertEqual([delay for delay, _ in fake.timers], [40 * 60])
def test_starts_no_timer_where_the_transcript_cannot_be_read_and_still_asks(self):
self.transcript.unlink()
fake = FakeEffects(inputs=["Use B."])
self.assertEqual(self.put(fake)[0], "Use B.")
self.assertEqual(fake.timers, [])
def test_a_compaction_that_hits_a_usage_limit_says_the_limits_message_and_keeps_waiting(self):
self.worked(minutes_ago=10)
fake = FakeEffects(streams=[Streamed(0, {"type": "result", "api_error_status": 429, "result": "You've hit your session limit"})])
fake.scripts["input"] = [self.fired(fake, "Use B.")]
answer, said = self.put(fake)
self.assertEqual(answer, "Use B.")
self.assertIn(f"\n{STAMP} could not compact the worker's claude session: You've hit your session limit\n", said)
def test_a_compaction_that_fails_says_why_and_keeps_waiting(self):
self.worked(minutes_ago=10)
fake = FakeEffects(streams=[Streamed(1)])
fake.scripts["input"] = [self.fired(fake, "Use B.")]
answer, said = self.put(fake)
self.assertEqual(answer, "Use B.")
self.assertIn(f"\n{STAMP} could not compact the worker's claude session: claude exited 1\n", said)
def test_stops_off_a_terminal_before_asking(self):
fake = FakeEffects(on_terminal=False)
self.assertEqual(self.put(fake), (Stop(2, "the human is needed to answer the question above, but stdin or stdout is not a terminal; rerun loop-claude on a terminal"), f"\n{STAMP} Which one?\n"))
@@ -832,7 +981,7 @@ class Interrupts(unittest.TestCase):
def test_drops_the_keys_typed_before_the_question_ahead_of_the_dm_so_an_answer_typed_while_it_sends_counts(self):
fake = FakeEffects(inputs=["Use B."])
seen = []
effects = dataclasses.replace(fake.effects(), dm=lambda text: seen.append(list(fake.calls)))
effects = dataclasses.replace(fake.effects(), dm=lambda text, directory: seen.append(list(fake.calls)))
self.assertEqual(self.put(fake, effects=effects)[0], "Use B.")
self.assertEqual(seen, [[("discard_typed", None)]])
@@ -2003,6 +2152,9 @@ class Spend(unittest.TestCase):
self.assertEqual(tokens_of({"input_tokens": 1, "cache_creation_input_tokens": 9}), Tokens(1, 9, 0, 0, 0))
self.assertEqual(tokens_of(None), Tokens())
def test_counts_a_messages_context_as_every_prompt_token_and_no_output(self):
self.assertEqual(Tokens(1, 2, 3, 4, 5).context(), 10)
def test_counts_a_message_written_in_the_stamped_second_or_without_a_readable_time_as_before_since(self):
thread = [turn("m1", "a", "2026-11-01T10:00:01Z", output_tokens=7), turn("m2", "a", "not a time", output_tokens=3), turn("m3", "a", "2026-11-01T10:00:02Z", output_tokens=1)]
self.assertEqual(spend.spent("2026-11-01T10:00:01Z", thread, [], "j", Tokens()), {("worker", "a"): Tokens(output=1)})
+20 -3
View File
@@ -9,6 +9,7 @@ import signal
import subprocess
import sys
import termios
import threading
import time
import typing
@@ -36,8 +37,8 @@ class Effects:
claude_on_terminal: typing.Callable[[list[str], str, dict[str, str]], int]
# Drops what was typed on the terminal and not yet read.
discard_typed: typing.Callable[[], None]
# Sends the human a direct message through the notifier the project's config names, as `notify` does, for the project whose checkout holds the current directory; a Failure where it could not.
dm: typing.Callable[[str], Failure | None]
# Sends the human a direct message through the notifier the project's config names, as `notify` does, for the project whose checkout holds the given directory, else the current directory; a Failure where it could not.
dm: typing.Callable[[str, str | None], Failure | None]
execv: typing.Callable[[str, list[str]], None]
git: git_repo.Git
input: typing.Callable[[str], str]
@@ -51,6 +52,8 @@ class Effects:
python: typing.Callable[[list[str], str], subprocess.CompletedProcess[str]]
sleep: typing.Callable[[float], None]
stream_claude: typing.Callable[[list[str], str, dict[str, str]], Streaming]
# Starts a timer, as start_timer does.
timer: typing.Callable[[float, typing.Callable[[], None]], typing.Callable[[], None]]
# Runs tmux with these arguments, as run_tmux does.
tmux: typing.Callable[[list[str]], subprocess.CompletedProcess[str]]
# Runs tmux on the terminal, as to attach a session, and returns its exit code once the human detaches.
@@ -75,7 +78,7 @@ def system_effects(backends: typing.Mapping[Notifier, Backend[typing.Any]] = BAC
claude=lambda args, cwd, stdin: subprocess.run(["claude", *args], capture_output=True, cwd=cwd, input=stdin, text=True),
claude_on_terminal=claude_on_terminal,
discard_typed=lambda: termios.tcflush(sys.stdin, termios.TCIFLUSH),
dm=lambda text: notify(text, None, pathlib.Path.home(), backends),
dm=lambda text, directory: notify(text, directory, pathlib.Path.home(), backends),
execv=os.execv,
git=git_repo.git,
input=input,
@@ -86,6 +89,7 @@ def system_effects(backends: typing.Mapping[Notifier, Backend[typing.Any]] = BAC
python=lambda args, cwd: run_python(args, cwd, PYTHON_TIMEOUT),
sleep=time.sleep,
stream_claude=StreamingClaude,
timer=start_timer,
tmux=run_tmux,
tmux_on_terminal=lambda args: subprocess.run(["tmux", *args]).returncode,
)
@@ -112,6 +116,19 @@ def run_python(args: list[str], cwd: str, timeout: float) -> subprocess.Complete
return subprocess.CompletedProcess(command, 1, "", f"stopped after {timeout} s")
def start_timer(delay: float, action: typing.Callable[[], None]) -> typing.Callable[[], None]:
"""Runs action on a thread of its own once delay seconds have passed, and returns what stops the timer: it cancels an action not yet started, and waits for one that has started to end."""
timer = threading.Timer(delay, action)
# A timer still running doesn't keep the process alive once the loop exits.
timer.daemon = True
timer.start()
def stop() -> None:
timer.cancel()
timer.join()
return stop
def run_tmux(args: list[str]) -> subprocess.CompletedProcess[str]:
"""Runs tmux and returns what it printed. A tmux that cannot start, as where none is installed, reads as exit 127, saying why on stderr."""
command = ["tmux", *args]
+34 -1
View File
@@ -6,13 +6,14 @@ import pathlib
import signal
import sys
import tempfile
import threading
import time
import unittest
import unittest.mock
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from loop_effects.effects import run_python, say, system_effects
from loop_effects.effects import run_python, say, start_timer, system_effects
NOW = 1790000000
# How a line said at NOW opens, with clocked's local_time.
@@ -134,3 +135,35 @@ class PythonEffect(unittest.TestCase):
done = run_python(["-c", "pass"], gone, 60)
self.assertEqual(done.returncode, 1)
self.assertIn(gone, done.stderr)
class Timer(unittest.TestCase):
def test_runs_the_action_beside_the_caller_once_the_delay_has_passed(self):
ran = threading.Event()
start_timer(0.05, ran.set)
self.assertTrue(ran.wait(10))
def test_the_systems_timer_runs_on_a_daemon_thread_so_a_loop_that_exits_while_it_waits_does_not_wait_for_it(self):
self.assertIs(system_effects().timer, start_timer)
before = set(threading.enumerate())
stop = start_timer(60, lambda: None)
self.addCleanup(stop)
self.assertEqual([thread.daemon for thread in set(threading.enumerate()) - before], [True])
def test_a_timer_stopped_before_its_delay_has_passed_never_runs_the_action(self):
ran = threading.Event()
# stop returns once the timer's thread has ended, so the action cannot run later.
start_timer(0.2, ran.set)()
self.assertFalse(ran.is_set())
def test_stopping_a_timer_whose_action_runs_waits_for_the_action_to_end(self):
started, ended = threading.Event(), threading.Event()
def action():
started.set()
time.sleep(0.2)
ended.set()
stop = start_timer(0, action)
self.assertTrue(started.wait(10))
stop()
self.assertTrue(ended.is_set())
+2 -1
View File
@@ -220,8 +220,9 @@ class ToolProcess(unittest.TestCase):
def test_an_interrupt_reaches_the_tool_before_the_run_kills_it(self):
# A container's CLI, such as docker compose, stops its container on the SIGINT it is passed, and can't once killed.
# The loop ends by itself after about 40 seconds: under mutmut, the interrupt doesn't reach this shell, and a shell that looped for ever hung the run.
with tempfile.TemporaryDirectory() as folder:
self.interrupted(folder, "trap 'echo > stopped; exit 130' INT; echo $$ > started; while :; do sleep 0.1; done;")
self.interrupted(folder, "trap 'echo > stopped; exit 130' INT; echo $$ > started; n=0; while [ $n -lt 400 ]; do sleep 0.1; n=$((n+1)); done;")
self.assertTrue(pathlib.Path(folder, "stopped").is_file())
def test_an_interrupted_tool_that_ignores_sigint_is_killed_after_the_grace_period(self):
+8 -1
View File
@@ -73,7 +73,14 @@ class Notify(Project):
self.name_notifier("slack", SLACK_KEYS)
slack = Slack({"ok": True})
with contextlib.chdir(self.checkout):
self.assertIsNone(system_effects(through("slack", slack)).dm("Which one?"))
self.assertIsNone(system_effects(through("slack", slack)).dm("Which one?", None))
self.assertEqual(slack.requests, [SLACK_POST])
def test_a_dm_that_names_a_directory_goes_through_the_notifier_for_the_project_holding_it_from_any_current_directory(self):
self.name_notifier("slack", SLACK_KEYS)
slack = Slack({"ok": True})
with contextlib.chdir(self.home):
self.assertIsNone(system_effects(through("slack", slack)).dm("Which one?", str(self.checkout)))
self.assertEqual(slack.requests, [SLACK_POST])
def test_skips_the_notice_for_a_project_that_names_no_notifier_even_where_its_env_file_holds_the_keys(self):
+1 -1
View File
@@ -270,7 +270,7 @@ class Main(unittest.TestCase):
result = result if "api_error_status" in result else {"type": "result", "structured_output": {"found": [n + 1 for n in result["found"]]}}
return subprocess.CompletedProcess(args, 0, json.dumps(result), "")
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=system_effects().git, input=unused, local_time=unused, memory=unused, now=lambda: 1790000000.0, on_terminal=unused, python=unused, sleep=unused, stream_claude=unused, tmux=unused, tmux_on_terminal=unused)
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=system_effects().git, input=unused, local_time=unused, memory=unused, now=lambda: 1790000000.0, on_terminal=unused, python=unused, sleep=unused, stream_claude=unused, timer=unused, tmux=unused, tmux_on_terminal=unused)
out, err = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
code = main.main(argv, env, self.home, effects)
+2 -2
View File
@@ -150,11 +150,11 @@ Valid while `~/.claude` is a checkout of this repo.
- **Items live only in the epic.** A repo's own plan never mirrors them. Where `repo-rule.md` leaves an item's repo unclear, do-epic asks. An item without a repo is either Claude's work, done without a PR, or a human task; where the item doesn't say which, do-epic asks.
- **One item, several repos.** do-epic splits such an item when it plans it, into one Jira sub-task per repo, each labelled for its repo. The parent tracks the whole change. A person's issue is split too, with a comment for the team.
- **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.
- **Releases.** An epic item has no release. It ships into its repo's unreleased work: where the repo publishes something others consume, a bullet under `CHANGELOG.md` → `## Unreleased`, or nothing where the repo's plan is in Jira. The issue is no item of the repo's plan, so the chunk's worker writes the bullet in its branch and runs `chunk-pr merge` without `--finish`.
- **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. The cap is a line of the epic's description, `**Max parallel chunks:** 2`, and 1 without it, as `parallel-chunks` is. 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. do-epic and loop-claude each hold the checkout's `starting` lock from checking the checkout's chunks to starting a window there. A chunk without a repo works in `~/.local/state/do-epic/<EPIC-KEY>/`. do-epic archives its cycles under `~/.claude/do-epic-transcripts/`, not in loop-claude's archive, 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. A gate is a pull request's pending checks or, on GitHub, the approval its branch protection requires; a draft waits on neither, since its worker has yet to mark it ready. On Gitea a draft is a pull request whose title opens with `WIP:` or `[WIP]`, Gitea's default `WORK_IN_PROGRESS_PREFIXES`. Changes a reviewer requested resume the chunk only while that review was made on the pull request's head commit and the pull request's author has not commented or replied after it; once the worker pushed or replied, the chunk parks on a new review, since GitHub keeps the decision until the reviewer reviews again. The chunk's window reads the forge once a minute, which no forge's rate limit notices. A chunk resumes only into a free slot, under the limits a starting chunk meets, and stays parked until then. `do-epic <key>` starts a parked chunk's window again whatever the limits, since the chunk stays parked. do-epic sets `CHUNK_PR_PARKS=1` for each worker, so `chunk-pr merge` fails at once where the pull request awaits an approval, and the worker's run doesn't hold a slot while the pull request waits.
- **Human tasks.** do-epic DMs the human when one blocks the next item, and polls until its issue closes.
- **Human tasks.** do-epic leaves a human task's issue as the team filed it. The task gets a window of its own while it is open, no issue blocks it, and it blocks another open issue. The window DMs the human once, through the notifier of the first repo whose project config names one (the repos of the issues it holds up come first, then those of the epic's other issues; where none does, the window says so), shows as parked (`awaits a human's task`) so that it doesn't take a running slot, and polls the epic every minute until the task no longer holds up an open issue. Then the issues it held up may start. A window that starts again, as after a reboot, DMs again.
- **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.
- **Finishing.** When the epic holds no open item: release-review passes on each repo the epic changed, then the items they file, then the human confirms each achieve goal and that no maintain goal has a defect. For a goal that isn't met, do-epic proposes items for approval. Then a summary comment on the epic, and closing the epic in Jira, as the very last step.
- **Tests.** Black-box tests run against a fake Jira backend. An opt-in e2e test runs as its own command against a sandbox epic on a real Jira site.
+6 -46
View File
@@ -6,19 +6,15 @@
`Bar = 0.1`
`Next ID = 443`
`Next ID = 444`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 416 | 0.12.0 | | | **Finish an epic's repo item with a bullet under its repo's `CHANGELOG.md` → `## Unreleased`, or with none where the repo's plan is in Jira.** | 1 | 1 | 1 | 1 | 2 | 1 by 5 | 2.1 |
| 420 | 0.12.0 | | | **End a worker that printed its final result and lingers, by killing the background shells it left, after a few minutes, and print each kill with its evidence on loop-claude's terminal.** | 2 | 2 | 2 | 4 | 3 | 1.5 by 6 | 2.0 |
| 414 | 0.12.0 | | | **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 | | | **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 |
| 440 | 0.12.0 | | | **End the shell that the interrupt test of `mutate-changes` starts within a minute, so a mutation run of this repo never waits on it for ever.** | 1 | 1 | 2 | 2 | 2 | 1 by 4 | 1.7 |
| 442 | 0.12.0 | | | **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 |
| 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 |
| 365 | 0.13.0 | | | **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.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.1 by 2 | 1.2 |
| 368 | 0.13.0 | | | **Call a release review due, call a release ready to cut, and tell whether a chunk owes a scoring run, for a plan outside the checkout, from the project repo's history or from Jira.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.1 by 2 | 1.2 |
@@ -49,6 +45,7 @@
| 68 | 0.14.0 | | principle | **Test `workflow-bench/compare.py`'s blinding and `bench.py`'s run plan.** | 2 | 1 | 1 | 2 | 4 | 1.1 by 5 | 1.5 |
| 102 | 0.14.0 | | | **Give loop-claude's retry delay, and the file it reads the machine's memory from, environment overrides, so the black-box test stops replacing `time.sleep` and `machine_load.memory.MEMINFO` through `sitecustomize`.** | 1 | 1 | 2 | 2 | 3 | 1.1 by 4 | 1.5 |
| 135 | 0.14.0 | | | **Fingerprint only the modules loop-claude imports, so editing another tool's code no longer reloads a running loop.** | 2 | 2 | 3 | 5 | 3 | 1.1 by 4 | 1.5 |
| 443 | 0.14.0 | | | **Measure whether compacting a waiting worker's session cut the cost of 20 chunks with an interrupt, with quality holding.** | 2 | 2 | 1 | 3 | 3 | 1.4 by 4 | 1.4 |
| 5 | 0.14.0 | | decision | **Key a project on its checkout's full path, and refuse to start while another session uses that key.** | 4 | 2 | 3 | 7 | 5 | 1.1 by 6 | 1.4 |
| 291 | 0.14.0 | | owner | **Let `principles/technical-principles.md` → "Sane defaults" allow a library whose README goals ask that it work with no config to default the clock and randomness in its public constructor, where a documented option overrides each.** | 1 | 2 | 3 | 4 | 1 | 1.2 by 3 | 1.3 |
| 156 | 0.14.0 | | decision | **Drop `rank_todo.py`'s ranking of an old-shape table once no project under `~/code` holds one.** | 2 | 1 | 3 | 4 | 4 | 1.1 by 4 | 1.2 |
@@ -72,14 +69,6 @@
## Details
### 416. Finish an epic's repo item with a bullet under its repo's `CHANGELOG.md` → `## Unreleased`, or with none where the repo's plan is in Jira.
An epic item has no release (`docs/decisions.md` → `do-epic: drives one Jira epic …`). do-epic runs `chunk-pr merge --finish` in the repo's checkout, and picks the flag by the repo's plan type.
Touches:
- `bin/do_epic/main.py`
### 420. End a worker that printed its final result and lingers, by killing the background shells it left, after a few minutes, and print each kill with its evidence on loop-claude's terminal.
On 2026-11-18 the worker of the item 402 chunk merged its pull request at about 11:47, printed its summary and then waited 95 minutes: it had started `until [ -s /tmp/merge-402.log ] && ! pgrep -f "chunk-pr merg"; do sleep 15; done` in the background, and `pgrep -f` matched the loop's own command line, so the condition never held. Its `claude -p` stayed alive ("Waiting for background work to finish"), `loop-claude` waited for it to exit, and the window's slot started no new chunk until the human found it and killed the shell.
@@ -96,15 +85,6 @@ Touches:
- `bin/loop_claude/loop/lingering_workers.py`
- `README.md`: `## Tools` (small)
### 414. DM the human through the notifier when a human-task issue blocks the epic's next item, and poll until it closes.
do-epic leaves the issue as the team filed it (`docs/decisions.md` → `do-epic: drives one Jira epic …`).
Touches:
- `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`.
The sandbox is the Jira site `larvit.atlassian.net`, project `SCRUM`: a team-managed test-data space with Epic, Task, Story and Subtask issue types. The test creates its own epic there, with children and sub-tasks, and deletes them when it ends, so it leaves the space's other issues alone. Its account may create, edit, transition, comment on and delete issues in `SCRUM`. The command reads the env-file's path, holding `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, from a setting of its own, never from the repo.
@@ -117,13 +97,6 @@ Touches:
- `bin/do-epic-e2e`
- `bin/do_epic/e2e/`
### 440. End the shell that the interrupt test of `mutate-changes` starts within a minute, so a mutation run of this repo never waits on it for ever.
Today a `mutate-changes` run on this repo can wait for ever: mutmut runs `bin/mutate_changes/test_mutate_changes.py` → `test_an_interrupt_reaches_the_tool_before_the_run_kills_it` inside its own process, where the test's SIGINT doesn't reach the `sh -c "trap … while :; do sleep 0.1; done"` it started. The shell then loops for good as mutmut's child, and mutmut waits for it. Three runs of two chunks hung this way on 2026-11-18, one for over two hours, each holding a heavy slot until someone killed the shell. Give the helper shell a deadline of its own, so it ends where no signal arrives, or leave the test out of what mutmut runs.
Touches:
- `bin/mutate_changes/test_mutate_changes.py`: `test_an_interrupt_reaches_the_tool_before_the_run_kills_it` (small)
### 442. 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.
@@ -137,23 +110,6 @@ Touches:
- `bin/do_epic/test_main.py`
- `README.md`: `## Tools`, `### Set up a project` (small)
### 310. Compact a waiting worker's session shortly before its prompt cache expires, only when the human has not answered an interrupt by then.
281 worker resumes after the 1-hour cache expired rewrote a whole context, $379 of the $9,154 measured from 2026-09-30 to 2026-11-11 (4.1%). A compaction while the cache is warm reads the context at a twentieth of the input price and leaves about 20k tokens to rewrite later.
lilleman, 2026-11-11: do it on a timer, so an answer that comes in time doesn't cost anything. When loop-claude interrupts, start a timer a margin short of the cache lifetime (about 50 minutes of a 1-hour cache; read the lifetime from the session's last `cache_creation` usage). If no answer has come when it fires, compact the session, then keep waiting. Skip it below about 60k tokens of context, where the rewrite costs less than the compaction. A wait for a usage limit can't be helped this way.
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/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)
- `bin/loop_claude/loop/usage.py`: `HELP` (small)
- `bin/loop_claude/test_loop_claude.py`: `FakeEffects`, `Interrupts`
- `bin/loop_effects/test_effects.py`
### 422. 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.
Item 420 ends a worker that printed its final result and lingers. A window can also stall earlier: a test run that hangs on a shell ignoring SIGINT (item 402's first full run), a pane with no output while its process tree does no work, or a background shell older than the chunk's usual length.
@@ -428,6 +384,10 @@ Found by the principles audit of PR #242. The `SITECUSTOMIZE` block in `bin/loop
The maintainability senior and the inherited architect of PR #257's scoring run named `fingerprint` and `exec_if_edited` in `bin/loop_claude/loop/reload.py`: the fingerprint covers every `bin/**/*.py`, so editing `statusline.py` or `rank_todo.py` re-execs a running loop. Make `fingerprint` easier to read.
### 443. Measure whether compacting a waiting worker's session cut the cost of 20 chunks with an interrupt, with quality holding.
The check lilleman set for item 310 on 2026-11-11, which project principle 1 asks for before a cost cut stands: compare the cost entries of 20 archived chunks with an interrupt from before the compaction shipped against 20 from after it. Measure the tokens written to the cache by each resume after an interrupt, and the tokens per finished chunk, and check that review rounds and unfinished verdicts per chunk hold. Where the saving doesn't show, or quality drops, file an item to remove the compaction or retune `COMPACT_FLOOR` and `CACHE_MARGIN` in `bin/loop_claude/cycle/interrupt.py`. Record the outcome as a decision. Start it once 20 chunks with an interrupt have run on 0.12.0 or later.
### 5. Key a project on its checkout's full path, and refuse to start while another session uses that key.
The key names the project's session, archive folder and models entry. `project_key`, in `bin/transcript_archive/project_key.py`, strips `~/code/` and then any leading `/`, so `~/code/a` and `/a` share all three, and one loop can resume or delete the other's session.