Answer stability round 1: 0 🔴, 5 🟡 (0 misread); park the window first, resend a failed DM, reword docstrings and trim two tests

This commit is contained in:
2026-11-19 02:44:22 +01:00
parent d652ab20d3
commit 7ed020490c
5 changed files with 60 additions and 31 deletions
+24 -8
View File
@@ -1,9 +1,13 @@
"""A human's task that holds up other issues of an epic (docs/decisions.md → `do-epic: drives one Jira epic …`, "Human tasks").
do-epic leaves the issue as the team filed it. While it is open and blocks an open issue, its window DMs the human once, shows itself as parked so that it takes no running slot, and reads the epic every `poll` seconds. Once the issue is closed, or blocks nothing any more, the window ends, and the chunks it held up may start. A window that starts again, as after a reboot, DMs again."""
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
@@ -13,18 +17,29 @@ 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, or is closed."""
"""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)}. It goes on once you close {task.key} in Jira."
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 awaited(task: EpicIssue, epic: str, store: EpicStore, window: tmux.Window, poll: int, 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 holds up no issue. A read of the epic that fails is said once and tried again."""
def checkout_of(held: list[EpicIssue], home: pathlib.Path) -> str | None:
"""The checkout of the first issue of held whose repo a project config names: where the DM finds its notifier, since the window runs in no checkout. None where there is none, and the DM goes by the current directory."""
for issue in held:
pick = recorded(issue)
found = by_name(pick.name, home) if isinstance(pick, Repo) else None
if isinstance(found, ProjectConfig):
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()
@@ -35,7 +50,8 @@ def awaited(task: EpicIssue, epic: str, store: EpicStore, window: tmux.Window, p
elif not (held := holds_up(task.key, issues)):
return
elif not told:
tell(message(task, epic, held), effects)
tmux.park(window, AWAITS, effects.tmux)
told = True
text = message(task, epic, held)
say(text, effects, stdout=True)
by_key = {issue.key: issue for issue in issues}
told = tell(text, effects, checkout_of([by_key[key] for key in held], home))
effects.sleep(poll)
+6 -6
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
@@ -46,8 +46,8 @@ 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.
A `do-epic-human` issue that blocks another gets a window too: it DMs you once and waits, with no running slot, until you close the issue in Jira.
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
@@ -62,7 +62,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.
@@ -227,7 +227,7 @@ 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>")
@@ -236,7 +236,7 @@ def chunk_run(key: str, epic: EpicRun) -> Stop:
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.effects)
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):
@@ -340,7 +340,7 @@ def issue_read(key: str, epic: EpicRun) -> EpicIssue | Stop:
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, and its issue is None. The chunk keeps both to its end, whatever its issue's labels become. The stop where the labels make the issue no chunk."""
"""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)
+5 -5
View File
@@ -20,7 +20,7 @@ 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 until its issue closes"
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"
@@ -31,7 +31,7 @@ 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 takes no running slot.
# 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
@@ -87,7 +87,7 @@ def open_blockers(issue: EpicIssue, by_key: dict[str, EpicIssue]) -> list[str]:
def held_up(issues: list[EpicIssue]) -> dict[str, list[str]]:
"""For each issue that blocks an open issue to work as a chunk, the keys of the open issues it blocks, in the tracker's rank order."""
"""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:
@@ -98,7 +98,7 @@ def held_up(issues: list[EpicIssue]) -> dict[str, list[str]]:
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 is a chunk only while it holds up another issue and nothing holds it up: its window waits for the human."""
"""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] = []
@@ -241,5 +241,5 @@ def status(key: str, home: pathlib.Path, issues: list[EpicIssue], run: tmux.Tmux
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 [f"{issue.key} waits: {reasons[issue.key]}" if issue.key in reasons else f"{issue.key} runs" for issue in issues if issue.key in reasons or issue.key in live]
+23 -10
View File
@@ -5,9 +5,12 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic.test_main import DESCRIPTION, Description, DoEpicTest, MODELS, UNREAD
from project_config.test_project_config import configured
from do_epic.test_main import 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
@@ -40,10 +43,27 @@ class AHumanTaskThatBlocksAnIssue(DoEpicTest):
code, out, err = self.awaited(fake, closes_after=3)
self.assertEqual((code, err), (0, ""))
self.assertEqual(self.slept, [60, 60, 60])
self.assertEqual(fake.dms, ["do-epic ABC-12 awaits you: ABC-19, \"Order the test certificate\", blocks ABC-21. It goes on once you close ABC-19 in Jira."])
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, [None])
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(self) -> None:
checkout = self.home / "code" / "api"
configured(self, checkout, home=self.home)
self.epic.change("ABC-21", labels=("repo:api",))
fake = FakeEffects(git=UNREAD, windows=WINDOW)
self.awaited(fake, closes_after=1)
self.assertEqual(fake.dm_directories, [str(checkout)])
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",))])
@@ -53,13 +73,6 @@ class AHumanTaskThatBlocksAnIssue(DoEpicTest):
self.assertEqual(len(fake.dms), 1)
self.assertIn("the chunk finished; started ABC-21, ABC-30\n", out)
def test_the_window_takes_no_running_slot_when_it_starts_the_next_chunk(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_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)
@@ -99,7 +112,7 @@ class AHumanTaskThatBlocksAnIssue(DoEpicTest):
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(), ["ABC-19 waits: it is a human's task; do-epic polls until its issue closes", "ABC-21 waits: ABC-19 blocks it"])
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="")
+2 -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
@@ -189,7 +189,7 @@ class StartingAnEpicsChunks(unittest.TestCase):
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", "it is a human's task; do-epic polls until its issue closes"), Waits("ABC-21", "ABC-19 blocks it")]))
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: