@lawaty/lacode 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,168 @@
+# Changelog
+
+All notable changes to LaCode are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and releases follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Versions come from git release commits; the npm version is bumped in the same
+commit as the changelog entry it describes.
+
+## [Unreleased]
+
+## [0.4.1] — refuse hand-named slot variants, and ship a changelog
+
+### Added
+
+- `CHANGELOG.md`, reconstructing all 13 published releases from their commits. It
+  ships with the package, so an install can read what changed without the repo.
+
+### Changed
+
+- A pool slot variant named by hand (`explore-1`, `implement-2`, …) is now
+  **refused** rather than counted. Naming one skipped both the round-robin
+  rotation and the slot's ceiling, so six spawns of `explore-1` put six
+  concurrent claims on a slot bounded at three. The refusal names the bare base
+  to spawn instead, is logged, and escapes the routing catch — swallowed into
+  "spawn unchanged" it would have admitted the spawn it forbids.
+- Agent prompts dropped the long explanation of why a variant must not be named.
+  It is enforced now, and the refusal carries the reason; the prompts keep only
+  the bare-base rule and what to do on refusal. 1,012 characters removed across
+  the `build`, `plan` and `explore` prompts.
+
+### Documented
+
+- `isAvailable` and `pickSlot` now say, in place, that the pool is deliberately
+  fail-open in two places: a model absent from the catalog is not treated as
+  unavailable, and when every slot is cooling they are re-admitted rather than
+  the work refused. Both were previously only discoverable by reading the code.
+
+## [0.4.0] — order-first weighted round-robin, and a reaper that can kill
+
+### Changed
+
+- **Slot selection is now order-first weighted round-robin.** Weight was both
+  the priority and the ceiling, so the heaviest slot was re-prioritised on every
+  spawn and refilled the moment a claim completed, while the others sat idle.
+  Selection walks the slot list in order, each slot taking as many turns as its
+  weight says, from a cursor persisted in the pool directory so the rotation is
+  shared by every opencode process rather than restarting in each one. Weights
+  `[3,2,1,1]` now produce the run `1,1,1,2,2,3,4`.
+- The concurrency ceiling is unchanged: a slot still holds at most `weight`
+  concurrent claims, and overflow still goes to the least-loaded slot.
+- `pool_status` previews the next slot without advancing the rotation, so
+  looking at the pool no longer shifts every spawn after it.
+
+### Fixed
+
+- **A hung subagent could not be killed.** The reaper detected the wedge, freed
+  the claim, and then failed to abort the session — because the claim was
+  released *before* the abort, so a failed kill orphaned the session with
+  nothing left to retry it. Kills are verified against the response, retried
+  three times, and only a confirmed kill releases the claim; a give-up names
+  the session to kill by hand.
+- A kill reported success for any HTTP response, including the gateway's
+  `200` with body `true` for a session that does not exist.
+- A claim that never bound to a child session was logged as `Infinitys of
+  silence` and cooled the provider, though an unbound claim is no evidence that
+  anything hung. It is now released without cooling, and a child created before
+  its claim is bound at reap time instead of being lost.
+- **A live task lost its slot past the TTL.** Claims now carry a heartbeat
+  refreshed by message activity, and abandonment is measured from it. A task
+  that ran past the 10-minute TTL previously stopped being counted while it
+  kept working, so the slot was handed out again — a ceiling-3 slot ran five.
+
+## [0.3.0] — a sound per notification outcome (US-29)
+
+### Changed
+
+- Notification outcomes are per-notification and sound, rather than one silent
+  aggregate.
+
+## [0.2.2] — stop capping gateway traffic at 5s
+
+### Fixed
+
+- `timeoutMs` no longer caps real provider traffic at 5s. It was documented as
+  a probe budget only, but it was being applied to live completions too.
+
+## [0.2.1] — OmniRoute registers the provider only
+
+### Changed
+
+- The OmniRoute integration registers the provider and nothing else; it writes
+  no pool file and no variants.
+
+## [0.2.0] — OmniRoute as the pool's primary slot
+
+### Added
+
+- OmniRoute, a local OpenAI-compatible gateway, as the pool's primary slot, with
+  combo routing, sticky sessions and cooldown on usage limits.
+
+## [0.1.10] — observable self-update outcome
+
+### Changed
+
+- The self-update reports its outcome instead of failing silently.
+
+## [0.1.9] — reclaim update locks orphaned by a dead process
+
+### Fixed
+
+- An update lock left behind by a dead process is reclaimed rather than blocking
+  every later update.
+
+## [0.1.7] — self-update, hermetic tests
+
+### Added
+
+- Self-update on restart, and a hermetic test suite that does not read the
+  developer's own `~/.config`.
+
+## [0.1.6] — small implement asks, Step 5 Preview pool
+
+### Changed
+
+- Implementation asks are split into smaller units.
+- `opencode-go/step-5-preview-free` added to the bundled pool preset.
+
+## [0.1.5] — build/plan may spawn basic and expert
+
+### Changed
+
+- `build` and `plan` may spawn `basic` and `expert`, which are not pooled.
+
+## [0.1.4] — flat pool.txt
+
+### Changed
+
+- The pool's user config is a flat `~/.config/lacode/pool.txt`, one model per
+  line with an optional weight.
+
+## [0.1.3] — ship the updated notification/remote docs
+
+### Changed
+
+- Notification and remote-control documentation brought up to date.
+
+## [0.1.1]
+
+### Added
+
+- First published release: pooled subagents over a shared set of models.
+
+[Unreleased]: https://github.com/lawaty/lacode/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/lawaty/lacode/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/lawaty/lacode/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/lawaty/lacode/compare/v0.2.2...v0.3.0
+[0.2.2]: https://github.com/lawaty/lacode/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/lawaty/lacode/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/lawaty/lacode/compare/v0.1.10...v0.2.0
+[0.1.10]: https://github.com/lawaty/lacode/compare/v0.1.9...v0.1.10
+[0.1.9]: https://github.com/lawaty/lacode/compare/v0.1.7...v0.1.9
+[0.1.7]: https://github.com/lawaty/lacode/compare/v0.1.6...v0.1.7
+[0.1.6]: https://github.com/lawaty/lacode/compare/v0.1.5...v0.1.6
+[0.1.5]: https://github.com/lawaty/lacode/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/lawaty/lacode/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/lawaty/lacode/compare/v0.1.1...v0.1.3
+[0.1.1]: https://github.com/lawaty/lacode/releases/tag/v0.1.1

