@lawaty/lacode 0.11.0 → 1.0.1

package/dist/lacode.js

@@ -12,9 +12,9 @@ import { homedir as homedir3 } from "node:os";
 import { join as join4 } from "node:path";
 
 // src/lib/notify.ts
-import { closeSync, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync3, statSync as statSync2, unlinkSync as unlinkSync2, writeSync } from "node:fs";
+import { closeSync, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync3, renameSync as renameSync2, statSync as statSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2, writeSync } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { join as join3 } from "node:path";
+import { basename, join as join3 } from "node:path";
 
 // src/lib/pool.ts
 import { existsSync, mkdirSync, readdirSync, readFileSync as readFileSync2, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
@@ -466,7 +466,7 @@ function describe(env = process.env, platform = process.platform) {
 
 // src/lib/selfupdate.ts
 import { spawn as spawn2 } from "node:child_process";
-import { closeSync as closeSync2, mkdirSync as mkdirSync4, openSync as openSync2, readFileSync as readFileSync5, renameSync as renameSync2, rmSync, statSync as statSync3, unlinkSync as unlinkSync4, writeFileSync as writeFileSync2, writeSync as writeSync2 } from "node:fs";
+import { closeSync as closeSync2, mkdirSync as mkdirSync4, openSync as openSync2, readFileSync as readFileSync5, renameSync as renameSync3, rmSync, statSync as statSync3, unlinkSync as unlinkSync4, writeFileSync as writeFileSync3, writeSync as writeSync2 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
 import { dirname as dirname2, join as join5, resolve } from "node:path";
 var REGISTRY_LATEST = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
@@ -568,7 +568,7 @@ async function refreshCache(opts) {
   const aside = `${cacheRoot}.stale-${Date.now()}`;
   try {
     rmSync(aside, { recursive: true, force: true });
-    renameSync2(cacheRoot, aside);
+    renameSync3(cacheRoot, aside);
   } catch (error) {
     return { ok: false, detail: `could not set the old cache aside: ${String(error)}` };
   }
@@ -603,7 +603,7 @@ async function refreshCache(opts) {
     }
   } else {
     try {
-      renameSync2(aside, cacheRoot);
+      renameSync3(aside, cacheRoot);
     } catch {
     }
   }

package/dist/pool.js

@@ -626,48 +626,24 @@ function snapshot(s) {
 }
 var loadOf = (counts, model) => counts.get(model) ?? 0;
 var underCeiling = (slot, counts) => loadOf(counts, slot.model) < slotCeiling(slot);
-function roundRobinSequence(slots) {
-  const seq = [];
-  for (const slot of slots) for (let turn = 0; turn < slot.weight; turn++) seq.push(slot.index);
-  return seq;
-}
-var CURSOR_FILE = "cursor.json";
-function readCursor(s) {
-  try {
-    const parsed = JSON.parse(readFileSync2(join2(s.dir, CURSOR_FILE), "utf8"));
-    if (typeof parsed.seq === "number" && Number.isInteger(parsed.seq) && parsed.seq >= 0) return parsed.seq;
-  } catch {
+function pickSlot(s, snap) {
+  const slots = s.slots.length > 0 ? s.slots : FALLBACK_SLOTS;
+  const usable = slots.filter((slot) => isAvailable(s, slot.model, snap.cooling));
+  const pool = usable.length > 0 ? usable : slots;
+  for (const slot of usable) {
+    if (loadOf(snap.counts, slot.model) < slot.weight) return slot;
   }
-  return 0;
-}
-function writeCursor(s, seq) {
-  if (!s.dirReady) return;
-  const path = join2(s.dir, CURSOR_FILE);
-  try {
-    writeFileSync(`${path}.tmp`, JSON.stringify({ seq }));
-    renameSync(`${path}.tmp`, path);
-  } catch {
+  for (const slot of usable) {
+    if (loadOf(snap.counts, slot.model) < slotCeiling(slot)) return slot;
   }
+  return pool.reduce((best, slot) => loadOf(snap.counts, slot.model) < loadOf(snap.counts, best.model) ? slot : best, pool[0]);
 }
-function pickSlot(s, snap, options) {
-  const advance = options?.advance !== false;
+function poolPass(s, snap) {
   const slots = s.slots.length > 0 ? s.slots : FALLBACK_SLOTS;
-  const seq = roundRobinSequence(slots);
-  if (seq.length > 0) {
-    const byIndex = new Map(slots.map((slot) => [slot.index, slot]));
-    const start = readCursor(s) % seq.length;
-    for (let step = 0; step < seq.length; step++) {
-      const at = (start + step) % seq.length;
-      const slot = byIndex.get(seq[at]);
-      if (slot && isAvailable(s, slot.model, snap.cooling) && underCeiling(slot, snap.counts)) {
-        if (advance) writeCursor(s, at + 1);
-        return slot;
-      }
-    }
-  }
   const usable = slots.filter((slot) => isAvailable(s, slot.model, snap.cooling));
-  const pool = usable.length > 0 ? usable : slots;
-  return pool.reduce((best, slot) => loadOf(snap.counts, slot.model) < loadOf(snap.counts, best.model) ? slot : best, pool[0]);
+  if (usable.some((slot) => loadOf(snap.counts, slot.model) < slot.weight)) return 1;
+  if (usable.some((slot) => loadOf(snap.counts, slot.model) < slotCeiling(slot))) return 2;
+  return "overflow";
 }
 function agentFor(base, slot) {
   return `${base}-${slot}`;
@@ -829,6 +805,7 @@ export {
   parseSlots,
   parseTextSlots,
   pickSlot,
+  poolPass,
   providerOf,
   pruneOwn,
   pruneSessions,
@@ -843,7 +820,6 @@ export {
   reloadSlots,
   resolveModels,
   retryAfterMs,
-  roundRobinSequence,
   selfFile,
   slotCeiling,
   slotFor,

package/dist/tunnel.js

@@ -5,9 +5,9 @@ import { homedir as homedir3 } from "node:os";
 import { join as join4 } from "node:path";
 
 // src/lib/notify.ts
-import { closeSync, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync3, statSync as statSync2, unlinkSync as unlinkSync2, writeSync } from "node:fs";
+import { closeSync, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync3, renameSync as renameSync2, statSync as statSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2, writeSync } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { join as join3 } from "node:path";
+import { basename, join as join3 } from "node:path";
 
 // src/lib/pool.ts
 import { existsSync, mkdirSync, readdirSync, readFileSync as readFileSync2, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";

package/docs/CONFIGURATION.md

@@ -68,8 +68,8 @@ fields are not affected; `permission`, `prompt`, `model`, `description`,
 The hidden pool variants (`explore-1`, `implement-2`, …) inherit
 nothing here — add a line per variant, or drop the global
 deny and scope it to the agents that should not have browser access instead.
-Note that you cannot *spawn* a variant by name: the pool refuses
-`explore-1` and friends and points you at the bare base, so per-variant
+Note that you cannot *spawn* a variant by name: the pool rewrites
+`explore-1` and friends to their base and routes them, so per-variant
 permissions only ever apply to a spawn the plugin routed itself.
 
 The pool files are the exception to the restart rule: editing `pool.txt`,

package/docs/USER-STORIES.md

@@ -15,11 +15,7 @@ line. Criteria that cannot be observed without a running server are not in this
 document; everything here is testable offline with a stub client and a
 `mkdtempSync` state directory.
 
-**Terminology.** A *slot* is one entry in `presets/free-tier.json`, carrying a
-model and a `weight`. A *base* is a pooled agent type (`explore`), and its slot
-holders are `<base>-<slot>`, hidden in `opencode.jsonc`. A *claim* is a running
-spawn recorded in `claims.<pid>.json`. A *context map* is the five-file
-`.opencode/context/` codemap described in Epic G.
+**Terminology.** A *slot* is one entry in `presets/free-tier.json`, carrying a model and a `weight`. A slot's `weight` is its active-session budget for one pass: the number of concurrent claims it may hold before the next slot is preferred. A *pass* is one declaration-order sweep of the slot list; the pool runs at most two passes, and a slot's absolute cap is twice its weight. Preference is by declaration order, never by weight. A *base* is a pooled agent type (`explore`), and its slot holders are `<base>-<slot>`, hidden in `opencode.jsonc`. A *claim* is a running spawn recorded in `claims.<pid>.json`. A *context map* is the five-file `.opencode/context/` codemap described in Epic G.
 
 ---
 
@@ -96,16 +92,18 @@ The reconciliation with US-7 is that **acceptance and endorsement are different
 - [ ] Given every model is cooling, When a spawn is routed, Then the least-loaded slot is chosen anyway (degrade, never block).
 - [ ] Given a limit error names a reset time, When the cooldown is recorded, Then the stated reset is used instead of a guessed backoff.
 
-### US-5: Weighted round-robin gives every slot a turn per cycle
-**As a** user, **I want** weights to say how many turns each slot takes per rotation cycle, **so that** no provider is drained to its limit while the others sit idle.
+### US-5: Slots fill in declaration order, in up to two passes
+**As a** user, **I want** work to prefer the first slot and spill to later slots only when the earlier ones are full, **so that** a healthy preferred model is used before fallbacks and no slot is used while an earlier usable slot has room.
 
 **Story ID(s) for tests:** US-5
 **Acceptance criteria:**
-- [ ] Given a heavy slot and a light slot, When spawns are routed below both ceilings, Then the rotation walks the list in order with each slot taking as many consecutive turns as its weight says, rather than the heavy slot being filled and refilled first.
-- [ ] Given a slot is at its ceiling (twice its weight) or cooling, When its turn comes up in the rotation, Then the turn is skipped and the rotation resumes at the following turn.
-- [ ] Given every slot is at its ceiling, When another spawn is routed, Then it goes to the least-loaded slot as overflow.
-- [ ] Given all slots carry equal weight, When spawns are routed, Then the picks round-robin in declaration order.
-- [ ] Given per-slot load is read, When it is asserted, Then a slot's load never exceeds its ceiling (twice its weight) except by overflow.
+- [ ] Given live claims, When the pool has room in the first pass, Then the lowest-index usable slot whose load is below its weight is chosen, and a slot declared later is not used until every earlier usable slot has reached its weight.
+- [ ] Given every usable slot has reached its weight, When another spawn is routed, Then the second pass begins at the lowest-index slot and fills each usable slot up to twice its weight.
+- [ ] Given a slot is cooling or unavailable, When its position in the pass comes up, Then it is skipped and the pass continues to the next slot.
+- [ ] Given a claim is released, When the next spawn is routed, Then the slot that freed capacity is preferred again in declaration order; no stored position keeps it waiting.
+- [ ] Given every usable slot is at its absolute cap, When another spawn is routed, Then it goes to the least-loaded usable slot as overflow, and the pool never refuses work.
+- [ ] Given all slots carry equal weight, When spawns are routed, Then the same ordered two-pass fill applies.
+- [ ] Given per-slot load is read, When it is asserted, Then a slot's load never exceeds twice its weight except through overflow.
 
 ### US-6: Live pool visibility
 **As a** user, **I want** to see per-slot load and which model is cooling and why, **so that** I understand where my subagents are going.
@@ -115,7 +113,8 @@ The reconciliation with US-7 is that **acceptance and endorsement are different
 - [ ] Given claims are held by several processes, When the status view is requested, Then it shows every process's claims and the aggregate load per slot.
 - [ ] Given a model is cooling with a stated reason, When the status view is requested, Then the model is listed as cooling together with that reason.
 - [ ] Given a claim file is older than the dead-file threshold, When the status view is computed, Then the stale claim is pruned rather than counted.
-- [ ] Given a slot is at its ceiling, When the status view is requested, Then it is not marked as the slot the next spawn would take, because the rotation's turns are skipped for a full slot until it frees a claim — unless no other slot is available and under its ceiling, in which case that full slot is the next one.
+- [ ] Given a slot is at its absolute cap, When the status view is requested, Then it is not marked as the slot the next spawn would take while any usable slot is below its current pass target; when every usable slot is at its absolute cap, the least-loaded slot is marked next.
+- [ ] Given the pool is filling, When the status view is requested, Then it shows whether the next spawn belongs to the first pass, the second pass, or overflow.
 
 ### US-7: Non-free models still work
 **As a** user who wants a paid model in the pool, **I want** to supply any model list, **so that** the pool is not restricted to free tiers.
@@ -320,7 +319,7 @@ The popup belongs to its session: working in one chat closes that chat's popup a
 - [ ] Given a body containing `"`, `'`, `;`, `$(…)` or backticks, When the macOS send runs, Then it reaches `display notification` byte-for-byte as data and nothing is executed.
 - [ ] Given a machine has no notifier for its platform, When a notification is sent, Then the result is a failed delivery with a reason and no exception, and `lacode doctor` names the channel that would run — or reports that there is none — instead of reporting a binary that is not used there.
 - [ ] Given the CLI runs on macOS, When the send does not complete, Then it is still bounded by a timeout, exactly as on Linux.
-- [ ] Given the notification hop, When it is documented, Then the doc leads with the shipped path — the npm-installed plugin, a direct ssh hop (`ControlMaster`) set up by `lacode tunnel setup`, and the portable `lacode receive` forced command that delivers through the platform channel (`notify-send` or `osascript`) — and marks the reverse-forward scripts (`bin/oc`, `bin/oc-notify`, `bin/oc-notify-receiver`, `bin/oc-sync`) as the author's legacy tooling, so a Mac user is not sent to debug a script that was never meant to run on their machine.
+- [ ] Given the notification hop, When it is documented, Then the doc leads with the shipped path — the npm-installed plugin, a direct ssh hop (`ControlMaster`) set up by `lacode tunnel setup`, and the portable `lacode receive` forced command that delivers through the platform channel (`notify-send` or `osascript`) — and marks the reverse-forward scripts (`bin/oc`, `bin/oc-notify`, `bin/oc-notify-receiver`, `bin/oc-sync`) as the author's own scripts, so a Mac user is not sent to debug a script that was never meant to run on their machine.
 - [ ] Given a machine without GNU `timeout` or with bash older than 4.0, When `bin/oc-sync` runs, Then it refuses **before** touching anything, names each missing prerequisite, and names the `lacode` subcommand to use instead. It must never report a misleading cause: the host list is read with `mapfile`, so without it the run dies at "no hosts configured" — a confident wrong answer that sends the reader to edit `.env`.
 - [ ] Given `bin/oc-notify-receiver` runs where `notify-send` does not exist, When it is invoked, Then it exits non-zero and names both the missing channel and the portable path, because its stderr reaches whoever opened the ssh connection and nobody else, and a bare "command not found" reads as a desktop that quietly stopped notifying.
 - [ ] Given the payload is parsed, When the receiver splits `$SSH_ORIGINAL_COMMAND`, Then it splits on newlines only using constructs that exist in bash 3.2 as well as bash 5, and the suite **proves the split by running the receiver** rather than by finding the word `mapfile` in the file. Under bash 3.2 — the version macOS ships — a bash-4-only builtin leaves every field at its default, so the popup says "LaCode" with an empty body and no error anywhere: the same silent blank notification the argv bug causes, reached through a different door.
@@ -511,8 +510,8 @@ table was filled in.
 | US-3 | A | `tests/stories/a-cost-control.test.mjs` (harness: `tests/benchmark/run.mjs`) |
 | US-23 | A | `tests/stories/a-cost-control.test.mjs` |
 | US-4 | B | `tests/stories/b-provider-resilience.test.mjs`, `tests/pool-limits-test.mjs` |
-| US-5 | B | `tests/stories/b-provider-resilience.test.mjs`, `tests/pool-test.mjs`, `tests/pool-models-test.mjs` |
-| US-6 | B | `tests/stories/b-provider-resilience.test.mjs` |
+| US-5 | B | `tests/stories/b-slot-fill.test.mjs`, `tests/stories/b-provider-resilience.test.mjs`, `tests/pool-test.mjs`, `tests/pool-models-test.mjs` |
+| US-6 | B | `tests/stories/b-provider-resilience.test.mjs`, `tests/stories/b-slot-fill.test.mjs` |
 | US-7 | B | `tests/stories/b-provider-resilience.test.mjs`, `tests/pool-models-test.mjs` |
 | US-28 | B | `tests/stories/i-omniroute.test.mjs` |
 | US-31 | B | `tests/stories/b-provider-resilience.test.mjs`, `tests/stories/c-hang-recovery.test.mjs` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawaty/lacode",
-  "version": "0.11.0",
+  "version": "1.0.1",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",
@@ -62,6 +62,6 @@
     "@opencode-ai/plugin": "1.18.34"
   },
   "publishConfig": {
-    "tag": "beta"
+    "tag": "latest"
   }
 }

package/presets/README.md

@@ -63,7 +63,7 @@ else means the flat form.
 | Field | Required | Meaning |
 |-------|----------|---------|
 | `model` | yes | `provider/model-id`, split on the **first** slash only |
-| `weight` | no | turns taken per rotation (the slot's share of the rotation); its concurrency ceiling is twice that. Absent = 1 |
+| `weight` | no | active-session budget for one pass; its absolute cap is twice that. Absent = 1 |
 
 `$comment` is a JSON-legal array of strings and is ignored by the loader; the
 bundled preset uses it to explain itself in place.
@@ -81,7 +81,7 @@ The loader checks shape and nothing else:
 - at most `MAX_SLOTS` (4) slots; extra entries are **dropped with a warning**,
   because one hidden variant agent per base per slot exists and a fifth slot
   would route at an agent that does not exist
-- `tier` is accepted as a deprecated alias for `weight` (`primary` → 2,
+- `tier` is accepted as an alias for `weight` (`primary` → 2,
   `overflow` → 1) and warns
 
 **Cost is never validated.** Any provider/model-id string is accepted, including
@@ -92,28 +92,26 @@ because the pool requires it.
 
 ## Weight, precisely
 
-A weight is the number of turns a slot takes per rotation — its share of the
-work — and its concurrency ceiling is **twice that weight**: a weight-3 slot may
-hold 6 concurrent sessions. Routing is **order-first weighted round-robin**:
-
-1. the slot list is expanded into a run in which each slot appears once per
-   unit of its weight — `[3,2,1,1]` becomes `1,1,1,2,2,3,4` — and the next
-   spawn takes the turn a persistent cursor (a file in the pool directory,
-   shared by every opencode process) points at
-2. a turn whose slot is cooling or already at its ceiling is **skipped**, and
-   the rotation resumes at the following turn
-3. once **every** slot is at its ceiling, overflow goes to the least loaded slot —
-   a burst past the summed ceilings degrades to even spreading and never blocks
-
-Weight is no longer a priority: a heavy slot is not drained to its ceiling
-before the others see any work. Every slot gets a turn each cycle, so a fast
-provider with a large usage window is used early in the cycle while it is
-still fast — instead of one provider being refilled until it hits its limit
-and its 429s displace every agent type at once.
-
-Equal weights give a plain round robin in list order. List order is the
-rotation itself, so put the models you want taking the earlier turns of a
-cycle at the top and the ones you want taking the later turns at the bottom.
+A weight is a slot's active-session budget for one pass: the number of
+concurrent claims it may hold before the next slot is preferred. Its absolute
+cap is **twice that weight** — a weight-3 slot may hold 6 concurrent sessions.
+Slots are filled in declaration order; preference is order, never weight.
+
+Routing runs in two passes:
+
+1. pass 1 fills each usable slot up to its weight, in declaration order
+2. once every usable slot has reached its weight, pass 2 repeats the order,
+   filling each usable slot up to twice its weight
+
+A slot is skipped when it is cooling, unavailable, or at its absolute cap.
+When every usable slot is at its absolute cap, overflow goes to the least
+loaded usable slot; the pool never refuses work.
+
+Live claims decide the next slot: a released claim immediately reopens its
+slot, and there is no stored position.
+
+Equal weights give a plain pass in list order. List order is preference, so
+put the slots you want preferred first at the top of the list.
 
 Spreading at least two providers across the slots is worth doing deliberately: a
 provider-wide rate limit takes out every slot on that provider at once.

package/presets/free-tier.json

@@ -13,52 +13,36 @@
     "AT MOST 4 SLOTS: one hidden variant per base per slot is declared, so a fifth entry would",
     "route at an agent that does not exist. Extra entries are dropped with a warning.",
     "",
-    "WEIGHT IS THE ONLY KNOWN KNOB: one position per unit of weight in the rotation run,",
-    "and a concurrency ceiling of TWICE that weight -- a share of the work, not a priority.",
-    "Routing is ORDER-FIRST",
-    "WEIGHTED ROUND-ROBIN: the slot list is walked IN ORDER and each slot takes as many",
-    "consecutive turns as its weight says, so weights 3,2,1,1 produce the run 1,1,1,2,2,3,4,",
-    "which then repeats. The rule is:",
-    "  1. a persistent cursor in the pool directory marks where in that run the next spawn",
-    "     lands, so every opencode process on the machine shares one rotation",
-    "  2. a turn is SKIPPED only when its slot is cooling or already at its ceiling, and the",
-    "     rotation resumes at the following turn",
-    "  3. once EVERY slot is at its ceiling, the overflow goes to the least loaded slot,",
-    "     so a burst past the summed ceilings degrades to even spreading and never blocks",
+    "WEIGHT IS THE ACTIVE-SESSION BUDGET FOR ONE PASS: a slot may hold up to its weight in",
+    "concurrent claims before the next slot is preferred. Slots are filled in declaration",
+    "order; preference is order, never weight.",
+    "Routing runs in two passes:",
+    "  1. pass 1 fills each usable slot up to its weight, in declaration order",
+    "  2. once every usable slot has reached its weight, pass 2 repeats the order, filling",
+    "     each usable slot up to twice its weight",
+    "A slot is skipped when it is cooling, unavailable, or at its absolute cap (twice its",
+    "weight). When every usable slot is at its absolute cap, overflow goes to the least",
+    "loaded usable slot; the pool never refuses work.",
+    "Live claims decide the next slot: a released claim immediately reopens its slot, and",
+    "there is no stored position.",
     "",
-    "With this file: big-pickle takes 3 consecutive turns, then beam-free",
-    "(opencode-go) takes 2, then deepseek-v4.1-flash-free and glm-5.3-flash-free take 1",
-    "each -- sequence 1,1,1,2,2,3,4,...",
-    "Equal weights give a plain round robin in list order. 2,2,1,1 reproduces the old",
-    "primary/overflow cycle exactly, which is why the old tier values still work.",
+    "With this file: weights 3,2,1,1 give 7 active sessions in pass 1 and 14 total across",
+    "both passes.",
+    "Equal weights give a plain pass in list order.",
     "",
-    "WEIGHTS DESCEND, AND THAT IS NOT COSMETIC. The rotation is order-first: the run is",
-    "expanded in declaration order, so the heaviest slot must come first for a skip to",
-    "land on the heaviest slot that is LEFT. A heavier slot declared after a lighter one",
-    "is unreachable in the way the pool means.",
+    "DECLARATION ORDER IS PREFERENCE. Slots are filled in declaration order, so the slot",
+    "you want preferred comes first; weight sets its per-pass budget, not its priority.",
     "",
     "EVERY SLOT IS A MODEL THAT IS PROBABLY STILL THERE NEXT WEEK, AND NO TWO SLOTS",
-    "SHARE A FAMILY. A free model can be withdrawn by its provider without warning --",
-    "space-bunny-free was pulled from the opencode provider while it was still this",
-    "file's first slot, and every new session then died on 'Model not found'. So the",
-    "slots here are the long-lived free ones (big-pickle has been on the opencode",
-    "provider for years), spread over two providers and four model families, because a",
-    "pool where every slot is one family is one withdrawal away from being empty. If a",
-    "slot does go away, the plugin warns at startup and the rest keep working; the fix",
-    "is a one-line edit here, not a redesign.",
-    "",
-    "Round-robin rather than heaviest-first because re-prioritising the heaviest slot on",
-    "EVERY spawn drained the fastest provider's free-tier window early: one provider",
-    "absorbed all work up to its ceiling and kept being refilled the moment a claim",
-    "completed, while the other slots sat idle -- until the fast provider hit its limit and",
-    "its 429s displaced every agent type at once. Every slot a turn per cycle puts a fast",
-    "slot with a large usage window to work early in the cycle while it is still fast, and",
-    "no provider's quota sits unused while another's is drained.",
+    "SHARE A FAMILY. A free model can be withdrawn by its provider without warning, and",
+    "a pool where every slot is one family is one withdrawal away from being empty. The",
+    "slots here are long-lived free ones spread over two providers and four model",
+    "families. If a slot does go away, the plugin warns at startup and the rest keep",
+    "working; the fix is a one-line edit here, not a redesign.",
     "",
     "Absent means weight 1. Must be a number in (0, 100]; anything else warns and uses 1.",
-    "List order sets the rotation for every slot, not just a tie-break: earlier positions",
-    "take their turns earlier in each cycle, so put the slots you want worked first at the",
-    "top of the list.",
+    "List order sets preference: earlier slots are preferred first, so put the slots you",
+    "want worked first at the top of the list.",
     "",
     "COST IS THE DEFAULT, NOT A CONSTRAINT. These four slots are free because that is what",
     "the pool is FOR: mechanical work -- reading files, grepping, mechanical edits, cartography.",