feat(engine): accept node roster snapshot in node.heartbeat

[khaliqgant]

What

Extends the node.heartbeat fleet-wire schema so the broker can carry the node roster snapshot (name, node_id, capabilities, max_agents, version) on the steady-state heartbeat, and has the engine adopt it.

Previously FleetNodeHeartbeatMessageSchema was .strict() and accepted only load/active_agents/handlers_live. The relay broker (relay#1139, branch ricky/factory-p11-broker-heartbeat) wants the heartbeat to carry the roster for liveness so the engine keeps a node's descriptor fresh between — or in the absence of — a fresh node.register (e.g. after an engine restart where the broker keeps heartbeating an already-registered node). With the strict schema, every roster-carrying heartbeat was rejected, so node load/active_agents never updated and the Fleet E2E spawn/load scenarios timed out.

Changes

• packages/types/src/fleet-wire.ts: add optional name/node_id/capabilities/max_agents/version to FleetNodeHeartbeatMessageSchema (still .strict(), still backward-compatible with a minimal heartbeat).
• packages/engine/src/engine/node.ts (heartbeatNode): when roster fields are present, refresh name/capabilities/maxAgents/version on the node row and register newly-advertised capability actions via ensureCapabilityActions. Validate node_id against the authenticated token (node_id_mismatch) like node.register.
• packages/types/fixtures/fleet-wire/node.heartbeat.json: fixture now carries the roster (round-tripped by the wire-contract test).
• New conformance test asserting roster adoption, server-stamped receipt time, node_id mismatch rejection, and minimal-heartbeat preservation.

Single source of truth: last_heartbeat_at

last_heartbeat_at is intentionally not part of the wire. Receipt time is stamped server-side in heartbeatNode as the single source of truth for liveness; the broker does not send it.

Verification (local)

• npm run build --workspace @relaycast/types / @relaycast/engine: clean.
• engine suite: 133/133 pass (incl. new roster heartbeat test + existing fleetRolloutFlag).
• types suite: 68/68 pass.
• engine tsc --noEmit: clean; lint: clean (one pre-existing unrelated warning in delivery.ts).

Dependency note

relay #1139's Fleet E2E is being repointed at this branch's commit so CI runs the broker's roster-in-heartbeat feature against an engine that accepts it. Do not merge until that cross-repo verification is reviewed.

🤖 Generated with Claude Code

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9c1dea32-d0ad-432c-9a03-31601736b1d7

📥 Commits

Reviewing files that changed from the base of the PR and between b248bfa and 2f685fa.

📒 Files selected for processing (4)

• packages/engine/src/__tests__/conformance/node.test.ts
• packages/engine/src/engine/node.ts
• packages/types/fixtures/fleet-wire/node.heartbeat.json
• packages/types/src/fleet-wire.ts

---

📝 Walkthrough

Walkthrough

FleetNodeHeartbeatMessageSchema gains optional roster-snapshot fields (name, node_id, capabilities, max_agents, version). heartbeatNode validates node_id when present, conditionally persists descriptor fields, always stamps liveness/capacity fields server-side, and calls ensureCapabilityActions when capabilities are included. Conformance tests cover DB persistence, capability dispatch, mismatch rejection, and minimal-heartbeat preservation.

Changes

Roster snapshot on node.heartbeat

Layer / File(s)	Summary
Heartbeat schema and fixture expansion packages/types/src/fleet-wire.ts, packages/types/fixtures/fleet-wire/node.heartbeat.json	FleetNodeHeartbeatMessageSchema adds optional name, node_id, capabilities, max_agents, and version with liveness documentation comments. The fixture is expanded to include structured capability entries matching the new schema.
heartbeatNode roster update and capability re-sync packages/engine/src/engine/node.ts	Validates optional node_id against the authenticated node (rejects mismatches), builds a rosterUpdate partial for descriptor fields applied conditionally, always stamps liveness/capacity fields and server-side lastHeartbeatAt, and calls ensureCapabilityActions when capabilities are present in the heartbeat.
Conformance tests packages/engine/src/__tests__/conformance/node.test.ts	Adds a test that sends a roster-carrying heartbeat and asserts persisted descriptor fields, server-stamped timestamp, and capability endpoint reflection. Covers node_id mismatch rejection and confirms a subsequent minimal heartbeat preserves the previously stored roster.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 Hop, hop — my heartbeat now carries the whole crew,
capabilities, version, and max_agents too!
The broker refreshes its roster with each little beat,
no re-register needed — the liveness stays neat.
Server stamps the time so no clock tricks get through,
and mismatched node_ids? Rejected on cue! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: accepting node roster snapshot data in the heartbeat message.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, detailing what, why, and how the heartbeat schema is extended.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/heartbeat-roster-snapshot

---

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 and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2f685fa99a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Reconcile stale actions when heartbeat drops capabilities

When a roster heartbeat sends a capabilities list that no longer includes an action this node previously advertised, this block only creates/reactivates actions for the new list and never clears the old node-handled action rows. Since invokeAction dispatches by the stored handlerNodeId without rechecking the node's current capabilities, /v1/actions/<removed>/invoke can keep sending unsupported work to this node after its heartbeat roster says it no longer supports that capability. Please deactivate or reassign stale node actions when adopting the heartbeat roster.

Useful? React with 👍 / 👎.