Keep a parked chunk out of the epic's and its repo's running slots

This commit is contained in:
2026-11-18 23:11:31 +01:00
parent 004c76679e
commit 1df19f4ac8
5 changed files with 148 additions and 16 deletions
+25 -3
View File
@@ -14,6 +14,8 @@ NEEDED = (3, 2)
# What a window's name ends in while its chunk waits for the human. tmux's status bar shows the name, and `!` after it once the bell rang.
WAITS = " ?"
BELL = "\a"
# What follows a window's name while its chunk is parked, before what its pull request waits on, as in `ABC-34 awaits an approval`. A parked chunk takes no running slot (docs/decisions.md → `do-epic: drives one Jira epic …`, "Long gates").
PARKED = " awaits "
# What a session's name opens with: LOOP for a project's chunks under loop-claude, EPIC for an epic's chunks under do-epic.
LOOP = "loop"
EPIC = "epic"
@@ -41,12 +43,14 @@ class Window:
@dataclasses.dataclass(frozen=True)
class Listed:
"""A window of the project's session, as tmux lists it."""
# Without WAITS.
# Without WAITS, and without PARKED and what follows it.
name: str
# tmux's ID of the window, such as `@3`.
id: str
# Whether its loop has exited: `remain-on-exit failed` keeps the window of a loop that failed, so its last lines stay readable.
dead: bool
# Whether its chunk is parked: its name held PARKED.
parked: bool = False
@dataclasses.dataclass(frozen=True)
@@ -76,14 +80,20 @@ def listed(session: str, run: Tmux) -> list[Listed]:
"""The windows of session; none where tmux lists none, as while the session doesn't exist or no tmux server runs."""
done = run(["list-windows", "-t", f"={session}", "-F", "#{window_name}\t#{pane_dead}\t#{window_id}"])
rows = [line.split("\t") for line in done.stdout.splitlines()] if done.returncode == 0 else []
return [Listed(row[0].removesuffix(WAITS), row[2], row[1] == "1") for row in rows if len(row) == 3]
return [as_listed(row[0], row[2], row[1]) for row in rows if len(row) == 3]
def as_listed(shown: str, id: str, pane_dead: str) -> Listed:
"""The window tmux shows under the name shown, with the ID id and `#{pane_dead}` as pane_dead."""
name, parked, _ = shown.removesuffix(WAITS).partition(PARKED)
return Listed(name, id, pane_dead == "1", bool(parked))
def everywhere(run: Tmux) -> list[Placed]:
"""The windows of every session; none where no tmux server runs."""
done = run(["list-windows", "-a", "-F", f"#{{session_name}}\t#{{window_name}}\t#{{pane_dead}}\t#{{window_id}}\t#{{{ROOT}}}"])
rows = [line.split("\t") for line in done.stdout.splitlines()] if done.returncode == 0 else []
return [Placed(row[0], Listed(row[1].removesuffix(WAITS), row[3], row[2] == "1"), row[4]) for row in rows if len(row) == 5]
return [Placed(row[0], as_listed(row[1], row[3], row[2]), row[4]) for row in rows if len(row) == 5]
def start_window(window: Window, cwd: str, env: typing.Mapping[str, str], command: list[str], first: bool, owned: bool, run: Tmux) -> Failure | None:
@@ -131,6 +141,18 @@ def mark(window: Window, waits: bool, run: Tmux) -> None:
run(["rename-window", "-t", window.pane, window.name + (WAITS if waits else "")])
def park(window: Window, on: str, run: Tmux) -> None:
"""Shows window's chunk as parked while its pull request awaits on, such as `an approval`: the name says so, and the window names no folder its chunk works in, so no checkout counts it as a running chunk."""
run(["rename-window", "-t", window.pane, window.name + PARKED + on])
run(["set-option", "-w", "-u", "-t", window.pane, ROOT])
def unpark(window: Window, root: str, run: Tmux) -> None:
"""Shows window's chunk as running again, in the folder root."""
run(["rename-window", "-t", window.pane, window.name])
run(["set-option", "-w", "-t", window.pane, ROOT, root])
def show(session: str, inside: bool) -> list[str]:
"""The tmux arguments that put session on the human's terminal: inside tmux the client switches to it, and outside a new client attaches."""
return ["switch-client" if inside else "attach-session", "-t", f"={session}"]
+41 -9
View File
@@ -1,11 +1,13 @@
"""Which of an epic's issues run as chunks now, each in its own window of the epic's tmux session (docs/decisions.md → `do-epic: drives one Jira epic …`).
Three limits hold a chunk back: the epic's cap of chunks at once, its repo's `parallel-chunks`, counted across every epic, and a loop-claude that runs chunks in its repo. do-epic checks a repo and starts a chunk in it while holding the lock loop-claude holds when it starts one (`chunk_windows.starting`), so the two never start chunks in one checkout together."""
Three limits hold a chunk back: the epic's cap of chunks at once, its repo's `parallel-chunks`, counted across every epic, and a loop-claude that runs chunks in its repo. A parked chunk (`parked`) counts toward none of them: its window only polls the forge, and `resume` takes it a slot under the same limits once its worker has something to do. do-epic checks a repo and starts a chunk in it while holding the lock loop-claude holds when it starts one (`chunk_windows.starting`), so the two never start chunks in one checkout together."""
import dataclasses
import pathlib
import typing
from chunk_pr.approval import PARKS
from do_epic.epic_record import CAP
from do_epic.parked import parked_chunks
from loop_claude.loop.chunk_windows import epic_chunks, HANDED, LOCK, project_lock, starting
from do_epic.backend.protocol import EpicIssue
from failure import Failure
@@ -107,24 +109,33 @@ def refusal(repo: str, room: RepoRoom) -> str | None:
def start_chunks(epic: Epic, issues: list[EpicIssue], own: str | None, run: tmux.Tmux) -> Started | Failure:
"""Starts a do-epic in a new window for each of the epic's chunks that may start now. own is the issue of the chunk that asks, which has finished: it counts as running nowhere, and no stopped chunk starts again. Where own is None, the human's `do-epic <EPIC-KEY>` asks, and each stopped chunk starts again. A Failure says why a window could not start; those before it run."""
"""Starts a do-epic in a new window for each of the epic's chunks that may start now. own is the issue of the chunk that asks, which has finished or parked: it counts as running nowhere, and no stopped chunk starts again. Where own is None, the human's `do-epic <EPIC-KEY>` asks, and each stopped chunk starts again. A parked chunk waits in its window; one without a live window, as after a reboot, starts again as a stopped chunk does, whatever the limits, since it goes on parked. A Failure says why a window could not start; those before it run."""
session = tmux.session_name(tmux.EPIC, epic.key)
found, waits = chunks(issues)
started: list[str] = []
parked = parked_chunks(epic.folder)
if isinstance(parked, Failure):
return parked
try:
with starting(epic.folder):
windows = tmux.listed(session, run)
running = {window.name for window in windows if not window.dead} - {own}
stopped = {window.name for window in windows if window.dead} - running
live = {window.name for window in windows if not window.dead} - {own}
running = {window.name for window in windows if not window.dead and not window.parked} - {own}
stopped = {window.name for window in windows if window.dead} - live
# The windows this call started that take a running slot.
taken = 0
for chunk in found:
if chunk.issue in running or chunk.issue == own:
continue
if own and chunk.issue in stopped:
if chunk.issue in parked and chunk.issue in live:
waits.append(Waits(chunk.issue, parked[chunk.issue].waits))
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 len(running) + len(started) >= epic.cap:
elif chunk.issue not in parked 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, own, windows, run)
now = start_chunk(epic, chunk if chunk.issue not in parked else Chunk(chunk.issue, None), own, windows, run)
taken += chunk.issue not in parked
if isinstance(now, Failure):
return now
if isinstance(now, str):
@@ -138,9 +149,10 @@ def start_chunks(epic: Epic, issues: list[EpicIssue], own: str | None, run: tmux
def start_chunk(epic: Epic, chunk: Chunk, own: str | None, windows: list[tmux.Listed], run: tmux.Tmux) -> list[tmux.Listed] | str | Failure:
"""Starts chunk's window beside windows, the epic's session's, and returns the session's windows afterwards; the reason where its repo takes no chunk now, and a Failure where tmux started none. It holds the repo's lock from the check to the start. Raises OSError where that lock cannot be taken."""
"""Starts chunk's window beside windows, the epic's session's, and returns the session's windows afterwards; the reason where its repo takes no chunk now, and a Failure where tmux started none. It holds the repo's lock from the check to the start. Raises OSError where that lock cannot be taken. A chunk without a repo starts in the epic's folder, as a parked chunk does, which takes no room in its repo."""
session = tmux.session_name(tmux.EPIC, epic.key)
handed = {name: value for name, value in epic.env.items() if name.startswith(HANDED)}
# PARKS reaches the chunk's worker, so its `chunk-pr merge` doesn't wait for an approval the parked chunk waits for.
handed = {**{name: value for name, value in epic.env.items() if name.startswith(HANDED)}, PARKS: "1"}
command = [str(epic.launcher), CHUNK_FLAG, chunk.issue, epic.key]
if chunk.repo is None:
return tmux.start_chunk(tmux.Window(session, chunk.issue, ""), str(epic.folder), handed, command, windows, False, run)
@@ -160,3 +172,23 @@ def room_in(checkout: str, limit: int, leaving: tuple[str, str | None], home: pa
loop_session = tmux.session_name(tmux.LOOP, project_key(checkout, home))
loops = any(not window.dead for window in tmux.listed(loop_session, run)) and tmux.owner(loop_session, run) == checkout
return RepoRoom(limit, len(theirs), loops)
def resume(epic: Epic, repo: str, window: tmux.Window, run: tmux.Tmux) -> str | None:
"""Takes a running slot for the parked chunk in window, which changes repo and whose worker has something to do again: None once the window counts as a running chunk, else why the chunk still waits. The limits are those a starting chunk meets, checked under the same locks."""
try:
with starting(epic.folder):
running = [listed for listed in tmux.listed(window.session, run) if not listed.dead and not listed.parked]
if len(running) >= epic.cap:
return f"the epic runs as many chunks as its `{CAP}` line allows: {epic.cap}"
located = epic.locate(repo)
if isinstance(located, Failure):
return located.reason
checkout, limit = located
with starting(project_lock(str(checkout), epic.home)):
if reason := refusal(repo, room_in(str(checkout), limit, (window.session, None), epic.home, run)):
return reason
tmux.unpark(window, str(checkout), run)
return None
except OSError as failure:
return f"cannot lock {failure.filename or epic.folder / LOCK}: {failure.strerror}"
+1 -1
View File
@@ -89,7 +89,7 @@ class TheCommand(DoEpicTest):
self.assertIn("started ABC-21 in the tmux session epic-ABC-12\n", out)
self.assertIn("ABC-20 waits: no label names its repo\n", out)
started = [args for args in fake.tmux_calls if args[0] == "new-session"]
self.assertEqual(started, [["new-session", "-d", "-s", "epic-ABC-12", "-n", "ABC-21", "-c", str(self.home / ".local/state/do-epic/ABC-12"), "-e", "LOOP_CLAUDE_WORKER_MODEL=m", "-P", "-F", "#{window_id}", "--", "/b/do-epic", "--chunk", "ABC-21", "ABC-12"]])
self.assertEqual(started, [["new-session", "-d", "-s", "epic-ABC-12", "-n", "ABC-21", "-c", str(self.home / ".local/state/do-epic/ABC-12"), "-e", "LOOP_CLAUDE_WORKER_MODEL=m", "-e", "CHUNK_PR_PARKS=1", "-P", "-F", "#{window_id}", "--", "/b/do-epic", "--chunk", "ABC-21", "ABC-12"]])
# The session is no checkout's, so nothing marks it as one's.
self.assertNotIn(tmux.OWNER, [args[3] for args in fake.tmux_calls if args[0] == "set-option"])
+79 -1
View File
@@ -6,7 +6,8 @@ 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, start_chunks, Started, Waits
from do_epic.scheduler import Chunk, CHUNK_FLAG, chunks, Epic, refusal, RepoRoom, resume, start_chunks, Started, Waits
from do_epic.parked import file_of, park, Parked
from do_epic import chunk_prompt
from do_epic.backend.protocol import EpicIssue
from failure import Failure
@@ -102,6 +103,12 @@ class Tmux:
session = args[args.index("-s") + 1] if args[0] == "new-session" else args[args.index("-t") + 1].removeprefix("=").removesuffix(":")
self.windows.append((session, args[args.index("-n") + 1], False, args[args.index("-c") + 1]))
out = f"@{len(self.windows) - 1}\n"
elif args[0] == "rename-window":
at = int(args[2].removeprefix("%"))
self.windows[at] = (self.windows[at][0], args[3], *self.windows[at][2:])
elif args[0] == "set-option" and tmux.ROOT in args:
at = int(args[args.index("-t") + 1].removeprefix("%").removeprefix("@"))
self.windows[at] = (*self.windows[at][:3], "" if "-u" in args else args[-1])
elif args[0] == "kill-window":
self.windows[int(args[2].removeprefix("@"))] = ("", "", True, "")
return subprocess.CompletedProcess(args, 0, out, "")
@@ -137,6 +144,77 @@ class StartingAnEpicsChunks(unittest.TestCase):
self.assertIn("LOOP_CLAUDE_X=1", run.calls[[args[0] for args in run.calls].index("new-session")])
self.assertNotIn("OTHER=2", run.calls[[args[0] for args in run.calls].index("new-session")])
def parked(self, issue_key: str, on: str = "an approval") -> None:
self.assertIsNone(park(self.home / ".local/state/do-epic/ABC-12", Parked(issue_key, f"/code/api-{issue_key}", "7", "0c0f", on)))
def test_a_parked_chunk_waits_in_its_window_and_takes_no_slot_of_the_epic_or_its_repo(self) -> None:
self.parked("ABC-20")
run = Tmux(("epic-ABC-12", "ABC-20 awaits an approval", False, ""))
found = self.start(self.epic(1, api=1), [issue("ABC-20", "repo:api"), issue("ABC-21", "repo:api"), issue("ABC-22", "repo:api", blockers=("ABC-20",))], run)
self.assertEqual(found, Started(["ABC-21"], [Waits("ABC-20", "it is parked: its pull request #7 awaits an approval"), Waits("ABC-22", "ABC-20 blocks it")]))
def test_a_parked_chunk_without_a_window_starts_again_whatever_the_limits_in_the_epics_folder(self) -> None:
self.parked("ABC-20")
for windows in ((), (("epic-ABC-12", "ABC-20 awaits an approval", True, ""),)):
with self.subTest(windows=windows):
run = Tmux(*windows, ("epic-ABC-12", "ABC-21", False, str(self.home / "code/api")))
found = self.start(self.epic(1, api=1), [issue("ABC-20", "repo:api"), issue("ABC-21", "repo:api")], run)
self.assertEqual(found, Started(["ABC-20"], []))
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_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())
self.assertEqual(found, Started(["ABC-20", "ABC-21"], []))
def test_a_chunk_that_hands_on_starts_no_parked_chunk_whose_window_stopped(self) -> None:
self.parked("ABC-20")
found = self.start(self.epic(2, api=2), [issue("ABC-20", "repo:api"), issue("ABC-21", "repo:api")], Tmux(), own="ABC-21")
self.assertEqual(found, Started([], [Waits("ABC-20", "its window stopped; run `do-epic ABC-12` to start it again")]))
def test_a_chunk_that_parks_frees_its_slot_for_the_next(self) -> None:
self.parked("ABC-20")
run = Tmux(("epic-ABC-12", "ABC-20 awaits an approval", False, ""))
found = self.start(self.epic(1, api=1), [issue("ABC-20", "repo:api"), issue("ABC-21", "repo:api")], run, own="ABC-20")
self.assertEqual(found, Started(["ABC-21"], []))
def test_stops_on_a_parked_chunk_it_cannot_read_and_starts_none(self) -> None:
self.parked("ABC-20")
file_of(self.home / ".local/state/do-epic/ABC-12", "ABC-20").write_text("{")
run = Tmux()
found = start_chunks(self.epic(2, api=2), [issue("ABC-21", "repo:api")], None, run)
assert isinstance(found, Failure)
self.assertIn("cannot read the parked chunk in ", found.reason)
self.assertEqual(run.started(), [])
def test_hands_each_chunk_the_variable_that_makes_its_merge_park(self) -> None:
run = Tmux()
self.start(self.epic(1, api=1), [issue("ABC-20", "repo:api")], run)
self.assertIn("CHUNK_PR_PARKS=1", run.calls[[args[0] for args in run.calls].index("new-session")])
def resumed(self, epic: Epic, run: Tmux) -> str | None:
"""resume for the parked chunk in the first window, which changes the repo api."""
return resume(epic, "api", tmux.Window("epic-ABC-12", "ABC-20", "%0"), run)
def test_a_parked_chunk_resumes_into_a_free_slot_and_counts_in_its_repo_again(self) -> None:
run = Tmux(("epic-ABC-12", "ABC-20 awaits an approval", False, ""), ("epic-ABC-12", "ABC-21 awaits its checks", False, ""))
self.assertIsNone(self.resumed(self.epic(1, api=1), run))
self.assertEqual(run.windows[0], ("epic-ABC-12", "ABC-20", False, str(self.home / "code/api")))
def test_a_parked_chunk_stays_parked_while_the_epic_or_its_repo_is_full(self) -> None:
parked = ("epic-ABC-12", "ABC-20 awaits an approval", False, "")
cases = {
"the epic runs as many chunks as its `**Max parallel chunks:**` line allows: 1": (self.epic(1, api=2), Tmux(parked, ("epic-ABC-12", "ABC-21", False, str(self.home / "code/web")))),
"api runs as many chunks as its `parallel-chunks` allows: 1": (self.epic(2, api=1), Tmux(parked, ("epic-XYZ-1", "XYZ-5", False, str(self.home / "code/api")))),
"loop-claude runs chunks in api": (self.epic(2, api=1), Tmux(parked, ("loop-api", "item-3", False, str(self.home / "code/api")), owners={"loop-api": str(self.home / "code/api")})),
"no project config names api": (self.epic(2), Tmux(parked)),
}
for reason, (epic, run) in cases.items():
with self.subTest(reason=reason):
self.assertEqual(self.resumed(epic, run), reason)
self.assertEqual(run.windows[0], parked)
def test_a_running_chunk_counts_and_is_not_started_twice(self) -> None:
run = Tmux(("epic-ABC-12", "ABC-20 ?", False, str(self.home / "code/api")))
found = self.start(self.epic(2, api=2), [issue("ABC-20", "repo:api"), issue("ABC-21", "repo:api"), issue("ABC-22", "repo:api")], run)
+2 -2
View File
@@ -66,8 +66,8 @@ def project_lock(root: str, home: pathlib.Path) -> pathlib.Path:
def epic_chunks(root: str, run: tmux.Tmux) -> list[tmux.Placed]:
"""The windows of do-epic's sessions whose chunks run in the checkout root."""
return [placed for placed in tmux.everywhere(run) if placed.session.startswith(f"{tmux.EPIC}-") and placed.root == root and not placed.window.dead]
"""The windows of do-epic's sessions whose chunks run in the checkout root. A parked chunk doesn't run."""
return [placed for placed in tmux.everywhere(run) if placed.session.startswith(f"{tmux.EPIC}-") and placed.root == root and not placed.window.dead and not placed.window.parked]
def held_items(chunks: typing.Iterable[str], key: str, claude_code_transcripts: pathlib.Path) -> set[int]: