@lawaty/lacode 0.3.0 → 0.4.0

package/README.md

@@ -337,6 +337,9 @@ as an opencode provider for you. It is **off by default**: if you do not set
    disabled for that run, and the integration is per-run.
 2. Add the plugin block to your opencode config:
    `["@lawaty/lacode", { "omniroute": { "enabled": true, "apiKey": "<your omniroute key>", "combo": "auto", "models": [] } }]`
+   `auto` is the zero-config default, but on a free tier it often resolves to a
+   slow chain. [A tested fast combo](#a-tested-fast-combo-free-mix) below is
+   ordered for latency and is worth applying on a new client.
 3. Optionally, to route pooled work through it, make `omniroute/auto 3` the
    **first** line of `~/.config/lacode/pool.txt`. `pool.txt` is optional user
    config; the bundled default preset does **not** include OmniRoute.
@@ -426,6 +429,98 @@ the only thing that changes when the gateway is down is that `omniroute/<id>`
 fails; every other slot keeps working. See
 [docs/USER-STORIES.md](docs/USER-STORIES.md) US-28.
 
+### A tested fast combo: `free-mix`
+
+`combo: "auto"` is the zero-configuration default, but `auto` inherits whatever
+the gateway chooses, and on a busy free tier that is frequently the slowest
+chain available. The combo below was **measured** against a live free-tier
+gateway and is ordered for latency rather than for breadth. Apply it during the
+"Setting it up on a client machine" steps above and pooled work is usable
+straight away, instead of starting from a gateway that queues for half a minute
+per call.
+
+```jsonc
+{
+  "name": "free-mix",
+  // Order decides. Do NOT use "weighted" here — weights let the gateway
+  // re-shuffle a model that is returning 429 into first position again.
+  "strategy": "priority",
+  "models": [
+    { "model": "gemini/gemini-3.1-flash-lite",                      "providerId": "gemini" },
+    { "model": "gemini/gemini-3.8-flash",                           "providerId": "gemini" },
+    { "model": "gemini/gemini-3.7-flash",                           "providerId": "gemini" },
+    { "model": "gemini/gemini-3-flash-preview",                     "providerId": "gemini" },
+    { "model": "openrouter/nvidia/nemotron-3-super-120b-a12b:free",  "providerId": "openrouter" },
+    { "model": "openrouter/nvidia/nemotron-3-ultra-550b-a55b:free",  "providerId": "openrouter" },
+    { "model": "openrouter/nvidia/nemotron-3.5-lightning:free",     "providerId": "openrouter" },
+    { "model": "openrouter/cohere/north-mini-code:free",            "providerId": "openrouter" },
+    { "model": "openrouter/poolside/laguna-s-2.1:free",             "providerId": "openrouter" },
+    { "model": "openrouter/dots-studio/dots-3-note-preview:free",   "providerId": "openrouter" }
+  ]
+}
+```
+
+Why this order, from 859 calls over a single day against that gateway:
+
+| Model | Observed behaviour | Position |
+| --- | --- | --- |
+| `gemini/gemini-3.1-flash-lite` | **165/172 succeeded (96%)**, ~4.5s median | **first** |
+| `gemini-3.8-flash` / `3.7-flash` / `3-flash-preview` | succeed intermittently, but **burn exactly 30.0s** on a `503` queue-budget timeout when they do not | next |
+| `openrouter/*:free` | **~90% `429`**, but fails *fast* (~1.8s) and occasionally succeeds | last, as a cheap final fallback |
+| `gemini-2.5-flash`, `gemini-2.5-flash-lite` | **`404` on every attempt** — dead ids | **omitted entirely** |
+
+The ordering matters because a combo pays for *every* step it walks past. Put the
+96%-success model first and the common case is a single hop; the 30s models sit
+behind it where they cost nothing, and the 429s sit last where they give up in
+under two seconds.
+
+Measured on the same gateway, same day, `max_tokens: 10`:
+
+| | Before | After |
+| --- | --- | --- |
+| `free-mix` response | 42.7s / 41.8s / 34.7s | 4.1s / 3.1s / 3.2s / 4.0s / 3.2s |
+| Median | **~41.8s** | **~3.2s** |
+| Provider time burned on calls >25s | **56.9 of 102.4 min (56%)** | — |
+
+Before the change, the real call sequence was a `429` after 2.7s, then a `503`
+after 30.0s, then the actual work in 5.7s — roughly **33 seconds of dead time in
+front of every successful request**, and a p90 of 100s when three 30s steps
+chained.
+
+These free-tier endpoints change availability constantly, so treat the ordering
+as a **starting point to re-measure, not a permanent truth**. Re-check it with
+OmniRoute's own call logs before assuming it still holds:
+
+```bash
+# one timed request through the gateway
+curl -o /dev/null -w '%{http_code} %{time_starttransfer}s\n' \
+  -X POST http://localhost:20128/v1/chat/completions \
+  -H "Authorization: Bearer $OMNIROUTE_API_KEY" -H 'Content-Type: application/json' \
+  -d '{"model":"free-mix","messages":[{"role":"user","content":"Say OK"}],"max_tokens":10}'
+
+# per-model status + duration, straight from OmniRoute's logs
+python3 - <<'PY'
+import json, glob, collections
+d = "/home/<user>/.omniroute/call_logs/<YYYY-MM-DD>"
+g = collections.defaultdict(collections.Counter)
+for f in glob.glob(d + "/*.json"):
+    try: s = json.load(open(f))["summary"]
+    except Exception: continue
+    g[s.get("comboStepId")][s.get("status")] += 1
+for k, v in sorted(g.items(), key=lambda x: str(x[0])):
+    print(f"{str(k)[:44]:44} {dict(v)}")
+PY
+```
+
+Apply it with the bundled CLI (`PUT /api/combos/<id>` updates in place, so the
+combo is never briefly missing):
+
+```bash
+omniroute api combos get-api-combos-id- --id <combo-id> --json > free-mix.json
+# edit name/strategy/models in free-mix.json, then:
+omniroute api combos put-api-combos-id- --id <combo-id> --body @free-mix.json
+```
+
 **A note on mid-session switching.** opencode 1.18.34 exposes no hook to change
 an agent's main model mid-request, so LaCode cannot swap models inside a running
 session; use an OmniRoute `combo` (or `auto`) if you want per-request fallback.
@@ -570,6 +665,28 @@ published, because none has been independently measured. The mechanism, the
 permission rule that makes one writer possible, and what the log lines mean are
 in [docs/CONTEXT.md](docs/CONTEXT.md).
 
+## Managerial directions
+
+You can optionally add `manager.md` to `.opencode/context/`. This file is owned
+by you alone and is never written, edited, pruned, or promoted by any agent. It
+outranks the five generated files on focus and settled decisions, but it is
+secondary to the source code: if the code disagrees, the code wins and the
+conflict is reported back to you.
+
+The file is per-clone, not committed, and entirely optional: if it is missing,
+agents behave exactly as before. When present, it should contain these three
+sections:
+
+- `## Stage`: A snapshot of your current work-in-progress. Rewrite this section
+  rather than appending to it to keep it concise. If this file passes roughly 150
+  lines, run `/context-review`.
+- `## Confirmed`: Facts and decisions you have personally ratified. Treat these
+  as settled, but not as permission to skip reading the code.
+- `## Instructions`: Standing managerial directions for all agents.
+
+No agent may write this file at all: the context agent's edit permission denies
+`manager.md` explicitly, so ratification can only ever come from your hand.
+
 ## Cost
 
 The mechanism is specific and small: bulk exploration, implementation and

package/dist/agents.js

@@ -43,6 +43,7 @@ var DEFAULT_PRESET = join2(PRESETS_DIR, "free-tier.json");
 var USER_CONFIG_DIR = join2(homedir(), ".config", "lacode");
 var USER_MODELS_PATH = join2(USER_CONFIG_DIR, "pool.json");
 var USER_MODELS_TXT = join2(USER_CONFIG_DIR, "pool.txt");
+var CHILD_MEMORY_MS = 30 * 6e4;
 
 // src/agents.ts
 var POOLED_BASES = ["explore", "implement", "context"];

package/dist/index.js

@@ -243,6 +243,7 @@ function state(opts = {}) {
       cooling: /* @__PURE__ */ new Map(),
       strikes: /* @__PURE__ */ new Map(),
       activity: /* @__PURE__ */ new Map(),
+      children: /* @__PURE__ */ new Map(),
       reaped: 0,
       reaping: false,
       lastSweep: 0,
@@ -284,7 +285,7 @@ function init(s, onWarn) {
 }
 function pruneOwn(s) {
   const now = Date.now();
-  for (const [key, claim] of s.own) if (now - claim.t > CLAIM_TTL_MS) s.own.delete(key);
+  for (const [key, claim] of s.own) if (now - (claim.hb ?? claim.t) > CLAIM_TTL_MS) s.own.delete(key);
 }
 function publish(s) {
   if (!s.dirReady) return;
@@ -349,7 +350,7 @@ function readSiblings(s) {
     try {
       const parsed = JSON.parse(readFileSync2(path4, "utf8"));
       const claims = Object.values(parsed).filter(
-        (c) => c && typeof c.v === "string" && typeof c.m === "string" && now - c.t <= CLAIM_TTL_MS
+        (c) => c && typeof c.v === "string" && typeof c.m === "string" && now - (c.hb ?? c.t) <= CLAIM_TTL_MS
       );
       siblings.push({ id: match[1], claims });
     } catch {
@@ -463,26 +464,72 @@ function snapshot(s) {
 }
 var loadOf = (counts, model) => counts.get(model) ?? 0;
 var underCeiling = (slot, counts) => loadOf(counts, slot.model) < slot.weight;
-function pickSlot(s, snap) {
+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 {
+  }
+  return 0;
+}
+function writeCursor(s, seq) {
+  if (!s.dirReady) return;
+  const path4 = join2(s.dir, CURSOR_FILE);
+  try {
+    writeFileSync(`${path4}.tmp`, JSON.stringify({ seq }));
+    renameSync(`${path4}.tmp`, path4);
+  } catch {
+  }
+}
+function pickSlot(s, snap, options) {
+  const advance = options?.advance !== false;
   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;
-  const open = pool.filter((slot) => underCeiling(slot, snap.counts));
-  if (open.length > 0) return open.reduce((best, slot) => slot.weight > best.weight ? slot : best, open[0]);
   return pool.reduce((best, slot) => loadOf(snap.counts, slot.model) < loadOf(snap.counts, best.model) ? slot : best, pool[0]);
 }
 function agentFor(base, slot) {
   return `${base}-${slot}`;
 }
 function acquire(s, base, slot, ownerSession, key, target) {
-  s.own.set(key, { v: base, k: slot.index, m: slot.model, t: Date.now(), s: ownerSession, g: target });
-  if (target) s.activity.set(target, Date.now());
+  const now = Date.now();
+  s.own.set(key, { v: base, k: slot.index, m: slot.model, t: now, hb: now, s: ownerSession, g: target });
+  if (target) s.activity.set(target, now);
   publish(s);
 }
 function release(s, key) {
   if (s.own.delete(key)) publish(s);
 }
+var CHILD_RING = 8;
+var CHILD_MEMORY_MS = 30 * 6e4;
+var CHILD_SLACK_MS = 1e3;
+function noteChild(s, parentID, childID) {
+  const ring = s.children.get(parentID) ?? [];
+  ring.push({ id: childID, t: Date.now() });
+  while (ring.length > CHILD_RING) ring.shift();
+  s.children.set(parentID, ring);
+}
 function bindChild(s, parentID, childID) {
+  noteChild(s, parentID, childID);
   const candidates = [...s.own.entries()].filter(([, c]) => c.s === parentID && !c.g).sort((a, b) => a[1].t - b[1].t);
   if (candidates.length === 0) return false;
   candidates[0][1].g = childID;
@@ -490,8 +537,29 @@ function bindChild(s, parentID, childID) {
   publish(s);
   return true;
 }
+function backfillChild(s, claim) {
+  if (claim.g || !claim.s) return false;
+  const now = Date.now();
+  const taken = new Set([...s.own.values()].map((c) => c.g).filter((g) => typeof g === "string"));
+  const ring = s.children.get(claim.s) ?? [];
+  for (let i = ring.length - 1; i >= 0; i--) {
+    const child = ring[i];
+    if (now - child.t > CHILD_MEMORY_MS) break;
+    if (child.t < claim.t - CHILD_SLACK_MS) continue;
+    if (taken.has(child.id)) continue;
+    claim.g = child.id;
+    s.activity.set(child.id, now);
+    publish(s);
+    return true;
+  }
+  return false;
+}
 function noteActivity(s, sessionID) {
-  s.activity.set(sessionID, Date.now());
+  const now = Date.now();
+  s.activity.set(sessionID, now);
+  let touched = false;
+  for (const claim of s.own.values()) if (claim.g === sessionID) claim.hb = now, touched = true;
+  if (touched) publish(s);
 }
 function idleFor(s, claim, now) {
   const target = claim.g;
@@ -1342,6 +1410,7 @@ import { tool } from "@opencode-ai/plugin";
 var SERVICE = "agent-pool";
 var REAP_INTERVAL_MS = 3e4;
 var HANG_FALLBACK_MS = 10 * 60 * 1e3;
+var ABORT_TIMEOUT_MS = 1e4;
 var agentPoolHooks = (async ({ client, serverUrl }, options) => {
   const opts = options ?? {};
   const s = state(opts);
@@ -1355,14 +1424,28 @@ var agentPoolHooks = (async ({ client, serverUrl }, options) => {
   };
   init(s, (m) => void warnOnce(m));
   const abortSession = async (sessionID) => {
-    if (!serverUrl) return false;
+    if (!serverUrl) return { ok: false, why: "no serverUrl: this process has no HTTP server to abort through" };
     try {
-      await fetch(new URL(`/session/${sessionID}/abort`, serverUrl).toString(), { method: "POST" });
-      return true;
-    } catch {
-      return false;
+      const res = await fetch(new URL(`/session/${sessionID}/abort`, serverUrl).toString(), {
+        method: "POST",
+        signal: AbortSignal.timeout(ABORT_TIMEOUT_MS)
+      });
+      if (!res.ok) return { ok: false, why: `gateway answered HTTP ${res.status}` };
+      const body = (await res.text()).trim();
+      if (body === "false") return { ok: false, why: "server reported the session was not aborted" };
+      return { ok: true, why: "" };
+    } catch (error) {
+      return { ok: false, why: String(error) };
     }
   };
+  const MAX_ABORT_ATTEMPTS = 3;
+  const coolForHang = async (claim, log2) => {
+    const now = Date.now();
+    const prior = s.cooling.get(claim.m);
+    if (prior && prior.until > now) return;
+    const strike = recordStrike(s, claim.m, "hang", HANG_FALLBACK_MS);
+    if (strike) await log2("warn", `cooling ${claim.m} for ${Math.round((strike.until - now) / 1e3)}s (hang)`);
+  };
   const reapStuck = async () => {
     if (s.reaping) return;
     s.reaping = true;
@@ -1370,21 +1453,53 @@ var agentPoolHooks = (async ({ client, serverUrl }, options) => {
     try {
       const stuck = findStuck(s);
       if (stuck.length === 0) return;
-      releaseStuck(s, stuck.map((x) => x.key));
-      for (const { claim } of stuck) {
-        const killed = claim.g ? await abortSession(claim.g) : false;
+      const released = [];
+      for (const { key, claim } of stuck) {
+        if (!claim.g) backfillChild(s, claim);
+        const idle = idleFor(s, claim, Date.now());
+        const since = Number.isFinite(idle) ? `${Math.round(idle / 1e3)}s of silence` : "no child session ever bound";
+        const age = Math.round((Date.now() - claim.t) / 1e3);
+        if (claim.g) {
+          const kill = await abortSession(claim.g);
+          if (kill.ok) {
+            released.push(key);
+            s.reaped++;
+            await log(
+              "warn",
+              `hung ${claim.v} on ${claim.m} after ${age}s with ${since}; aborted session ${claim.g}`,
+              { base: claim.v, model: claim.m, slot: claim.k, session: claim.g, aborted: true }
+            );
+            await coolForHang(claim, log);
+            continue;
+          }
+          claim.n = (claim.n ?? 0) + 1;
+          if (claim.n < MAX_ABORT_ATTEMPTS) {
+            await log(
+              "warn",
+              `could not abort hung ${claim.v} session ${claim.g} on ${claim.m} (${kill.why}); claim held, retry ${claim.n}/${MAX_ABORT_ATTEMPTS}`,
+              { base: claim.v, model: claim.m, slot: claim.k, session: claim.g, aborted: false }
+            );
+            continue;
+          }
+          released.push(key);
+          s.reaped++;
+          await log(
+            "error",
+            `GIVING UP on hung ${claim.v} session ${claim.g} on ${claim.m}: ${kill.why} after ${claim.n} attempts. The claim is released but the session is still running and must be killed by hand.`,
+            { base: claim.v, model: claim.m, slot: claim.k, session: claim.g, aborted: false }
+          );
+          continue;
+        }
+        released.push(key);
         s.reaped++;
-        await log(
-          "warn",
-          `hung ${claim.v} on ${claim.m} after ${Math.round((Date.now() - claim.t) / 1e3)}s with ${Math.round(idleFor(s, claim, Date.now()) / 1e3)}s of silence; ${killed ? `aborted session ${claim.g}` : "no session to abort"}`,
-          { base: claim.v, model: claim.m, slot: claim.k, session: claim.g, aborted: killed }
-        );
-        const now = Date.now();
-        const prior = s.cooling.get(claim.m);
-        if (prior && prior.until > now) continue;
-        const strike = recordStrike(s, claim.m, "hang", HANG_FALLBACK_MS);
-        if (strike) await log("warn", `cooling ${claim.m} for ${Math.round((strike.until - now) / 1e3)}s (hang)`);
+        await log("warn", `released unbound ${claim.v} claim on ${claim.m} after ${age}s (${since}); model not cooled`, {
+          base: claim.v,
+          model: claim.m,
+          slot: claim.k,
+          aborted: false
+        });
       }
+      if (released.length > 0) releaseStuck(s, released);
     } catch (error) {
       await log("error", `reaper failed: ${String(error)}`);
     } finally {
@@ -1549,7 +1664,7 @@ var agentPoolHooks = (async ({ client, serverUrl }, options) => {
           };
           for (const claim of snap.own.values()) add(claim.m, claim.v);
           for (const sibling of snap.siblings) for (const claim of sibling.claims) add(claim.m, claim.v);
-          const next = pickSlot(s, snap);
+          const next = pickSlot(s, snap, { advance: false });
           const line = (slot) => {
             const entry = byModel.get(slot.model);
             const users = entry && entry.bases.size > 0 ? [...entry.bases].map(([b, n]) => `${b}x${n}`).join(" ") : "idle";
@@ -1571,7 +1686,7 @@ var agentPoolHooks = (async ({ client, serverUrl }, options) => {
             title: `agent-pool: ${total} task(s) in flight, ${coolingNow.length} model(s) cooling`,
             output: [
               `shared pool over ${slots.length} model(s) from ${s.origin}; bases: ${BASES.join(", ")}
-priority is weight: the heaviest slot under its ceiling takes the next spawn (FULL = at ceiling, used only when every slot is)`,
+round robin in slot order, each slot taking as many turns as its weight says, so no slot is starved while another drains (FULL = at ceiling, used only when every slot is)`,
               ...slots.map(line),
               "",
               "by process:",

package/dist/pool.js

@@ -243,6 +243,7 @@ function state(opts = {}) {
       cooling: /* @__PURE__ */ new Map(),
       strikes: /* @__PURE__ */ new Map(),
       activity: /* @__PURE__ */ new Map(),
+      children: /* @__PURE__ */ new Map(),
       reaped: 0,
       reaping: false,
       lastSweep: 0,
@@ -284,7 +285,7 @@ function init(s, onWarn) {
 }
 function pruneOwn(s) {
   const now = Date.now();
-  for (const [key, claim] of s.own) if (now - claim.t > CLAIM_TTL_MS) s.own.delete(key);
+  for (const [key, claim] of s.own) if (now - (claim.hb ?? claim.t) > CLAIM_TTL_MS) s.own.delete(key);
 }
 function publish(s) {
   if (!s.dirReady) return;
@@ -349,7 +350,7 @@ function readSiblings(s) {
     try {
       const parsed = JSON.parse(readFileSync2(path, "utf8"));
       const claims = Object.values(parsed).filter(
-        (c) => c && typeof c.v === "string" && typeof c.m === "string" && now - c.t <= CLAIM_TTL_MS
+        (c) => c && typeof c.v === "string" && typeof c.m === "string" && now - (c.hb ?? c.t) <= CLAIM_TTL_MS
       );
       siblings.push({ id: match[1], claims });
     } catch {
@@ -463,26 +464,72 @@ function snapshot(s) {
 }
 var loadOf = (counts, model) => counts.get(model) ?? 0;
 var underCeiling = (slot, counts) => loadOf(counts, slot.model) < slot.weight;
-function pickSlot(s, snap) {
+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 {
+  }
+  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 {
+  }
+}
+function pickSlot(s, snap, options) {
+  const advance = options?.advance !== false;
   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;
-  const open = pool.filter((slot) => underCeiling(slot, snap.counts));
-  if (open.length > 0) return open.reduce((best, slot) => slot.weight > best.weight ? slot : best, open[0]);
   return pool.reduce((best, slot) => loadOf(snap.counts, slot.model) < loadOf(snap.counts, best.model) ? slot : best, pool[0]);
 }
 function agentFor(base, slot) {
   return `${base}-${slot}`;
 }
 function acquire(s, base, slot, ownerSession, key, target) {
-  s.own.set(key, { v: base, k: slot.index, m: slot.model, t: Date.now(), s: ownerSession, g: target });
-  if (target) s.activity.set(target, Date.now());
+  const now = Date.now();
+  s.own.set(key, { v: base, k: slot.index, m: slot.model, t: now, hb: now, s: ownerSession, g: target });
+  if (target) s.activity.set(target, now);
   publish(s);
 }
 function release(s, key) {
   if (s.own.delete(key)) publish(s);
 }
+var CHILD_RING = 8;
+var CHILD_MEMORY_MS = 30 * 6e4;
+var CHILD_SLACK_MS = 1e3;
+function noteChild(s, parentID, childID) {
+  const ring = s.children.get(parentID) ?? [];
+  ring.push({ id: childID, t: Date.now() });
+  while (ring.length > CHILD_RING) ring.shift();
+  s.children.set(parentID, ring);
+}
 function bindChild(s, parentID, childID) {
+  noteChild(s, parentID, childID);
   const candidates = [...s.own.entries()].filter(([, c]) => c.s === parentID && !c.g).sort((a, b) => a[1].t - b[1].t);
   if (candidates.length === 0) return false;
   candidates[0][1].g = childID;
@@ -490,8 +537,29 @@ function bindChild(s, parentID, childID) {
   publish(s);
   return true;
 }
+function backfillChild(s, claim) {
+  if (claim.g || !claim.s) return false;
+  const now = Date.now();
+  const taken = new Set([...s.own.values()].map((c) => c.g).filter((g) => typeof g === "string"));
+  const ring = s.children.get(claim.s) ?? [];
+  for (let i = ring.length - 1; i >= 0; i--) {
+    const child = ring[i];
+    if (now - child.t > CHILD_MEMORY_MS) break;
+    if (child.t < claim.t - CHILD_SLACK_MS) continue;
+    if (taken.has(child.id)) continue;
+    claim.g = child.id;
+    s.activity.set(child.id, now);
+    publish(s);
+    return true;
+  }
+  return false;
+}
 function noteActivity(s, sessionID) {
-  s.activity.set(sessionID, Date.now());
+  const now = Date.now();
+  s.activity.set(sessionID, now);
+  let touched = false;
+  for (const claim of s.own.values()) if (claim.g === sessionID) claim.hb = now, touched = true;
+  if (touched) publish(s);
 }
 function idleFor(s, claim, now) {
   const target = claim.g;
@@ -555,6 +623,7 @@ export {
   USER_MODELS_TXT,
   acquire,
   agentFor,
+  backfillChild,
   bindChild,
   claimKey,
   coolProvider,
@@ -585,6 +654,7 @@ export {
   releaseStuck,
   resolveModels,
   retryAfterMs,
+  roundRobinSequence,
   selfFile,
   slotFor,
   snapshot,

package/docs/USER-STORIES.md

@@ -96,13 +96,13 @@ 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 preference drains preferred providers first
-**As a** user, **I want** to express preference between models via weights, **so that** the pool prefers the cheapest/freest provider up to its ceiling.
+### 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.
 
 **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 heavier slot is filled before the lighter one.
-- [ ] Given a slot is at its weight ceiling, When another spawn is routed, Then the pick moves to the next slot under its ceiling.
+- [ ] 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 weight ceiling 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 weight ceiling except by overflow.
@@ -115,7 +115,7 @@ 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 marked as the slot the next spawn would take.
+- [ ] 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.
 
 ### 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawaty/lacode",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",

package/presets/README.md

@@ -62,7 +62,7 @@ else means the flat form.
 | Field | Required | Meaning |
 |-------|----------|---------|
 | `model` | yes | `provider/model-id`, split on the **first** slash only |
-| `weight` | no | soft ceiling on concurrent claims, and priority. Absent = 1 |
+| `weight` | no | soft ceiling on concurrent claims, and turns taken per rotation. 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.
@@ -91,17 +91,28 @@ because the pool requires it.
 
 ## Weight, precisely
 
-A weight is a count of concurrent sessions, used as both a ceiling and a
-priority:
+A weight is a count of concurrent sessions — a soft ceiling — and the number
+of turns a slot takes per rotation. Routing is **order-first weighted
+round-robin**:
 
-1. the **highest-weight** slot still under its own ceiling takes the next spawn
-2. so slot 1 fills to its number before slot 2 sees any work at all
+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
-tie-break, so put the models you want busiest first and treat the bottom of the
-list as reserve capacity.
+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.
 
 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

@@ -14,20 +14,34 @@
     "route at an agent that does not exist. Extra entries are dropped with a warning.",
     "",
     "WEIGHT IS THE ONLY KNOWN KNOB, and it is a SOFT CEILING on how many concurrent claims a",
-    "slot holds -- not a share of the work. Priority is that same number, so the rule is:",
-    "  1. the HIGHEST-weight slot that is still under its ceiling takes the spawn",
-    "  2. slot 1 therefore fills to its number before slot 2 sees any work at all",
+    "slot holds -- not a share of the work and 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",
     "",
-    "With this file: space-bunny takes 3 sessions to itself, then step-5-preview",
+    "With this file: space-bunny takes 3 consecutive turns, then step-5-preview",
     "(opencode-go) takes 2, then big-pickle and step-5-preview (Zen) 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.",
     "",
+    "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.",
+    "",
     "Absent means weight 1. Must be a number in (0, 100]; anything else warns and uses 1.",
-    "List order is the tie-break between slots of equal weight, so put the ones you want",
-    "first and treat the bottom of the list as the reserve.",
+    "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.",
     "",
     "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.",