package/README.md

@@ -13,6 +13,9 @@ desktop.
 Install it with one config line. It adds agents and commands it finds missing,
 and it never overwrites one you already defined.
 
+Upgrading? See [CHANGELOG.md](CHANGELOG.md) — it ships with the package, so it
+is also on disk at `node_modules/@lawaty/lacode/CHANGELOG.md`.
+
 ## Why
 
 | Capability | The problem it solves |
@@ -337,6 +340,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 +432,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.
@@ -491,8 +589,11 @@ fields are not affected; `permission`, `prompt`, `model`, `description`,
 ```
 
 The hidden pool variants (`explore-1`, `implement-2`, …) inherit
-nothing here — add a line per variant you actually spawn, or drop the global
+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
+permissions only ever apply to a spawn the plugin routed itself.
 
 Nothing hot-reloads: after editing your config, restart every running opencode
 process.
@@ -570,6 +671,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"];
@@ -72,15 +73,9 @@ Every question of the form "what does this file do", "where is X handled", or
   that proves it. Never one whole refactor handed over in a single piece \u2014
   see \`# Task size\` below.
 
-The agents you spawn are the pooled \`explore\` / \`implement\` / \`context\`
-bases. **Always spawn the BARE base name and let the plugin choose the slot;
-never name a \`-N\` variant** (\`explore-1\`..\`explore-4\`, \`implement-1\`..,
-\`context-1\`..). The plugin owns which model every pooled spawn runs on: it
-picks the next slot from the pool's weights, current load and cooldowns, and
-rewrites your spawn to that variant for you. Naming a variant bypasses that
-decision, defeats failover, and can pin work to a cooling or unhealthy model.
-If you catch yourself choosing a slot number, you are doing the plugin's job \u2014
-spawn \`explore\` and let it decide.
+Spawn the BARE pooled base \u2014 \`explore\`, \`implement\` or \`context\`. The pool
+refuses a \`-N\` variant, and a refusal means spawn the bare base, never a
+different number.
 
 # When the pool is unavailable
 
@@ -200,10 +195,8 @@ When you need to understand the codebase:
 2. Invoke @explore with specific, focused instructions (e.g. "read src/auth.ts", "grep for 'migration' in *.py files", "list the src/ directory")
 3. @explore will return its findings \u2014 you process them and plan accordingly
 
-Always spawn the BARE pooled base (\`explore\`, \`implement\`, \`context\`) and let
-the plugin choose the slot. Never name a \`-N\` variant (\`explore-1\`..\`explore-4\`);
-doing so bypasses the pool's weights, load and cooldowns, which is the one thing
-the plugin exists to decide.
+Spawn the BARE pooled base (\`explore\`, \`implement\`, \`context\`); the pool
+refuses \`-N\` variants, and a refusal means spawn the bare base, not another number.
 
 If the pool cannot serve a spawn \u2014 every slot cooling or exhausted, or repeated
 failures \u2014 do NOT fall back to reading or planning from your own inspection.

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,77 @@ 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 manualVariant(name) {
+  const direct = /^(.*)-([1-9][0-9]*)$/.exec(name);
+  if (!direct) return void 0;
+  return BASES.includes(direct[1]) ? direct[1] : void 0;
+}
 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 +542,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;
@@ -558,15 +631,9 @@ Every question of the form "what does this file do", "where is X handled", or
   that proves it. Never one whole refactor handed over in a single piece \u2014
   see \`# Task size\` below.
 
-The agents you spawn are the pooled \`explore\` / \`implement\` / \`context\`
-bases. **Always spawn the BARE base name and let the plugin choose the slot;
-never name a \`-N\` variant** (\`explore-1\`..\`explore-4\`, \`implement-1\`..,
-\`context-1\`..). The plugin owns which model every pooled spawn runs on: it
-picks the next slot from the pool's weights, current load and cooldowns, and
-rewrites your spawn to that variant for you. Naming a variant bypasses that
-decision, defeats failover, and can pin work to a cooling or unhealthy model.
-If you catch yourself choosing a slot number, you are doing the plugin's job \u2014
-spawn \`explore\` and let it decide.
+Spawn the BARE pooled base \u2014 \`explore\`, \`implement\` or \`context\`. The pool
+refuses a \`-N\` variant, and a refusal means spawn the bare base, never a
+different number.
 
 # When the pool is unavailable
 
@@ -686,10 +753,8 @@ When you need to understand the codebase:
 2. Invoke @explore with specific, focused instructions (e.g. "read src/auth.ts", "grep for 'migration' in *.py files", "list the src/ directory")
 3. @explore will return its findings \u2014 you process them and plan accordingly
 
-Always spawn the BARE pooled base (\`explore\`, \`implement\`, \`context\`) and let
-the plugin choose the slot. Never name a \`-N\` variant (\`explore-1\`..\`explore-4\`);
-doing so bypasses the pool's weights, load and cooldowns, which is the one thing
-the plugin exists to decide.
+Spawn the BARE pooled base (\`explore\`, \`implement\`, \`context\`); the pool
+refuses \`-N\` variants, and a refusal means spawn the bare base, not another number.
 
 If the pool cannot serve a spawn \u2014 every slot cooling or exhausted, or repeated
 failures \u2014 do NOT fall back to reading or planning from your own inspection.
@@ -1342,6 +1407,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 +1421,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 +1450,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 {
@@ -1494,9 +1606,19 @@ var agentPoolHooks = (async ({ client, serverUrl }, options) => {
     },
     "tool.execute.before": async (input, output) => {
       if (input.tool !== "task") return;
+      const requested = output.args?.subagent_type;
+      if (typeof requested !== "string") return;
+      const manual = manualVariant(requested);
+      if (manual) {
+        await log("warn", `refused manual spawn of slot variant ${requested}; spawn "${manual}" instead`, {
+          variant: requested,
+          base: manual
+        });
+        throw new Error(
+          `${requested} is a pool slot variant and cannot be spawned by name. Naming it lets the caller pick the provider: it skips the round-robin rotation and the slot's ceiling, so one provider takes every concurrent claim. Spawn "${manual}" and let the pool choose the slot.`
+        );
+      }
       try {
-        const requested = output.args?.subagent_type;
-        if (typeof requested !== "string") return;
         await reapStuck();
         refreshCatalog(s, serverUrl);
         const snap = snapshot(s);
@@ -1518,11 +1640,6 @@ var agentPoolHooks = (async ({ client, serverUrl }, options) => {
           });
           return;
         }
