code-coordinator 0.5.297__tar.gz → 0.5.298__tar.gz

{code_coordinator-0.5.297 → code_coordinator-0.5.298}/PKG-INFO

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.297
+Version: 0.5.298
 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.297 → code_coordinator-0.5.298}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.297",
+  "tag": "0.5.298",
   "distance": 0,
-  "node": "g47fe3ff98db0a0f6549b080e1a59c60423ff2df8",
+  "node": "gaa327b0f6d037fbb6df6db3ef4dd15e123624825",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-29"

{code_coordinator-0.5.297 → code_coordinator-0.5.298}/coord/deploy/coord-agent.service

@@ -74,15 +74,40 @@
 #   systemctl --user restart coord-agent
 #
 # See docs/AGENT_OPERATIONS.md → "Install a new agent (first time)".
-
+#
+# #2938: Restart=always, not on-failure. `POST /update` stops this unit's
+# own process so it can come back on the swapped venv — the agent IS its own
+# recovery channel here, via an explicit `systemctl --user restart` the
+# process fires at itself just before exiting (coord/agent_app.py's
+# `_default_exec_restart`). When that explicit restart lands, this process
+# exits 0 either way (a clean stop) and `Restart=on-failure` — correctly, by
+# its own definition — declines to act on a clean exit. If the explicit
+# restart request is ever lost (a dropped systemd/D-Bus call, a race with
+# the process's own exit, anything), NOTHING brings the unit back: it sits
+# `enabled`/`inactive` forever, port 7433 refused, and the fleet has lost
+# its only remote-control channel to that host. `Restart=always` makes
+# systemd itself the backstop for a clean exit, independent of whether the
+# self-restart call landed — dell64, 2026-08-29, ~23 minutes of that exact
+# outage, recovered only because someone could walk to the machine.
+#
+# StartLimitIntervalSec/StartLimitBurst (#2938) bound it: 5 restarts inside
+# 5 minutes and systemd stops trying, landing the unit in `failed` with
+# `Result: start-limit-hit` — visible in `systemctl --user status` and the
+# journal — rather than crash-looping forever. A binary that is genuinely
+# broken (not just "the explicit restart didn't land") must fail loud, not
+# spin silently; `Restart=always` without a limit would trade one silent
+# failure (never restarts) for another (restarts forever with no signal
+# anything is wrong).
 [Unit]
 Description=Coordinator agent server (port <PORT>)
 After=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
 ExecStart=%h/.coord-venv/bin/coord agent --machine <MACHINE_NAME> --port <PORT>
-Restart=on-failure
+Restart=always
 RestartSec=5
 Environment=PATH=%h/.coord-venv/bin:%h/.cargo/bin:%h/.local/bin:/usr/local/bin:/usr/bin:/bin
 

{code_coordinator-0.5.297 → code_coordinator-0.5.298/coord}/deploy/coord-serve.service

@@ -36,11 +36,23 @@
 #     put --token on ExecStart — it would leak via `ps`).
 #
 # See docs/AGENT_OPERATIONS.md → "Control-center daemon (coord serve)".
-
+#
+# #2938: Restart=always (was on-failure), + a StartLimitIntervalSec/
+# StartLimitBurst backstop — see deploy/coord-agent.service's header for the
+# full incident this closes (a clean stop that Restart=on-failure correctly
+# declines to act on, with no other recovery path, leaving the unit
+# `enabled`/`inactive` forever). coord-serve restarts through the same
+# `_restart_sibling_unit` caller as coord-agent's own self-restart
+# (coord/agent_app.py, #2069), so it is exposed to the identical failure
+# shape if that restart request is ever lost. 5 restarts / 5 minutes before
+# systemd gives up and lands the unit in `failed` (`start-limit-hit`) —
+# visible, not a silent crash-loop.
 [Unit]
 Description=coord serve — portable control-center daemon (#584)
 After=network-online.target
 Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
@@ -78,7 +90,7 @@ Type=simple
 # ahead of ~/.local/bin or ~/.coord-venv/bin.
 Environment=PATH=%h/.cargo/bin:%h/.local/bin:%h/src/code-coordinator/.venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin
 ExecStart=%h/.coord-venv/bin/coord serve --config %h/.coord/coordinator.yml --host 0.0.0.0 --port 7435
-Restart=on-failure
+Restart=always
 RestartSec=3
 # #2095: coord-web (its sibling on the same host, restarted through the same
 # `_restart_sibling_unit` caller) went down for the length of a fleet roll

{code_coordinator-0.5.297 → code_coordinator-0.5.298}/coord/deploy/coord-web.service

@@ -92,11 +92,24 @@
 # (#1830), even though the underlying reason differs (that one protects a
 # spawned tmux server from this unit's own cgroup teardown; this one avoids
 # ever having to signal a nonexistent auxiliary process group at all).
+#
+# #2938: Restart=always (was on-failure), + a StartLimitIntervalSec/
+# StartLimitBurst backstop — see deploy/coord-agent.service's header for the
+# full incident this closes (a clean stop that Restart=on-failure correctly
+# declines to act on, with no other recovery path, leaving the unit
+# `enabled`/`inactive` forever). coord-web restarts through the same
+# `_restart_sibling_unit` caller as coord-agent's own self-restart
+# (coord/agent_app.py, #2069), so it is exposed to the identical failure
+# shape if that restart request is ever lost. 5 restarts / 5 minutes before
+# systemd gives up and lands the unit in `failed` (`start-limit-hit`) —
+# visible, not a silent crash-loop.
 
 [Unit]
 Description=coord web — phone/web control-center dashboard (#700)
 After=network-online.target
 Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
@@ -118,7 +131,7 @@ ExecStart=%h/.coord-venv/bin/coord web --config %h/.coord/coordinator.yml --host
 # setting it here too ensures any other subprocess spawned by coord web also
 # has a sane terminal type without requiring a code fix for each callsite.
 Environment=TERM=xterm-256color
-Restart=on-failure
+Restart=always
 RestartSec=3
 # #2095 — see the header comment above. Bounds the SSE-drain hang that took
 # the dashboard down during the 2026-08-10 fleet roll.

{code_coordinator-0.5.297 → code_coordinator-0.5.298}/deploy/coord-agent.service

@@ -74,15 +74,40 @@
 #   systemctl --user restart coord-agent
 #
 # See docs/AGENT_OPERATIONS.md → "Install a new agent (first time)".
-
+#
+# #2938: Restart=always, not on-failure. `POST /update` stops this unit's
+# own process so it can come back on the swapped venv — the agent IS its own
+# recovery channel here, via an explicit `systemctl --user restart` the
+# process fires at itself just before exiting (coord/agent_app.py's
+# `_default_exec_restart`). When that explicit restart lands, this process
+# exits 0 either way (a clean stop) and `Restart=on-failure` — correctly, by
+# its own definition — declines to act on a clean exit. If the explicit
+# restart request is ever lost (a dropped systemd/D-Bus call, a race with
+# the process's own exit, anything), NOTHING brings the unit back: it sits
+# `enabled`/`inactive` forever, port 7433 refused, and the fleet has lost
+# its only remote-control channel to that host. `Restart=always` makes
+# systemd itself the backstop for a clean exit, independent of whether the
+# self-restart call landed — dell64, 2026-08-29, ~23 minutes of that exact
+# outage, recovered only because someone could walk to the machine.
+#
+# StartLimitIntervalSec/StartLimitBurst (#2938) bound it: 5 restarts inside
+# 5 minutes and systemd stops trying, landing the unit in `failed` with
+# `Result: start-limit-hit` — visible in `systemctl --user status` and the
+# journal — rather than crash-looping forever. A binary that is genuinely
+# broken (not just "the explicit restart didn't land") must fail loud, not
+# spin silently; `Restart=always` without a limit would trade one silent
+# failure (never restarts) for another (restarts forever with no signal
+# anything is wrong).
 [Unit]
 Description=Coordinator agent server (port <PORT>)
 After=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
 ExecStart=%h/.coord-venv/bin/coord agent --machine <MACHINE_NAME> --port <PORT>
-Restart=on-failure
+Restart=always
 RestartSec=5
 Environment=PATH=%h/.coord-venv/bin:%h/.cargo/bin:%h/.local/bin:/usr/local/bin:/usr/bin:/bin
 

{code_coordinator-0.5.297/coord → code_coordinator-0.5.298}/deploy/coord-serve.service

@@ -36,11 +36,23 @@
 #     put --token on ExecStart — it would leak via `ps`).
 #
 # See docs/AGENT_OPERATIONS.md → "Control-center daemon (coord serve)".
-
+#
+# #2938: Restart=always (was on-failure), + a StartLimitIntervalSec/
+# StartLimitBurst backstop — see deploy/coord-agent.service's header for the
+# full incident this closes (a clean stop that Restart=on-failure correctly
+# declines to act on, with no other recovery path, leaving the unit
+# `enabled`/`inactive` forever). coord-serve restarts through the same
+# `_restart_sibling_unit` caller as coord-agent's own self-restart
+# (coord/agent_app.py, #2069), so it is exposed to the identical failure
+# shape if that restart request is ever lost. 5 restarts / 5 minutes before
+# systemd gives up and lands the unit in `failed` (`start-limit-hit`) —
+# visible, not a silent crash-loop.
 [Unit]
 Description=coord serve — portable control-center daemon (#584)
 After=network-online.target
 Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
@@ -78,7 +90,7 @@ Type=simple
 # ahead of ~/.local/bin or ~/.coord-venv/bin.
 Environment=PATH=%h/.cargo/bin:%h/.local/bin:%h/src/code-coordinator/.venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin
 ExecStart=%h/.coord-venv/bin/coord serve --config %h/.coord/coordinator.yml --host 0.0.0.0 --port 7435
-Restart=on-failure
+Restart=always
 RestartSec=3
 # #2095: coord-web (its sibling on the same host, restarted through the same
 # `_restart_sibling_unit` caller) went down for the length of a fleet roll

{code_coordinator-0.5.297 → code_coordinator-0.5.298}/deploy/coord-web.service

@@ -92,11 +92,24 @@
 # (#1830), even though the underlying reason differs (that one protects a
 # spawned tmux server from this unit's own cgroup teardown; this one avoids
 # ever having to signal a nonexistent auxiliary process group at all).
+#
+# #2938: Restart=always (was on-failure), + a StartLimitIntervalSec/
+# StartLimitBurst backstop — see deploy/coord-agent.service's header for the
+# full incident this closes (a clean stop that Restart=on-failure correctly
+# declines to act on, with no other recovery path, leaving the unit
+# `enabled`/`inactive` forever). coord-web restarts through the same
+# `_restart_sibling_unit` caller as coord-agent's own self-restart
+# (coord/agent_app.py, #2069), so it is exposed to the identical failure
+# shape if that restart request is ever lost. 5 restarts / 5 minutes before
+# systemd gives up and lands the unit in `failed` (`start-limit-hit`) —
+# visible, not a silent crash-loop.
 
 [Unit]
 Description=coord web — phone/web control-center dashboard (#700)
 After=network-online.target
 Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
@@ -118,7 +131,7 @@ ExecStart=%h/.coord-venv/bin/coord web --config %h/.coord/coordinator.yml --host
 # setting it here too ensures any other subprocess spawned by coord web also
 # has a sane terminal type without requiring a code fix for each callsite.
 Environment=TERM=xterm-256color
-Restart=on-failure
+Restart=always
 RestartSec=3
 # #2095 — see the header comment above. Bounds the SSE-drain hang that took
 # the dashboard down during the 2026-08-10 fleet roll.

{code_coordinator-0.5.297 → code_coordinator-0.5.298}/docs/CUSTOMER_FACING_APPS.md

@@ -109,10 +109,23 @@ natal-chart (Preview)  ref=issue-39-transit-page-annual-profections-mock-up
     https://ed9f21ad.natal-chart-3ew.pages.dev
 ```
 
-The hash is not derivable from the branch name, and the branch-alias URL
-Cloudflare also publishes truncates at 28 characters, which these branch names
-exceed. Read it from the forge instead — `cloudflare/pages-action` creates a
-GitHub Deployment per PR whose latest status carries the real URL:
+The hash is not derivable from the branch name, and **there is no branch-alias
+URL to fall back on** — measured 2026-08-29 against this project, aliasing is off
+entirely, `main` included:
+
+```
+404  https://issue-56-transit-chart-add-a.natal-chart-3ew.pages.dev
+404  https://main.natal-chart-3ew.pages.dev
+200  https://f432dd47.natal-chart-3ew.pages.dev
+```
+
+Note the domain too: it is `natal-chart-3ew.pages.dev`, while
+`deploy-cloudflare.yml` says `projectName: natal-chart`. Cloudflare's `-3ew`
+suffix is not derivable from anything coord holds, so a repo's preview host has
+to be *read*, never *constructed* — see #2948, which is this exact assumption
+shipped as a config template. Read it from the forge instead —
+`cloudflare/pages-action` creates a GitHub Deployment per PR whose latest status
+carries the real URL:
 
 ```bash
 gh api "repos/{owner}/{repo}/deployments?ref={branch}" --jq '.[0].id'
@@ -122,21 +135,58 @@ gh api "repos/{owner}/{repo}/deployments/{id}/statuses" --jq '.[0].environment_u
 Match on the **environment name** (`"<project> (Preview)"`), not on recency —
 production deploys are hash URLs too and interleave with previews in that list.
 
-### 2. A `uat` gate between Review and Merge · **NOT BUILT — claude-coordinator#2687**
+### 2. A `uat` gate between Review and Merge · **shipped (#2687) · ON for natal-chart since 2026-08-29**
 
-The gap that lets everything else fail. Today `merge.auto_drain: true` with
-`max_per_tick: 1` means the daemon merges the moment Test + Review + CI go
-green, and the push to `main` fires production. **There is no per-repo,
-pre-merge operator hold anywhere in coord**: `coord pause` only stops agent
-routing, and drive-queue's `--hold-after` (#1757) fires *after* the merge, which
-for an auto-deploying repo is after the customer can already see it.
+This was the gap that let everything else fail, and it is closed. Before it,
+`merge.auto_drain: true` with `max_per_tick: 1` meant the daemon merged the
+moment Test + Review + CI went green and the push to `main` fired production,
+with **no per-repo, pre-merge operator hold anywhere in coord** — `coord pause`
+only stops agent routing, and drive-queue's `--hold-after` (#1757) fires *after*
+the merge, which for an auto-deploying repo is after the customer can already
+see it.
 
-#2687 adds a `uat` gate ordered before `merge`, a
-`coord uat <id> --passed|--failed` verdict modelled on `coord test`, and — the
-part that decides whether it gets used or bypassed — **the preview URL surfaced
-in `coord status` and the TUI**, next to the command that clears the gate. A
-gate that makes the operator go hunting for the link will be routed around
-inside a week.
+`coord merge` now refuses a PR whose UAT verdict is missing or failed, printing
+the preview URL and the exact command to clear it:
+
+```
+uat verdict missing — preview: <url> — run: coord uat <assignment-id> --passed
+```
+
+**Enabling it is a two-part opt-in, and one half alone does nothing:**
+
+```yaml
+pipeline:
+  default_gates: [test, review, uat, merge]   # fleet-wide half — inert on its own
+repos:
+  - name: natal-chart
+    uat_preview: "https://github.com/JDonaghy/natal-chart/pull/{pr_number}"
+```
+
+`coord.merge_queue.requires_uat` demands **both**, so listing `uat` fleet-wide is
+safe: a repo without `uat_preview` never blocks, no matter what `default_gates`
+says. Clear the gate with `coord uat <assignment-id> --passed|--failed` (an
+assignment id, not repo/issue) — modelled on `coord test`.
+
+**Two follow-ups are open, and both matter before you enable this for a second
+repo:**
+
+- **#2948 — `uat_preview` cannot build a working Cloudflare URL.** The
+  `{pr_branch_slug}` placeholder assumes branch aliases that this project does
+  not publish (see §1). It renders a plausible dead link and
+  `resolve_uat_preview_url` never raises, so the failure is silent. natal-chart's
+  template therefore points at the **PR page**, whose timeline carries the live
+  `natal-chart (Preview)` deployment — one click from the real build, and it
+  cannot 404.
+- **#2947 — `coord drive` does not classify the gate.** `_merge_gate_kind`
+  knows `smoke`/`review`/`unknown_head` and returns `None` for a uat block, so an
+  unattended drive spends its merge attempts blind and lands the drive-queue
+  entry in terminal `blocked` rather than parking. Until it lands, expect to
+  `remove` + `add` the queue entry after recording the verdict.
+
+The part #2687 called the deciding one — **the preview URL surfaced in `coord
+status` and the TUI**, next to the command that clears the gate — is what #2947
+and #2948 between them still owe. A gate that makes the operator go hunting for
+the link will be routed around inside a week.
 
 ### 3. Sign-off reaches the customer without you relaying it · **partially built**
 
@@ -148,12 +198,27 @@ explicitly out of scope for #2588 and never filed.
 Until it exists, step 3 is you, by hand, in the runbook below. That is fine at
 one customer and does not survive two.
 
-### 4. Visual regression baselines · **NOT BUILT — natal-chart#47**
+### 4. Visual regression baselines · **shipped (natal-chart#47)**
 
 So the human is the *second* line of defence, not the first. Screenshot the
 core screens against a **fixed fixture** — one hardcoded chart, a frozen clock —
 and diff them in CI.
 
+Built as Playwright screenshot specs in `packages/web/e2e/`, with committed
+baselines beside each spec:
+
+```
+packages/web/playwright.config.ts
+packages/web/e2e/chart-wheel.spec.ts  + chart-wheel.spec.ts-snapshots/chart-wheel-chromium-linux.png
+packages/web/e2e/positions.spec.ts    + positions.spec.ts-snapshots/positions-chromium-linux.png
+packages/web/e2e/zr-tab.spec.ts       + zr-tab.spec.ts-snapshots/zr-tab-chromium-linux.png
+```
+
+**A deliberate restyle of a covered screen therefore fails CI until its baseline
+is re-recorded, and that is the harness working.** Say so in the issue when you
+file one — a worker that reads a red baseline diff as a defect will spend fix
+rounds trying to restore the look you asked it to change.
+
 The honest caveat, worth stating because it is the trap: pixel diffing is flaky
 across font rendering and browser versions, and **font fallback is exactly the
 defect this is meant to catch**, so a tolerance loose enough to ignore font
@@ -206,33 +271,41 @@ the preview" is the control that already failed on 2026-08-23. This file
 documents a *mechanism*; where the mechanism does not exist yet it says so, in
 bold, with the issue number.
 
-## The manual runbook — what to do until #2687 lands
-
-For a customer-facing repo, right now, with no gate to help you:
+## The runbook — a repo with the gate on
 
 1. **Queue the work as normal** (`coord drive-queue add`). Nothing special.
-2. **Watch for the PR.** The work leg completing is your cue — the branch is
-   pushed and the PR opens shortly after.
-3. **Get the preview URL** with the two `gh api` calls in step 1 above. The URL
-   does not exist the instant the PR opens; the preview build has to finish.
+2. **Wait for `coord merge` to refuse.** That refusal *is* the notification —
+   it names the gate, the preview link and the command. You are no longer racing
+   `auto_drain`; the merge cannot happen without your verdict.
+3. **Get the real preview URL** with the two `gh api` calls in §1. Until #2948
+   lands the gate's own link points at the PR, so in practice: open the PR and
+   click the `natal-chart (Preview)` deployment in its timeline. The URL does not
+   exist the instant the PR opens; the preview build has to finish.
 4. **Look at it yourself first.** Walk the screens the change touched. You will
    catch most of it here, and it costs a minute.
-5. **Send the customer the URL** and wait for a yes.
-6. **Then let it merge.**
-
-Step 6 is the weak one and you should know why: **you cannot reliably hold a
-merge today.** `auto_drain` will take the PR as soon as its gates are green,
-whether or not you have heard back. The available holds are all bad in
-different ways — draft the PR on GitHub (targeted, but strands the merge-queue
-entry in `NEEDS_ATTENTION`), or flip `merge.auto_drain: false` in
-`~/.coord/coordinator.remote.yml` (a hard guarantee that stalls auto-merge for
-every other repo in flight, and is easy to forget to switch back).
-
-**This is exactly why #2687 exists.** Until it lands, on a change where the
-customer's opinion genuinely gates the release, the honest options are to pick
-one of those two holds consciously, or to accept that the merge may win the
-race — as it did on 2026-08-24, when natal-chart#42 merged and deployed to
-production during the conversation about how to review it before it shipped.
+5. **Send the customer the URL** and wait for a yes. Through the portal, that is
+   `coord portal enqueue-preview <SUB-ID> <url>` then `coord portal
+   enqueue-status <SUB-ID> quality-check`, both on the daemon host, and her
+   answer arrives as a `preview.approved` / `preview.changes_requested` event
+   (`docs/CUSTOMER_PORTAL.md`).
+6. **Record the verdict and let it merge:** `coord uat <assignment-id> --passed`.
+
+**What is still weak, and why.** Nothing auto-fires off `preview.approved` — it
+is not wired into `coord merge` or the merge queue, so step 6 remains a
+deliberate human act. And per #2947 an unattended drive will have burned its
+merge attempts against the block and parked the queue entry in terminal
+`blocked` by the time you get here, so expect a `remove` + `add` after recording
+the verdict.
+
+**For a repo with the gate off, you cannot reliably hold a merge at all.**
+`auto_drain` takes the PR as soon as its gates are green, whether or not you
+have heard back. The available holds are all bad in different ways — draft the
+PR on GitHub (targeted, but strands the merge-queue entry in
+`NEEDS_ATTENTION`), or flip `merge.auto_drain: false` (a hard guarantee that
+stalls auto-merge for every other repo in flight, and is easy to forget to
+switch back). That is what the gate replaces, and it is not hypothetical: on
+2026-08-24 natal-chart#42 merged and deployed to production *during the
+conversation about how to review it before it shipped*.
 
 ## Adopting this for a new repo
 
@@ -242,7 +315,10 @@ production during the conversation about how to review it before it shipped.
    per-deploy hashes.
 3. Add the repo's visual-regression harness *before* the first customer-visible
    feature, not after the first complaint. Fixed fixture, frozen clock.
-4. Turn on the `uat` gate for the repo once #2687 ships.
+4. Turn on the `uat` gate for the repo — the two-part opt-in in §2. Resolve its
+   `uat_preview` against a **real** deployment before you trust it (§1): a
+   template that renders a dead link is worse than no gate, because the operator
+   learns to waive it.
 5. Point the repo's own `CLAUDE.md` at this file, and make sure its deployment
    section is **true** — natal-chart's said "GitHub Pages" for a week after
    production moved to Cloudflare (fixed in #47).

{code_coordinator-0.5.297 → code_coordinator-0.5.298}/install-agent.sh

@@ -169,11 +169,21 @@ cat > "$UNIT_DIR/coord-agent.service" << UNIT
 [Unit]
 Description=Coordinator agent server (port $PORT)
 After=network-online.target
+# #2938: bound Restart=always below so a genuinely broken binary fails loud
+# (systemd 'failed'/start-limit-hit) instead of crash-looping silently
+# forever — see deploy/coord-agent.service's header for the full incident.
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
 ExecStart=$VENV_DIR/bin/coord agent --machine $MACHINE_NAME --port $PORT
-Restart=on-failure
+# #2938: was Restart=on-failure. POST /update stops this process cleanly so
+# it can come back on the swapped venv via an explicit self-restart
+# (coord/agent_app.py); if that explicit restart is ever lost, on-failure
+# never fires for a clean exit and the unit is gone for good, port 7433
+# refused, no remote-control channel left. Restart=always is the backstop.
+Restart=always
 RestartSec=5
 # #1671: include ~/.cargo/bin so a rustup-installed toolchain resolves to
 # both this agent process (the "rust" capability probe, coord/prereqs.py)