code-coordinator 0.5.650__tar.gz → 0.5.652__tar.gz

{code_coordinator-0.5.650 → code_coordinator-0.5.652}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.650
+Version: 0.5.652
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.650 → code_coordinator-0.5.652}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.650
+Version: 0.5.652
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.650 → code_coordinator-0.5.652}/code_coordinator.egg-info/SOURCES.txt

@@ -459,6 +459,7 @@ tests/test_agent_config_free_1712.py
 tests/test_agent_deploy_units_endpoint.py
 tests/test_agent_dirty_worktree.py
 tests/test_agent_drive_queue_reconcile_2373.py
+tests/test_agent_graceful_shutdown_3649.py
 tests/test_agent_graph_refresh.py
 tests/test_agent_graph_self_heal.py
 tests/test_agent_health_h3.py

{code_coordinator-0.5.650 → code_coordinator-0.5.652}/code_coordinator.egg-info/scm_file_list.json

@@ -486,6 +486,7 @@
     "tests/test_agent_deploy_units_endpoint.py",
     "tests/test_agent_dirty_worktree.py",
     "tests/test_agent_drive_queue_reconcile_2373.py",
+    "tests/test_agent_graceful_shutdown_3649.py",
     "tests/test_agent_graph_refresh.py",
     "tests/test_agent_graph_self_heal.py",
     "tests/test_agent_health_h3.py",

{code_coordinator-0.5.650 → code_coordinator-0.5.652}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.650",
+  "tag": "0.5.652",
   "distance": 0,
-  "node": "gf6c0cf969776e35085b65dc340c118b19733079d",
+  "node": "g2167c3f211f76ec7abfbb32385f06f098cb6c877",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-10-18"

{code_coordinator-0.5.650 → code_coordinator-0.5.652}/coord/auto_loop.py

@@ -64,6 +64,8 @@ from coord.review import (
     dispatch_review,
     estimate_review_counts,
     maybe_scoped_review_for_completed_fix,
+    mechanical_gate_kind,
+    needs_redesign_escalation,
     parse_review_from_agent,
     parse_review_from_log,
 )
