Skip to content

feat(placement): load-aware placement that fills headless machines first - #85

Merged
nullStack65 merged 2 commits into
release/native-0.1.10from
feat/native-0.1.10-load-aware-placement
Nov 18, 2026
Merged

nullStack65 merged 2 commits into
release/native-0.1.10from
feat/native-0.1.10-load-aware-placement

Conversation

@nullStack65

Copy link
Copy Markdown
Owner

Today the ASUS (8 cores) reached a load of 64 and stopped responding while the R720 (48 cores) sat mostly idle. Automatic placement only compared a short CPU sample with free memory. It could not see run-queue saturation or how many agents a machine already runs, and it had no way to keep work off the computers Kameron and Jeff use.

What changes

  1. Placement evidence (HostResourcesSnapshot, optional fields so older servers still decode): load per host CPU, running agent scopes on the host across every T3 server, the machine's placement role, and whether its person is active.
  2. Balancer (packages/shared/src/loadBalancing.ts, used by server placement:'auto' and the web auto-balance draft): two tiers. Headless machines fill first. A machine counts as saturated at load ≥ 1 per CPU, CPU ≥ 95%, or memory under 5% or 1.5 GB. The score is cores × idle share × free memory share ÷ (1 + running agents). Someone's computer is a candidate only if every headless machine is full, its person is idle, CPU and load per CPU are under 50%, at least 3 GB and 40% of memory are free, and fewer than 2 agents run there. A machine that doesn't report a role, or can't tell whether someone is active, is never used.
  3. Machine role (machinePlacementRole, default auto): Detect treats the desktop app, macOS, Windows, or a local Linux graphical login (logind Display session of type x11/wayland, not remote) as someone's computer. Activity comes from logind Active/Locked/Idle on Linux and HIDIdleTime under 10 minutes on macOS.
  4. Hard caps on someone's computer (agentScope.ts): the agents slice gets CPUQuota of half the cores, CPUWeight=1 and IOWeight=1. Agents start slowing once free memory falls to 4 GB or 40% of RAM, and one is killed at 3 GB or 30%. Headless limits are unchanged. Limits follow a role change at the next launch.
  5. Default on (automaticPlacementByDefault, Closura default true): an agent's t3_thread_launch of a worktree started from origin is placed without asking. placement:'here' or the setting turned off keeps it local. If nothing has room, it starts here, as before. An explicit placement:'auto' still fails loudly.
  6. delegate_task without placement still shares the parent's checkout. A child moved elsewhere would silently lose uncommitted edits. Its placement description now steers agents to 'auto' for independent work.
  7. Settings: web Labs → Load balancing (role and default toggle). Mobile gets a per-machine Automatic placement toggle. User docs updated in docs/user/remote-access.md.

Verified locally (R720, Node 22): typecheck for contracts, shared, server, web and mobile. Tests: threadPlacement (7), HostResources (8), MachinePresence (4), agentScope (17), RemoteDelegation (53, including 2 new default-placement tests), project handlers, OrchestratorMcpService, McpHttpServer, ProviderSessionManager, serverSettings, and the contracts suite all pass. DesktopTelemetryReceiver.test.ts has one failure that also fails on the unmodified base. vp lint could not load the repo's TypeScript oxlint plugin on this host's Node 22 (the repo pins Node 26), so CI owns lint.

Not covered here: Jeff's machines run their own builds and are read-only links, so they are already never placement targets from the fleet. macOS agent processes get no CPU cap, because there is no systemd there.

Model: claude-opus-5-5
Task: implementation

🤖 Generated with Claude Code

nullStack65 and others added 2 commits November 18, 2026 22:24
Placement now reads load per core, running agents, and whether a machine
belongs to a person. Headless machines take work first; someone's computer
only when every headless one is full and nobody is using it, and agents
there are capped so it stays responsive. Fresh worktrees from origin are
placed by default in Closura builds.

Model: claude-opus-5-5
Task: implementation
Agent: Builder

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… machine

From review: logind errors no longer read as headless, a machine without
agent scopes reports no agent count, default placement needs the caller's
clientRequestId so a retry finds the chosen machine, and work started on
someone's computer stays there when nothing else has room.

Model: claude-opus-5-5
Task: fix
Agent: Builder

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nullStack65

Copy link
Copy Markdown
Owner Author

Independent review round (Claude Opus 5.5 subagent, read-only, against the common ancestor f7b207768c). Head reviewed: 94f6b28dc8. Fixes are in 12c8580dee, rebased onto release/native-0.1.10 at 2349389883.

Findings and what happened to each:

  1. Machines on older releases are never chosen. Kept on purpose: a machine that doesn't report a role counts as someone's computer in use, so a GUI machine on an old build is never loaded by mistake. The code comment and user docs now say so. Fleet machines pick this up when they upgrade.
  2. The person's own machine was refused for its own automatic work when no headless machine had room. Fixed. The origin keeps the work if it passes headless limits, as before this change (chooseLoadBalancedEnvironment(..., originEnvironmentId)), with a new test.
  3. A default launch without clientRequestId could be duplicated on retry. Fixed. Default placement now requires the caller's key, and a launch without one stays local. The test is updated.
  4. A logind failure classed a Linux workstation as headless. Fixed. Only a successful "no local graphical session" answer, or logind's "not logged in", counts as headless. Any other failure counts as someone's computer in use. Covered by a test.
  5. Without agent scopes the agent count read 0. Fixed. A missing agents slice now reports no count, so someone's computer without caps is never a candidate.
  6. The macOS idle check was dead code. Removed. macOS and Windows always report someone in use, and the docs say they never take placed work from another machine.

Checked fine by the reviewer: resetting the headless quota with CPUQuota=, slice ownership, the applyMemoryLimits retry, the binding and replay order, and layer wiring. Not fixed: two T3 servers on one host with different roles would overwrite each other's slice limits. No fleet host runs two servers with different roles.

Re-verified after the rebase: server, web and mobile typecheck pass. RemoteDelegation, agentScope, MachinePresence and HostResources pass (83 tests), and shared threadPlacement passes (8).

@nullStack65
nullStack65 force-pushed the feat/native-0.1.10-load-aware-placement branch from 94f6b28 to 12c8580 Compare November 18, 2026 22:27
@nullStack65
nullStack65 merged commit 81ecf0a into release/native-0.1.10 Nov 18, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant