code-coordinator 0.5.237__tar.gz → 0.5.239__tar.gz

{code_coordinator-0.5.237 → code_coordinator-0.5.239}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.237
+Version: 0.5.239
 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.237 → code_coordinator-0.5.239}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.237
+Version: 0.5.239
 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.237 → code_coordinator-0.5.239}/code_coordinator.egg-info/SOURCES.txt

@@ -496,6 +496,7 @@ tests/test_dist_name.py
 tests/test_done_housekeeping.py
 tests/test_drive.py
 tests/test_drive_queue.py
+tests/test_drive_queue_roll_pending.py
 tests/test_drive_state.py
 tests/test_drive_tmux.py
 tests/test_epic_up_capability_detection.py

{code_coordinator-0.5.237 → code_coordinator-0.5.239}/code_coordinator.egg-info/scm_file_list.json

@@ -568,6 +568,7 @@
     "tests/test_done_housekeeping.py",
     "tests/test_drive.py",
     "tests/test_drive_queue.py",
+    "tests/test_drive_queue_roll_pending.py",
     "tests/test_drive_state.py",
     "tests/test_drive_tmux.py",
     "tests/test_epic_up_capability_detection.py",

{code_coordinator-0.5.237 → code_coordinator-0.5.239}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.237",
+  "tag": "0.5.239",
   "distance": 0,
-  "node": "g855b16cb40a1e4b711059e218b94cd1b8c19f38b",
+  "node": "g6bf7406e8a26af4949bd4dac5a486ef69a92af43",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-23"

{code_coordinator-0.5.237 → code_coordinator-0.5.239}/coord/commands/drive_queue.py

@@ -1111,6 +1111,79 @@ def drive_queue_status(output_json: bool, config_path: Path) -> None:
         click.echo("alert: (none)")
 
 
+@drive_queue_group.command("cancel-roll")
+@click.option("--json", "output_json", is_flag=True, default=False,
+              help="Emit the cancelled marker (and any cordons cleared with it) as JSON.")
+def drive_queue_cancel_roll(output_json: bool) -> None:
+    """Cancel a #2587 roll-pending marker so the queue resumes launching now.
+
+    #2607: every OTHER queue-blocking state has an operator override — a
+    held deploy gate has `coord drive-queue resume`, a release cordon has
+    `coord release cordon --clear` — but the roll-pending marker had none.
+    It is supposed to be self-bounding (a TTL / deferral ceiling —
+    `RollPending.expired`), but a marker that keeps getting RE-ARMED before
+    it ever expires never reaches that bound on its own (the defect #2607
+    fixed at the write sites); this command is the escape hatch for while
+    that marker is still live, and for any future case a re-arm loop is not
+    yet ruled out for. Also clears any release cordon still open for the
+    SAME target — the cordon a stalled `coord release propagate`/
+    `nightly-window` run can leave behind — so cancelling actually frees the
+    queue rather than trading one hold for another.
+
+    Does NOT change the target: the next `coord release propagate`/
+    `nightly-window` run re-arms a marker from scratch if the fleet is still
+    behind. This only stops the CURRENT wait.
+    """
+    from coord.machine_pause import clear_cordon, cordons as read_cordons  # noqa: PLC0415
+
+    pending = read_roll_pending()
+    cleared_cordons: list[str] = []
+    if pending is not None:
+        try:
+            active_cordons = read_cordons()
+        except Exception:  # noqa: BLE001 — best-effort; the marker clear below is load-bearing
+            active_cordons = {}
+        for name, cordon in active_cordons.items():
+            if getattr(cordon, "target_version", None) != pending.target_version:
+                continue
+            try:
+                if clear_cordon(name):
+                    cleared_cordons.append(name)
+            except Exception:  # noqa: BLE001 — best-effort; never block the marker clear on this
+                pass
+        clear_roll_pending()
+
+    if output_json:
+        click.echo(
+            _json.dumps(
+                {
+                    "cancelled": pending.to_dict() if pending is not None else None,
+                    "cleared_cordons": sorted(cleared_cordons),
+                },
+                sort_keys=True,
+            )
+        )
+        return
+
+    if pending is None:
+        click.echo("no roll-pending marker to cancel — the queue is not held for a roll")
+        return
+    click.echo(
+        f"cancelled {pending.describe()} — the drive-queue tick resumes "
+        "launching immediately"
+    )
+    if cleared_cordons:
+        click.echo(
+            "also cleared cordon(s) still open for this target: "
+            + ", ".join(sorted(cleared_cordons))
+        )
+    click.echo(
+        "note: this only stops the current wait — the next `coord release "
+        "propagate`/`nightly-window` run re-arms a fresh marker if the "
+        "fleet is still behind"
+    )
+
+
 # ── block-log (#2235 Phase 0) ────────────────────────────────────────────────
 
 

{code_coordinator-0.5.237 → code_coordinator-0.5.239}/coord/commands/release.py

@@ -431,6 +431,24 @@ def _paused_machine_busy(config) -> list:
     return busy
 
 
+def _confirmation_running_busy() -> list:
+    """A #2464 out-of-band test confirmation in flight, as a `Busy` signal
+    (#2596).
+
+    Thin wiring around :func:`coord.release_propagate.confirmation_lock_busy`
+    — see that function's docstring for the incident and why a LOCAL,
+    non-networked lock probe is the right (and sufficient) check here. Feeds
+    the same `extra_busy` seam `_interactive_session_busy`/
+    `_paused_machine_busy` do, at both call sites that build one (the top of
+    `propagate` and `_drain`'s default `extra_busy_fetch`), so a confirmation
+    in flight defers a restart exactly like a live headless assignment does.
+    """
+    from coord import release_propagate as rp  # noqa: PLC0415
+    from coord.filelock import notify_lock_path  # noqa: PLC0415
+
+    return rp.confirmation_lock_busy(notify_lock_path())
+
+
 def _daemon_machine_name(
     config, override: str | None, machine_health: dict | None = None
 ) -> str | None:
@@ -595,14 +613,22 @@ def _ensure_roll_pending_marker(target_version: str, *, reason: str) -> None:
     :class:`coord.drive_queue.RollPending`'s docstring for the mechanism
     this feeds.
 
