fix(cluster): heartbeat-driven registration refresh for host_lan_ip/url/hardware

[hognek]

Fix: taOS jaylfc#1538 — agent-registration drift (stale IP/status).

Problem: When a worker LXC container comes up on a different IP, the host_lan_ip/url/hardware drifts. Skald routes on these fields — stale values cause hangs or 5xx.

Fix — heartbeat-driven refresh/reconciliation: WorkerAgent.heartbeat() now includes host_lan_ip, url, hardware on every pulse. ClusterManager.heartbeat() updates cached WorkerInfo when these fields are present (backward-compat: None leaves stale values untouched).

Tests: 5 new in TestHeartbeatRegistrationRefresh — all 33 cluster+protocol unit tests pass, no regressions.

Also fixes: storage_cap/storage_used/bytes_deduped were accepted by HeartbeatBody but silently dropped by the handler.

---

Note

Medium Risk
Changes cluster routing metadata and deploy/proxy paths that depend on worker.url and host_lan_ip; behavior is backward-compatible but incorrect refresh could misroute traffic.

Overview
Fixes jaylfc#1538 by reconciling worker registration metadata on every heartbeat instead of only at initial register, so cluster routing (e.g. Skald) does not keep using stale host_lan_ip, url, or hardware after DHCP moves or LXC restarts.

Workers now send live host_lan_ip (via _detect_lan_ip), url, and hardware on each pulse, alongside existing backend/capacity fields. Controller extends HeartbeatBody and ClusterManager.heartbeat() to apply those fields when present (None leaves cached values for legacy agents). The heartbeat route also forwards LXC storage counters (storage_cap_bytes, storage_used_bytes, bytes_deduped_total) that were accepted on the body but previously dropped. When backends is updated, available_models is flattened from sidecar-enriched backend catalogs into WorkerInfo.

Tests: TestHeartbeatRegistrationRefresh covers IP/URL/hardware refresh, no-op on None, and unknown workers. .gitignore adds venv/.

^{Reviewed by Cursor Bugbot for commit 3cce536. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Warning

Review limit reached

@hognek, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 10 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ae1921e7-f4cf-432e-a66b-a616b305eab5

📥 Commits

Reviewing files that changed from the base of the PR and between 133e88e and 3cce536.

📒 Files selected for processing (5)

• .gitignore
• tests/test_cluster_worker_protocol.py
• tinyagentos/cluster/manager.py
• tinyagentos/routes/cluster.py
• tinyagentos/worker/agent.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/heartbeat-drift-refresh

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3cce536. Configure here.}

[cursor]

Heartbeat overwrites routable worker URL

High Severity

Each heartbeat now sends a url derived from the first detected backend’s url (typically http://localhost:…). The controller applies that on every pulse, replacing a previously registered LAN or Incus URL. Cluster routing and mesh metadata use worker.url from the controller, so requests can target an address only reachable inside the worker container.

 

^{Reviewed by Cursor Bugbot for commit 3cce536. Configure here.}