Persist unreported fleet node load honestly

[kjgbot]

What changed

• accept absent or null node.heartbeat.load and constrain measured values to [0,1]
• persist an explicit load_reported bit for nodes and providers via migration 0034
• return load: null when a node-wide load is not fully measured
• preserve max_agents: 0 as unlimited across provider aggregates
• rank unknown-load nodes by active agent count rather than treating them as measured idle
• update TypeScript, Python, Rust, and Swift SDK contracts and heartbeat producers

Why

Unbounded providers use max_agents: 0. Existing heartbeats and persistence converted the undefined utilization ratio into load: 0, so a node with 25 active agents appeared identical to one with 4 and consumers rendered both as confidently idle.

load now has one definition: managed-agent capacity utilization (active_agents / max_agents), bounded to [0,1]. CPU, memory, queue depth, and dispatch latency are separate metrics. When no finite denominator exists—or any constituent provider is unmeasured—the aggregate load is explicitly unavailable.

The migration also keeps old unbounded-provider load: 0 heartbeats unreported during a rolling upgrade, so legacy senders cannot revive the false idle state.

Impact

GET /v1/nodes now returns load: null when utilization is unavailable. SDK consumers must handle the nullable field. Finite-capacity nodes continue returning a numeric ratio.

Companion Relay broker PR: AgentWorkforce/relay#1445

Validation

• 101 focused engine, fleet-wire, and TypeScript SDK tests passed
• TypeScript typechecks passed for engine, types, and SDK packages
• Python node SDK: 17 tests passed
• Rust SDK: 42 tests passed
• migration 0034 backfill exercised against finite, unbounded, mixed-provider, and direct-node fixtures
• Swift implementation sources compiled; Swift tests could not run on this host because the installed toolchain lacks XCTest

[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: 14201d11-36be-45dc-99a6-6db9c2602706

📥 Commits

Reviewing files that changed from the base of the PR and between eb7563f and 747c609.

📒 Files selected for processing (3)

• .agentworkforce/trajectories/completed/2026-08/traj_0h8yn88qklhh/summary.md
• .agentworkforce/trajectories/completed/2026-08/traj_0h8yn88qklhh/trajectory.json
• packages/engine/src/__tests__/conformance/node.test.ts

---

📝 Walkthrough

Walkthrough

The PR records fleet node load semantics and adds conformance tests for unreported heartbeat loads, API exposure, provider persistence, finite load reporting, and placement selection.

Changes

Node load conformance

Layer / File(s)	Summary
Load semantics and conformance validation .agentworkforce/trajectories/completed/2026-08/traj_0h8yn88qklhh/*, packages/engine/src/__tests__/conformance/node.test.ts	The trajectory records unmeasured load behavior and unlimited max_agents=0 semantics. Conformance tests verify persistence, null exposure, finite reporting, and placement that excludes nodes with unknown load.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• AgentWorkforce/relaycast#308: Implements the unreported-load semantics covered by these conformance tests.

Suggested labels: size:L

Poem

A rabbit checked the node-load trail,
Where unknown weights stay marked unscaled.
Finite loads remain in bounds,
Measured nodes receive dispatch rounds.
“Null is clear,” the rabbit sings.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: preserving unreported fleet node load instead of treating it as measured idle.
Description check	✅ Passed	The description directly explains the load-handling changes, API impact, migration, SDK updates, rationale, and validation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ 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 agent/persist-unreported-node-load

---

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.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 1 additional finding.

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}