-        const direct = /^(.*)-([1-9][0-9]*)$/.exec(requested);
-        if (direct && BASES.includes(direct[1])) {
-          const slot = s.slots.find((sl) => sl.index === Number(direct[2]));
-          if (slot) acquire(s, direct[1], slot, input.sessionID, claimKey(input.sessionID, input.callID));
-        }
       } catch (error) {
         await log("error", `routing failed, spawn unchanged: ${String(error)}`);
       }
@@ -1549,7 +1666,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 +1688,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,77 @@ 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 manualVariant(name) {
+  const direct = /^(.*)-([1-9][0-9]*)$/.exec(name);
+  if (!direct) return void 0;
+  return BASES.includes(direct[1]) ? direct[1] : void 0;
+}
 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 +542,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 +628,7 @@ export {
   USER_MODELS_TXT,
   acquire,
   agentFor,
+  backfillChild,
   bindChild,
   claimKey,
   coolProvider,
@@ -568,6 +642,7 @@ export {
   isLimitText,
   isQuotaReason,
   isUnavailableText,
+  manualVariant,
   noteActivity,
   parseSlotText,
   parseSlots,
@@ -585,6 +660,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.1",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",
@@ -45,6 +45,7 @@
     "presets",
     "sounds",
     "LICENSE",
+    "CHANGELOG.md",
     "README.md",
     "docs"
   ],

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.",