@@ -148,6 +150,11 @@ class LoopAction:
                                  for bookkeeping only (``dispatch_fixes=False``
                                  — the daemon drain, which must never spawn a
                                  fix worker; #476/#477)
+    - ``"needs_redesign"``     — #3721: the SAME structurally-unfixable
+                                 mechanical gate (sealed-path, breaking public
+                                 API) fired twice in a row for this issue; the
+                                 issue was parked with a durable escalation
+                                 instead of dispatching another fix round
     """
     assignment_id: str | None
     detail: str = ""
@@ -1126,6 +1133,30 @@ def _dispatch_fix_for_review(
             ),
         )]
 
+    # #3721: a mechanical request-changes verdict (sealed-path tamper,
+    # breaking-public-API semver check — the only two gate kinds a diff to
+    # THIS work leg can never satisfy without also breaking another
+    # unconditional rule) that fires for the SECOND time in a row on this
+    # issue means another fix round is pure churn, not a chance to improve.
+    # Park it with a durable escalation instead of re-dispatching. Checked
+    # only for mechanical verdicts — a real reviewer's request-changes
+    # always gets its normal fix round, however many times it repeats.
+    if review.verdict_source == "mechanical":
+        gate_kind = mechanical_gate_kind(review.verdict_source_reason)
+        escalation_reason = needs_redesign_escalation(
+            work, review, board, gate_kind=gate_kind,
+        )
+        if escalation_reason is not None:
+            log.warning(
+                "auto_loop: NOT dispatching fix for %s — %s",
+                work.assignment_id, escalation_reason,
+            )
+            return [LoopAction(
+                kind="needs_redesign",
+                assignment_id=review.assignment_id,
+                detail=escalation_reason,
+            )]
+
     # Compute the next iteration number and check the limit.  #3322: read it
     # off the WHOLE branch chain, not off `work` alone — the stalled-pipeline
     # sweep reaches this function with `work` bound to the ORIGINAL

{code_coordinator-0.5.650 → code_coordinator-0.5.652}/coord/commands/agent_ops.py

@@ -33,6 +33,20 @@ from coord.commands._common import (
 )
 
 
+# #3649: the macmini incident — uvicorn's default `timeout_graceful_shutdown`
+# is `None`, which means "wait forever" for in-flight requests/background
+# tasks to finish before exiting. The agent's own `/health` run can take
+# tens of seconds under CPU load (the observed log sequence was `Shutting
+# down` -> `Waiting for connections to close` -> `Waiting for background
+# tasks to complete`, then nothing further — no new `Started server
+# process`, port never freed). A bounded ceiling here means a shutdown
+# signal always produces a process exit within this many seconds, so
+# launchd's `KeepAlive`/`ThrottleInterval` actually gets a chance to fire
+# instead of waiting on a process that is still "running" but wedged in
+# shutdown.
+AGENT_GRACEFUL_SHUTDOWN_TIMEOUT_S = 30
+
+
 @click.group(
     invoke_without_command=True,
     help=(
@@ -447,7 +461,16 @@ def _start_agent_server(
         f"listening on http://{bind_host}:{bind_port}"
     )
     try:
-        uvicorn.run(app, host=bind_host, port=bind_port, log_level="info")
+        uvicorn.run(
+            app,
+            host=bind_host,
+            port=bind_port,
+            log_level="info",
+            # #3649: bound how long shutdown waits on in-flight
+            # requests/background tasks — see the module-level constant's
+            # docstring for why unbounded is a real outage.
+            timeout_graceful_shutdown=AGENT_GRACEFUL_SHUTDOWN_TIMEOUT_S,
+        )
     finally:
         server.shutdown()
 

{code_coordinator-0.5.650 → code_coordinator-0.5.652}/coord/review.py

@@ -3441,6 +3441,131 @@ def _record_prereview_gate_verdict(
     )
 
 
+# (#3721) Mechanical gate kinds that are structurally unfixable within the
+# SAME work leg: no further diff can satisfy this gate while also satisfying
+# the rule that required it, so re-dispatching another fix round is pure
+# churn, not a chance to improve. Deliberately narrow — every OTHER
+# mechanical kind (``coordinator_doc``, ``lane_entrypoint_weakened``, a
+# generic ``prereview_gate`` finding) is fixable by a diff that simply stops
+# making the forbidden edit, so a repeat there is worker error, not a wall.
+NEEDS_REDESIGN_GATE_KINDS: frozenset[str] = frozenset(
+    {"sealed_path", "breaking_public_api"}
+)
+
+NEEDS_REDESIGN_ALERT_STAGE = "needs-redesign"
+
+_NEEDS_REDESIGN_GATE_DESCRIPTION: dict[str, str] = {
+    "sealed_path": (
+        "sealed-path violation — the fix would require editing a sealed "
+        "path (tests/acceptance/**), which is itself an unconditional "
+        "request-changes under this repo's own rules, so no single diff "
+        "can satisfy both at once"
+    ),
+    "breaking_public_api": (
+        "breaking public-API change flagged by the semver check — cannot "
+        "be resolved by further edits to this same PR; needs a "
+        "non-breaking redesign or the deprecate-first two-PR protocol"
+    ),
+}
+
+
+def mechanical_gate_kind(reason: str | None) -> str:
+    """Classify a mechanical ``verdict_source_reason`` into a stable
+    gate-kind tag (#3721).
+
+    Works off the reason TEXT rather than a persisted field, so it
+    classifies both freshly-recorded and historical ``board.completed``
+    rows identically, with no schema/signature change: every reason string
+    produced by :func:`_record_mechanical_review_verdict` or
+    :func:`_record_prereview_gate_verdict` already starts with one of
+    these stable prefixes.
+    """
+    if not reason:
+        return "other"
+    if reason.startswith("sealed path(s) violated:"):
+        return "sealed_path"
+    if reason.startswith("coordinator-owned doc(s) edited:"):
+        return "coordinator_doc"
+    if reason.startswith("Tier-2 lane smoke-spec entry point weakened:"):
+        return "lane_entrypoint_weakened"
+    if "semver check failed (" in reason:
+        return "breaking_public_api"
+    if reason.startswith("prereview mechanical gate:"):
+        return "prereview_gate"
+    return "other"
+
+
+def needs_redesign_escalation(
+    work: Assignment,
+    review: Assignment,
+    board: Board,
+    *,
+    gate_kind: str,
+) -> str | None:
+    """(#3721) Decide whether *work*'s issue should be parked as
+    needs-redesign instead of dispatching yet another fix round.
+
+    Returns the escalation reason once *gate_kind* is one of
+    :data:`NEEDS_REDESIGN_GATE_KINDS` AND this is at least the SECOND time
+    a mechanical verdict of that same kind has fired for this issue —
+    counted off ``board.completed`` (which reflects the full DB history,
+    not just this process's lifetime), excluding *review* itself so the
+    verdict that triggered this call isn't double-counted as its own
+    predecessor. A worker gets exactly one mechanical bounce on an eligible
+    gate before this escalates, since a lone occurrence could still be a
+    trivial mistake rather than the structural wall the issue describes.
+
+    Returns ``None`` (dispatch the fix as usual) for every other case:
+    *gate_kind* not eligible, or this is its first occurrence. Writes the
+    durable escalation itself (best-effort — a write failure here must not
+    block the caller's own fallback behavior) so the caller only needs to
+    check for a non-``None`` return to skip dispatch.
+    """
+    if gate_kind not in NEEDS_REDESIGN_GATE_KINDS:
+        return None
+    prior = sum(
+        1
+        for a in board.completed
+        if a.type == "review"
+        and a.assignment_id != review.assignment_id
+        and a.repo_name == work.repo_name
+        and a.issue_number == work.issue_number
+        and a.verdict_source == "mechanical"
+        and mechanical_gate_kind(a.verdict_source_reason) == gate_kind
+    )
+    if prior < 1:
+        return None
+    occurrences = prior + 1
+    description = _NEEDS_REDESIGN_GATE_DESCRIPTION.get(gate_kind, gate_kind)
+    reason = (
+        f"needs-redesign (#3721): {work.repo_name}#{work.issue_number} hit "
+        f"the same structurally-unfixable mechanical gate {occurrences} "
+        f"times in a row — {description}. Latest finding: "
+        f"{review.verdict_source_reason}"
+    )
+    try:
+        from coord.state import record_drive_escalation  # noqa: PLC0415
+
+        record_drive_escalation(
+            work.repo_name,
+            work.issue_number,
+            stage=NEEDS_REDESIGN_ALERT_STAGE,
+            reason=reason,
+            gate_readings=f"gate_kind={gate_kind} occurrences={occurrences}",
+            proposed_command=(
+                f"coord drive-queue remove {work.repo_name} {work.issue_number}"
+            ),
+            assignment_id=work.assignment_id,
+        )
+    except Exception as exc:  # noqa: BLE001 — the log line below is the floor
+        log.warning(
+            "auto_loop: failed to record needs-redesign escalation for "
+            "%s#%s: %s",
+            work.repo_name, work.issue_number, exc,
+        )
+    return reason
+
+
 def dispatch_review(
     completed: Assignment,
     board: Board,

code_coordinator-0.5.652/tests/test_agent_graceful_shutdown_3649.py

@@ -0,0 +1,82 @@
+"""#3649: `coord agent`'s uvicorn server must bound how long shutdown waits
+on in-flight requests/background tasks.
+
+The macmini incident: uvicorn's default `timeout_graceful_shutdown` is
+`None` — wait forever. Under CPU load, a slow `/health` call (served via
+`asyncio.to_thread`) was still in flight when a shutdown signal arrived, so
+the process logged `Shutting down` -> `Waiting for connections to close` ->
+`Waiting for background tasks to complete` and then never exited. Because
+the process never actually *died*, launchd's `KeepAlive`/`ThrottleInterval`
+never got a chance to restart it — that logic fires on process death, not on
+"looks stuck". The fix is a bounded ceiling passed into `uvicorn.run`, so a
+shutdown signal always produces an exit within a known number of seconds.
+
+This test asserts the wiring end-to-end through `_start_agent_server` (not
+just that the constant exists) — a regression that drops the kwarg or
+silently passes `None` again must fail here.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import coord.commands.agent_ops as agent_ops
+
+
+class _FakeAgentServer:
+    """Records construction kwargs; `shutdown()` is a no-op so the test
+    never touches a real process table."""
+
+    instances: list["_FakeAgentServer"] = []
+
+    def __init__(self, **kwargs) -> None:
+        self.kwargs = kwargs
+        self.shutdown_called = False
+        _FakeAgentServer.instances.append(self)
+
+    def shutdown(self, *, kill_running: bool = False) -> None:
+        self.shutdown_called = True
+
+
+def _fake_build_app(server, *, idle_restart: bool = False):
+    # #2139's watcher is a background thread for the life of the real
+    # process — never actually start it under test.
+    return object()
+
+
+class TestAgentGracefulShutdownIsBounded:
+    def test_uvicorn_run_gets_a_bounded_graceful_shutdown_timeout(
+        self, tmp_path: Path, monkeypatch
+    ) -> None:
+        captured: dict = {}
+
+        def _fake_uvicorn_run(app, **kwargs):
+            captured.update(kwargs)
+
+        monkeypatch.setattr("uvicorn.run", _fake_uvicorn_run)
+        # `_start_agent_server` imports these function-local (#1237), so the
+        # names it resolves at call time are these modules' own attributes —
+        # patch those, not `agent_ops`'s namespace.
+        monkeypatch.setattr("coord.agent.AgentServer", _FakeAgentServer)
+        monkeypatch.setattr("coord.agent_app.build_app", _fake_build_app)
+
+        absent_config = tmp_path / "no-such-dir" / "coordinator.yml"
+        assert not absent_config.exists()
+
+        agent_ops._start_agent_server(
+            absent_config, "ephemeral-1", "127.0.0.1", 7433
+        )
+
+        assert "timeout_graceful_shutdown" in captured
+        assert captured["timeout_graceful_shutdown"] == (
+            agent_ops.AGENT_GRACEFUL_SHUTDOWN_TIMEOUT_S
+        )
+        # Not the uvicorn default — a regression that silently passes `None`
+        # again (wait forever) must fail here, not just "kwarg present".
+        assert captured["timeout_graceful_shutdown"] is not None
+        assert captured["timeout_graceful_shutdown"] > 0
+
+    def test_constant_is_a_real_bound_not_a_token_value(self) -> None:
+        """A ceiling of 0 or an absurdly large number defeats the point —
+        it must be a genuinely bounded, human-scale number of seconds."""
+        assert 0 < agent_ops.AGENT_GRACEFUL_SHUTDOWN_TIMEOUT_S <= 120

{code_coordinator-0.5.650 → code_coordinator-0.5.652}/tests/test_auto_loop.py

@@ -3868,6 +3868,133 @@ class TestDispatchFixReachabilityFallback:
         assert "--machine" in actions[0].detail
 
 
+# ── #3721: needs-redesign escalation instead of churning the same gate ───────
+
+
+class TestNeedsRedesignEscalation:
+    """A mechanical request-changes verdict on a structurally-unfixable gate
+    (sealed-path, breaking public API) must get exactly one bounce before
+    the issue is parked instead of re-dispatched."""
+
+    def test_first_occurrence_dispatches_fix_normally(self, config: Config) -> None:
+        from coord.auto_loop import _dispatch_fix_for_review
+
+        work = _work_assignment(assignment_id="work-3721a")
+        review = _review_assignment(
+            assignment_id="review-3721a", review_of="work-3721a",
+        )
+        review.verdict_source = "mechanical"
+        review.verdict_source_reason = (
+            "sealed path(s) violated: tests/acceptance/foo.py"
+        )
+        board = _board_with(work, review)
+        findings = ReviewFindings(
+            verdict="request-changes", body="## Blocking\n- 1. don't touch it\n"
+        )
+
+        mock_http = MagicMock()
+        mock_http.post.return_value.json.return_value = {"id": "fix-3721a-2"}
+        mock_http.post.return_value.raise_for_status = MagicMock()
+
+        with patch("coord.auto_loop.record_dispatched_assignment"):
+            actions = _dispatch_fix_for_review(
+                review, findings, board, config, http_client=mock_http,
+            )
+
+        assert actions[0].kind == "fix_dispatched"
+
+    def test_second_occurrence_escalates_and_skips_dispatch(
+        self, config: Config
+    ) -> None:
+        from coord.auto_loop import _dispatch_fix_for_review
+
+        work = _work_assignment(assignment_id="work-3721b")
+        prior_review = _review_assignment(
+            assignment_id="review-3721b-1", review_of="work-3721b",
+        )
+        prior_review.verdict_source = "mechanical"
+        prior_review.verdict_source_reason = (
+            "sealed path(s) violated: tests/acceptance/bar.py"
+        )
+        review = _review_assignment(
+            assignment_id="review-3721b-2", review_of="work-3721b",
+        )
+        review.verdict_source = "mechanical"
+        review.verdict_source_reason = (
+            "sealed path(s) violated: tests/acceptance/foo.py"
+        )
+        board = Board(
+            repos=[Repo(name="api", github="acme/api")],
+            machines=[],
+            active=[],
+            completed=[work, prior_review, review],
+        )
+        findings = ReviewFindings(
+            verdict="request-changes", body="## Blocking\n- 1. don't touch it\n"
+        )
+
+        with patch("coord.state.record_drive_escalation") as mock_escalate:
+            actions = _dispatch_fix_for_review(review, findings, board, config)
+
+        assert len(actions) == 1
+        assert actions[0].kind == "needs_redesign"
+        assert "sealed-path" in actions[0].detail
+        assert "api#1" in actions[0].detail
+        mock_escalate.assert_called_once()
+        _, kwargs = mock_escalate.call_args
+        assert kwargs["stage"] == "needs-redesign"
+        assert kwargs["assignment_id"] == "work-3721b"
+        # No fix worker dispatched.
+        assert board.active == []
+
+    def test_non_eligible_mechanical_kind_never_escalates(
+        self, config: Config
+    ) -> None:
+        """A repeated coordinator-doc tamper is worker error, not a
+        structural wall — it must keep bouncing through the normal fix
+        loop, not get parked."""
+        from coord.auto_loop import _dispatch_fix_for_review
+
+        work = _work_assignment(assignment_id="work-3721c")
+        prior_review = _review_assignment(
+            assignment_id="review-3721c-1", review_of="work-3721c",
+        )
+        prior_review.verdict_source = "mechanical"
+        prior_review.verdict_source_reason = (
+            "coordinator-owned doc(s) edited: README.md"
+        )
+        review = _review_assignment(
+            assignment_id="review-3721c-2", review_of="work-3721c",
+        )
+        review.verdict_source = "mechanical"
+        review.verdict_source_reason = (
+            "coordinator-owned doc(s) edited: CHANGELOG.md"
+        )
+        board = Board(
+            repos=[Repo(name="api", github="acme/api")],
+            machines=[],
+            active=[],
+            completed=[work, prior_review, review],
+        )
+        findings = ReviewFindings(
+            verdict="request-changes", body="## Blocking\n- 1. don't touch it\n"
+        )
+
+        mock_http = MagicMock()
+        mock_http.post.return_value.json.return_value = {"id": "fix-3721c-2"}
+        mock_http.post.return_value.raise_for_status = MagicMock()
+
+        with patch("coord.auto_loop.record_dispatched_assignment"), patch(
+            "coord.state.record_drive_escalation"
+        ) as mock_escalate:
+            actions = _dispatch_fix_for_review(
+                review, findings, board, config, http_client=mock_http,
+            )
+
+        assert actions[0].kind == "fix_dispatched"
+        mock_escalate.assert_not_called()
+
+
 # ── #3322: the fix-round counter is monotonic across every dispatch path ─────