From 48d7841fbf9dc3bfc8e173c58fcd04b917f824ed Mon Sep 17 00:00:00 2001 From: Dai Ha Date: Sun, 16 Aug 2026 18:27:19 +0200 Subject: [PATCH] CB-589: document that weighted placement is not cheapest-first The weight ratio does not express a preference order. weighted spreads spawns across every profile with a free slot, so paid spawns happen while the free box is idle - and a profile at maxLoad freezes its score, so it can lose the next pick after a slot frees. The real fix is a cost-first policy (CB-589). This documents the workaround and its trap next to the key, because bridged.yaml is gitignored: a fresh host starts without the workaround and quietly pays, with nothing to tell the operator why. Comments only. BridgedConfigTest: 85 tests, BUILD SUCCESS. --- bridged/bridged.example.yaml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/bridged/bridged.example.yaml b/bridged/bridged.example.yaml index cec5520..ebf506c 100644 --- a/bridged/bridged.example.yaml +++ b/bridged/bridged.example.yaml @@ -275,6 +275,26 @@ profiles: # argv: ["opencode"] # How an unqualified spawn chooses a profile: fixed (default, reproduces pre-CB-518 behaviour), # round-robin, or weighted. Omitting this key is a strict no-op for existing configs. +# +# `weighted` IS NOT "cheapest first" — read this before you set weights (CB-589). +# It is smooth weighted round-robin: it spreads spawns across EVERY profile that has a free slot, +# in weight ratio. It has no idea which profile costs money. So with local:10 / paid:2 you do not +# get "use local, overflow to paid" — you get roughly one spawn in six going to the paid profile +# while the local box still has a free slot. +# +# There is a sharper second effect. The policy's running score map lives for the daemon's whole +# life. While a profile is at maxLoad it is filtered out and its score FREEZES, so the paid +# profiles keep accumulating against it. When the local slot frees up it returns with a stale +# score and can LOSE the next pick — a paid spawn while the free box sits idle. +# +# Until a real cost-first policy exists, the workaround is to make the ratio decisive rather than +# proportional: give the free profile a weight so large that it wins every pick it is eligible +# for, and paid profiles only ever take genuine overflow. On this host that is local weight 100 +# against paid weights of ~1. +# +# The gotcha with that workaround: it expresses a PREFERENCE ORDER through a RATIO knob. Add a +# future profile at weight 150 and it silently outranks the free box, with nothing to warn you. +# Re-check the weights whenever you add a profile. placement: weighted # How long a credential sits out after a BACKEND_EXHAUSTED classification (CB-578 stage B), in