[maksymhryzodub-prog]

Jira: CLEAN-140. Two commits: the guard, and a small escaping fix in the Slack renderers the push security review caught (CLEAN-165 code).

What happened

On prod-mazda the Slack threads of incidents #4–#7 hold 3 300 "Failed again / Running again" pairs per agent over four days, two minutes apart. The seconds give it away: every unreachable write sits on one 30-second grid (:29.6 / :59.6) and every running write on another (:23.1 / :53.1) — two API processes, each sweeping against its own in-memory bridle hub. The copy without the agent's socket saw "pod running, hub absent" and after the 60 s grace wrote unreachable; the other copy wrote running back. The runtime never disconnected. k8s/platform/api runs 2 replicas with an HPA 2–5.

The API is single-process by design: the hub, chat routing (sendToAgent answers "Agent is not connected" on the copy without the socket) and MCP sessions all live in memory. This PR does not make several copies work together; it makes a second copy harmless to the status and loud.

What it does

• The API registers itself. ApiInstance row per process (id, hostname, heartbeat every 10 s; live for 30 s; pruned after an hour; removed on shutdown). ApiInstanceService in the setting slice, exported for anyone who must trust the hub.
• The sweep holds back. detectDrift reads liveCount() first. With more than one copy alive it writes no unreachable, keeps no observation window (it would count minutes the agent spent happily on the other copy and fire the moment this copy is alone), and warns once per five minutes: N copies of the API are alive … Run ranch-api as one replica (CLEAN-140). A vanished pod is still a failure — Kubernetes' word, not the hub's. A rolling update's one-minute overlap is covered by the same rule.
• The owner sees it. apiReplicas on the destination view: Settings → Notifications shows a red box with the count and what it means; get_notification_destination carries the number.
• Manifests. k8s/platform/api/deployment.yaml → replicas: 1 with the reason; hpa.yaml removed. The Mazda fork has the same two files; the patch is ready for that repo.
• Docs. docs/operations/agent-events.md: the "Before switching on" check becomes "One copy of the API".
• Also (second commit): renderRoot and every renderReply branch put the raw agent name into the Slack text fallback — the field notifications are built from — while renderOpened/renderClosed escaped it. Now all of them do; a name like <!channel> Bot cannot page from there. Spec added.

Verified

• api: bun run build; jest for setting + agent/agent status + agent/event (252), and the full suite; Prettier + eslint --quiet on changed files. New specs: heartbeat on boot and every 10 s, the 30 s live window, hourly prune, failed heartbeat does not stop the timer, removal on shutdown; the sweep with 2 copies alive (no unreachable across three sweeps, one warning, the window restarts from scratch once alone, a vanished pod still fails); the view's apiReplicas.
• admin: npx nuxt typecheck, bun test slices (195), bun run locale:check. SDK regenerated (apiReplicas only).
• Live, two API processes on one local Postgres: both registered a row, both reported apiReplicas: 2 on GET /agent-events/destination, both logged the warning exactly once over 90 s of sweeps, heartbeats refreshed every 10 s. One process killed hard (taskkill /F, a crashed pod): its row froze, and 40 s later the survivor reported apiReplicas: 1. The startup sweep still marked pod-less agents failed. Not seen live: the unreachable write itself needs a Running+Ready pod, which the local run has none of — that branch is the unit-tested one.

Twin consoles

admin changed (the Notifications form's one box). app has no agent/event sub-slice: nothing to mirror.

For DevOps

The code alone ends the incident spam: with this merged, a second replica no longer produces unreachable, incidents or Slack messages. Going to one replica (replicas: 1, no HPA, as the manifests now say) is the recommendation, because with two copies the pre-existing problems stay: a chat may land on the copy without the agent’s socket and answer "Agent is not connected", MCP sessions are per process, and unreachable detection is off while the red box shows. That trade-off is the cluster owner’s call; the console will say which state it is in.

🤖 Generated with Claude Code