-    Never overwrites an existing marker for the SAME target — resetting
-    ``set_at``/``deferrals`` every few minutes while this timer keeps
-    finding the fleet busy would make the TTL bound
-    (:meth:`~coord.drive_queue.RollPending.expired`) unreachable in
-    practice, exactly the "never actually bounded" failure #2587's own
-    bound exists to prevent. A marker for a DIFFERENT (stale) target IS
-    replaced — the newly resolved version is the one that should roll.
+    Never overwrites an existing marker's ``set_at``/``deferrals`` — for the
+    SAME target this is a plain no-op (unchanged from before #2607); for a
+    DIFFERENT target the target/reason are updated in place but the clock
+    and deferral count carry over unchanged. #2607: PyPI's "latest" climbs on
+    every merge (`Auto-release on merge to main`), so a busy fleet's target
+    had almost always moved by the time this timer re-fired — treating that
+    as a "new" roll and resetting ``set_at``/``deferrals`` made the TTL/
+    deferral bound (:meth:`~coord.drive_queue.RollPending.expired`)
+    unreachable in practice, exactly the "never actually bounded" failure
+    #2587's own bound exists to prevent, and exactly how #2607's queue froze
+    for good. A re-arm — same target or not — is a continuation of the SAME
+    stuck roll, not a new operator request; only a marker set from scratch
+    (no existing one at all, e.g. right after `coord drive-queue
+    cancel-roll`) starts a new clock.
     """
+    import dataclasses as _dataclasses  # noqa: PLC0415
     import time as _time  # noqa: PLC0415
 
     from coord.commands.drive_queue import read_roll_pending, write_roll_pending  # noqa: PLC0415
@@ -611,6 +637,11 @@ def _ensure_roll_pending_marker(target_version: str, *, reason: str) -> None:
     existing = read_roll_pending()
     if existing is not None and existing.target_version == target_version:
         return
+    if existing is not None:
+        write_roll_pending(
+            _dataclasses.replace(existing, target_version=target_version, reason=reason)
+        )
+        return
     write_roll_pending(
         RollPending(target_version=target_version, set_at=_time.time(), reason=reason)
     )
@@ -808,6 +839,13 @@ def release_propagate(  # noqa: PLR0912, PLR0915 — a pipeline; the decisions a
     # seam from the daemon-aware pause store, so an operator-paused machine
     # defers exactly like a live assignment does instead of reading idle.
     extra_busy.extend(_paused_machine_busy(config))
+    # #2596: nor can it see a #2464 confirmation running in the notify
+    # drain — a restart landing mid-confirmation is exactly what let a
+    # SIGTERM get read as a test failure on 2026-08-22 (the confirmation
+    # itself now refuses that read, #2527, but the restart still shouldn't
+    # have happened at all). Feed the same seam so it defers like a live
+    # assignment instead of getting reaped.
+    extra_busy.extend(_confirmation_running_busy())
     quiescence = rp.assess_quiescence(
         queue_entries=board.get("drive_queue") or [],
         assignments=board.get("assignments") or [],
@@ -2510,8 +2548,15 @@ def _drain(
             # #2174: paused/quiet-hours state, same as the top-level
             # `propagate` call site — a paused daemon host must keep the
             # drain from ever reading "clear" just because tmux is quiet.
+            # #2596: same for a confirmation running under `notify.lock` —
+            # gated on `config is not None` too, even though the check
+            # itself needs no config, purely to keep this function's
+            # documented "no *config* means no real filesystem I/O"
+            # contract intact for the `config=None` unit-test path above.
             extra_busy_fetch = lambda: (  # noqa: E731
-                _interactive_session_busy(config) + _paused_machine_busy(config)
+                _interactive_session_busy(config)
+                + _paused_machine_busy(config)
+                + _confirmation_running_busy()
             )
         else:
             extra_busy_fetch = lambda: []  # noqa: E731
@@ -2799,6 +2844,7 @@ def release_nightly_window(
     genuinely idle is a fine moment to roll immediately. A still-busy fleet
     just leaves the marker exactly as it was for the tick to keep watching.
     """
+    import dataclasses as _dataclasses  # noqa: PLC0415
     import json as _json  # noqa: PLC0415
     import time  # noqa: PLC0415
 
@@ -3002,18 +3048,35 @@ def release_nightly_window(
             _finish(rw.STATUS_PROPAGATE_FAILED, prop_exit or 1)
 
     # ── 3. set (or refresh) the marker and return immediately (#2587) ─────
+    # #2607: a marker already pending for a DIFFERENT target is updated in
+    # place — target_version/reason move, but set_at/deferrals carry over
+    # unchanged. This is the exact site the incident traced back to: PyPI's
+    # "latest" climbs on every merge, so by the time this nightly timer
+    # re-fired the target had almost always moved, and writing a brand new
+    # `RollPending` here reset the TTL/deferral escape hatch on every single
+    # re-arm — the queue froze because the bound that was supposed to save it
+    # could never be reached. Only a genuinely fresh marker (no existing one
+    # at all) gets a new clock.
     if existing is not None:
         click.echo(
             f"replacing stale roll-pending marker ({existing.describe()}) "
-            f"with v{record.target_version}"
+            f"with v{record.target_version} — preserving its original "
+            f"set_at/deferrals (#2607: a re-arm is a continuation of the "
+            f"same stuck roll, not a new request)"
         )
-    write_roll_pending(
-        RollPending(
-            target_version=record.target_version,
-            set_at=time.time(),
-            reason="nightly-window",
+        write_roll_pending(
+            _dataclasses.replace(
+                existing, target_version=record.target_version, reason="nightly-window",
+            )
+        )
+    else:
+        write_roll_pending(
+            RollPending(
+                target_version=record.target_version,
+                set_at=time.time(),
+                reason="nightly-window",
+            )
         )
-    )
     click.echo(
         f"roll pending: v{record.target_version} — the drive-queue tick will "
         f"fire `coord release propagate` at the next inter-drive gap "

{code_coordinator-0.5.237 → code_coordinator-0.5.239}/coord/commands/status.py

@@ -629,6 +629,31 @@ def status(config_path: Path, machine_filter: str | None, no_reconcile: bool, ti
                 if live_error:
                     click.echo(f"      error: {live_error}")
 
+    # #2607: the #2587 roll-pending marker — while it is live the drive-queue
+    # tick refuses to launch anything, and #2607 found a re-arm path that
+    # could reset its own TTL/deferral escape hatch on every attempt, freezing
+    # the queue with no operator-visible sign anywhere OTHER than `coord
+    # drive-queue status`. Surfaced here too so an operator staring at plain
+    # `coord status` — the first thing anyone reaches for — sees it without
+    # having to know the marker exists. Host-local (same file the daemon
+    # host's own `coord-drive-queue.timer` reads), so skipped on a thin
+    # client exactly like the merge queue above.
+    if not svc:
+        import time as _time
+
+        from coord.commands.drive_queue import read_roll_pending
+
+        roll_pending = read_roll_pending()
+        if roll_pending is not None:
+            age = _time.time() - roll_pending.set_at
+            click.echo("")
+            click.echo(
+                f"⏸ {roll_pending.describe()} — set {age:.0f}s ago, "
+                f"{roll_pending.deferrals}/{roll_pending.max_deferrals} "
+                "deferrals — drive queue launches nothing until it fires or "
+                "expires. Cancel with `coord drive-queue cancel-roll`."
+            )
+
     # #920: sibling-overlap warnings — approved (PENDING) queue entries that
     # touch overlapping files and have been aging.  Mirrors the merge-queue
     # skip above: the queue is host-local, so this is a no-op on a thin
@@ -1364,6 +1389,28 @@ def doctor(
             if is_problem:
                 any_problem = True
 
+    # #2607: name the #2587 roll-pending marker here too, not just in `coord
+    # drive-queue status` — an operator running `coord doctor` to ask "why
+    # isn't the fleet doing anything" must see this without already knowing
+    # the marker exists. Host-local (the file the daemon host's own
+    # `coord-drive-queue.timer` reads), so this only has something to say
+    # when run ON that host — same caveat as the release-verify section
+    # above resolving PyPI locally.
+    from coord.commands.drive_queue import read_roll_pending  # noqa: PLC0415
+
+    roll_pending = read_roll_pending()
+    if roll_pending is not None:
+        import time as _time  # noqa: PLC0415
+
+        age = _time.time() - roll_pending.set_at
+        click.echo("")
+        click.echo(
+            f"⏸ {roll_pending.describe()} — set {age:.0f}s ago, "
+            f"{roll_pending.deferrals}/{roll_pending.max_deferrals} deferrals "
+            "— the drive queue on this host launches nothing until it fires "
+            "or expires. Escape hatch: `coord drive-queue cancel-roll`."
+        )
+
     # #1862: a quiet-hours window that removes the only machine with a
     # capability makes matching work silently unroutable (`dispatch_smoke`
     # already has this failure shape — #1678: it refuses to route and the

{code_coordinator-0.5.237 → code_coordinator-0.5.239}/coord/confirm_test.py

@@ -87,7 +87,14 @@ saying so:
   #2527) — a negative ``returncode`` from `subprocess.run` (e.g. ``-15`` for
   SIGTERM), most often a `coord-agent`/`coord-serve` restart landing mid-run.
   The command never ran to completion, exactly like a timeout, so it gets the
-  identical inconclusive treatment rather than being read as "ran and failed".
+  identical inconclusive treatment rather than being read as "ran and failed";
+* exit 126 (:data:`PERMISSION_DENIED_EXIT`, #2596) — POSIX's "found but not
+  executable", the same "toolchain problem, not a branch problem" shape as
+  exit 127's "not found";
+* a nonzero exit with literally no captured output (:data:`KIND_NO_OUTPUT`,
+  #2596) — a crash with no message, an OOM-kill, a runner that swallowed its
+  own output. A refutation is only as good as the evidence behind it, and
+  there is nothing here to put in a fix briefing.
 
 That asymmetry is the safety property: the worst case of a broken confirmation
 environment is that the Test stage behaves exactly as it did before this module
@@ -197,6 +204,28 @@ _TRUTHY = frozenset({"1", "true", "yes", "on"})
 #: existing ``TimeoutExpired`` carve-out and get misread as "ran and failed".
 KIND_SIGNAL = "signal"
 
+#: #2596: POSIX's "found but not executable" — a permission bit dropped on a
+#: build script, an environment inconsistency, the identical "toolchain
+#: problem, not a branch problem" shape :data:`~coord.revalidate.
+#: SHELL_NOT_FOUND_EXIT` (127, "not found") already covers. Handled locally
+#: here rather than folded into :func:`~coord.revalidate.
+#: is_infrastructure_failure`: that helper is shared with ``coord merge
+#: --revalidate``, which #2596 does not touch, and this module already keeps
+#: its own signal-kill classification local for the same reason.
+PERMISSION_DENIED_EXIT = 126
+
+#: #2596: a build/test command that ran to completion, returned nonzero, and
+#: captured NOTHING — no stdout, no stderr. A genuine failure almost always
+#: leaves a trace (an assertion, a traceback, a compiler error); zero bytes
+#: of output before dying nonzero is more often a crash with no message, an
+#: OOM-kill, or a runner that silently swallowed its own output than a real,
+#: diagnosable test failure. There is nothing here to extract into a fix
+#: briefing (see ``coord/drive.py``'s matching #2596 guard against
+#: dispatching a fix worker with no extracted failure), so this stays
+#: inconclusive rather than refuting a claim we cannot back up with a
+#: single line of evidence.
+KIND_NO_OUTPUT = "no_output"
+
 #: The only kinds that may overturn a PASS claim: a build or test command that
 #: ran to completion and returned nonzero. Nothing weaker. See the module
 #: docstring's fail-direction section — this frozenset IS that safety property.
@@ -204,7 +233,9 @@ REFUTING_KINDS = frozenset({KIND_BUILD, KIND_SUITE})
 
 #: Kinds meaning "the check could not reach a verdict". The caller falls back to
 #: the worker's own claim on any of these, which is pre-#2464 behaviour.
-INCONCLUSIVE_KINDS = frozenset({KIND_SETUP, KIND_INFRA, KIND_TIMEOUT, KIND_SIGNAL})
+INCONCLUSIVE_KINDS = frozenset({
+    KIND_SETUP, KIND_INFRA, KIND_TIMEOUT, KIND_SIGNAL, KIND_NO_OUTPUT,
+})
 
 
 # ── Per-pass budget (#2464-review) ──────────────────────────────────────────
@@ -584,7 +615,9 @@ def _classify_failure(
             returncode=returncode,
             worktree=worktree,
         )
-    infra = is_infrastructure_failure(returncode, output)
+    infra = returncode == PERMISSION_DENIED_EXIT or is_infrastructure_failure(
+        returncode, output,
+    )
     baseline = not infra and is_baseline_red_failure(returncode, output)
     if infra:
         return ConfirmationResult(
@@ -614,6 +647,25 @@ def _classify_failure(
             returncode=returncode,
             worktree=worktree,
         )
+    if not (output or "").strip():
+        # #2596: ran to completion, returned nonzero, and captured literally
+        # nothing — no stdout, no stderr. Same fail-direction reasoning as
+        # every other arm above: a refutation is only as good as the
+        # evidence behind it, and there is not one line of it here (a crash
+        # with no message, an OOM-kill, a runner that swallowed its own
+        # output). Never REFUTING_KINDS on evidence this thin.
+        return ConfirmationResult(
+            kind=KIND_NO_OUTPUT,
+            reason=(
+                f"the independently-run {stage} command exited nonzero (exit "
+                f"{returncode}) but produced NO captured output — there is "
+                "nothing here to diagnose as a branch failure, so this is "
+                "not treated as a refutation (#2596)"
+            ),
+            command=command,
+            returncode=returncode,
+            worktree=worktree,
+        )
     return ConfirmationResult(
         kind=KIND_BUILD if stage == "build" else KIND_SUITE,
         reason=(
@@ -885,8 +937,10 @@ __all__ = [
     "CONFIRM_PASS_BUDGET_SECONDS",
     "DISABLE_ENV_VAR",
     "INCONCLUSIVE_KINDS",
+    "KIND_NO_OUTPUT",
     "KIND_SIGNAL",
     "NOTIFY_BASE_CLIENT_TIMEOUT_SECONDS",
+    "PERMISSION_DENIED_EXIT",
     "REFUTING_KINDS",
     "ConfirmationResult",
     "begin_confirmation_pass",

{code_coordinator-0.5.237 → code_coordinator-0.5.239}/coord/db.py

@@ -69,10 +69,22 @@ def _open(path: Path) -> sqlite3.Connection:
     conn.execute("PRAGMA busy_timeout=5000")
     conn.execute("PRAGMA foreign_keys=ON")
     conn.row_factory = sqlite3.Row
-    _ensure_schema(conn)
-    _maybe_migrate_json(conn)
-    _migrate_gate_order(conn)
-    _backfill_orphaned_review_verdicts(conn)
+    # #2598: _ensure_schema/_maybe_migrate_json/_migrate_gate_order/
+    # _backfill_orphaned_review_verdicts are convergent one-time operations,
+    # not per-open invariants — but every one of them ran unconditionally on
+    # every process's DB open, so a read-only command (`coord status`) began
+    # a write transaction (and, for the unconstrained schema_version table,
+    # left a junk row behind — 45,708 of them observed in the field) purely
+    # to open a connection it only ever intended to read from. Gate the
+    # whole block on a cheap read-only version check: a database already at
+    # _DB_SCHEMA_VERSION does none of this work, so opening it issues no
+    # write at all. See _read_schema_version's docstring for why this read
+    # is correct against both the pre-#2598 and post-#2598 table shapes.
+    if _read_schema_version(conn) < _DB_SCHEMA_VERSION:
+        _ensure_schema(conn)
+        _maybe_migrate_json(conn)
+        _migrate_gate_order(conn)
+        _backfill_orphaned_review_verdicts(conn)
     return conn
 
 
@@ -143,13 +155,94 @@ def retry_on_locked(
 
 # ── Schema ────────────────────────────────────────────────────────────────────
 
+# #2598: bumped from the original unversioned "1" written by every process
+# forever. Read by _read_schema_version()/_open() as the target a database
+# must reach before _open() can skip its write path entirely. Whoever adds
+# the NEXT one-shot migration (another _migrate_* or _backfill_* function
+# meant to run once per database, not once per process) must bump this too
+# — otherwise an already-caught-up database (version == _DB_SCHEMA_VERSION)
+# will never run it, because the whole write path is gated on this compare.
+_DB_SCHEMA_VERSION = 2
+
+
+def _read_schema_version(conn: sqlite3.Connection) -> int:
+    """Cheap, read-only probe of how caught-up *conn*'s database is (#2598).
+
+    A plain ``SELECT`` — never begins a write transaction, so calling this
+    to decide whether _open() needs to do any write work cannot itself take
+    the write lock.
+
+    Returns 0 when ``schema_version`` doesn't exist yet (brand-new database)
+    or is empty. Otherwise returns the highest stored value, which reads
+    correctly against *either* table shape: the pre-#2598 unconstrained
+    table (every row holds the same value, so MAX is that value — junk rows
+    don't change the answer) or the post-#2598 constrained table (exactly
+    one row). A pre-#2598 database therefore reads as version 1, which is
+    ``< _DB_SCHEMA_VERSION`` (2) — so it takes the write path exactly once
+    more, which is what collapses its schema_version duplicates and applies
+    the PRIMARY KEY (see _fix_schema_version_table). Every open after that
+    reads 2 and skips the write path entirely.
+    """
+    try:
+        row = conn.execute("SELECT MAX(version) FROM schema_version").fetchone()
+    except sqlite3.OperationalError:
+        return 0  # table doesn't exist yet
+    if row is None or row[0] is None:
+        return 0
+    return int(row[0])
+
+
+def _fix_schema_version_table(conn: sqlite3.Connection) -> None:
+    """Collapse the pre-#2598 unconstrained ``schema_version`` table.
+
+    The original table declared no ``PRIMARY KEY``/``UNIQUE`` constraint, so
+    ``INSERT OR IGNORE INTO schema_version VALUES (1)`` — meant to be a
+    once-per-database no-op — actually succeeded on every single process
+    open, leaving one junk row per open (45,708 observed in the field).
+    This rebuilds the table with a real ``PRIMARY KEY`` on ``version`` so
+    that no longer happens, collapsing any existing duplicate rows down to
+    their distinct values in the process.
+
+    Safe to call against any existing shape: the old broken table (any
+    number of duplicate rows, no constraint), the new constrained table
+    (already migrated — a no-op), or no table at all (fresh database).
+    """
+    row = conn.execute(
+        "SELECT sql FROM sqlite_master WHERE type='table' AND name='schema_version'"
+    ).fetchone()
+    if row is not None and "PRIMARY KEY" in (row[0] or ""):
+        return  # already the constrained post-#2598 shape
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL);
+        CREATE TABLE schema_version_new (version INTEGER PRIMARY KEY);
+        INSERT OR IGNORE INTO schema_version_new
+            SELECT DISTINCT version FROM schema_version;
+        DROP TABLE schema_version;
+        ALTER TABLE schema_version_new RENAME TO schema_version;
+        """
+    )
+    conn.commit()
+
+
+def _set_schema_version(conn: sqlite3.Connection, version: int) -> None:
+    """Overwrite ``schema_version`` with a single row holding *version*.
+
+    ``schema_version`` holds exactly one fact — how caught-up this database
+    is — so a version bump DELETEs the old row rather than accumulating one
+    row per version ever seen (which ``INSERT OR IGNORE``/``INSERT OR
+    REPLACE`` would do here, since they only dedupe on a *matching* primary
+    key, and a version bump's whole point is that the key changes).
+    """
+    conn.execute("DELETE FROM schema_version")
+    conn.execute("INSERT INTO schema_version (version) VALUES (?)", (version,))
+    conn.commit()
+
+
 def _ensure_schema(conn: sqlite3.Connection) -> None:
     """Create all tables and indexes if they don't already exist."""
+    _fix_schema_version_table(conn)
     conn.executescript("""
-        CREATE TABLE IF NOT EXISTS schema_version (
-            version INTEGER NOT NULL
-        );
-
         CREATE TABLE IF NOT EXISTS assignments (
             assignment_id TEXT PRIMARY KEY,
             machine_name TEXT NOT NULL,
@@ -686,13 +779,12 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
             ON portal_outbox(state, submission_id, seq);
         CREATE INDEX IF NOT EXISTS idx_portal_events_submission
             ON portal_events(submission_id);
-
-        INSERT OR IGNORE INTO schema_version VALUES (1);
     """)
     conn.commit()
     # Column-level migrations for existing databases.  SQLite does not support
     # "ADD COLUMN IF NOT EXISTS", so we catch OperationalError instead.
     _migrate_add_columns(conn)
+    _set_schema_version(conn, _DB_SCHEMA_VERSION)
 
 
 def _migrate_add_columns(conn: sqlite3.Connection) -> None: