@lawaty/lacode 0.2.2 → 0.4.0

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.
@@ -222,6 +222,18 @@ does not.
 - [ ] Given the plugin observes a permission prompt, When it handles the event, Then it is a read-only observer: the payload is not mutated and no `permission.ask` hook is registered, because that hook's `output.status` is the permission decision itself.
 - [ ] Given a `permission` notification is raised, When it is evaluated against the cooldown, Then it bypasses it, since an unannounced block is the failure this story exists to remove.
 
+### US-29: Notification sounds distinguish outcomes and can be switched off
+**As a** user running many parallel sessions, **I want** each notification to arrive with its own sound, **so that** I can tell a finished session from a question or a permission prompt without looking at the popup.
+
+**Story ID(s) for tests:** US-29
+**Acceptance criteria:**
+- [ ] Given any of the four outcomes, When its notification is delivered, Then it carries that outcome's own sound name — `done`, `question`, `permission` or `error` — and no two share one, so the four are distinguishable by ear alone.
+- [ ] Given a notification raised on a remote host, When it reaches the desktop, Then the sound plays where the notification is delivered and never on the opencode host, because a headless host has no speakers for you to hear.
+- [ ] Given no sound player is installed, or the player cannot start, When the notification is delivered, Then the notification is delivered unchanged and only the sound is skipped, because a missing audio tool must never cost you the alert itself.
+- [ ] Given a machine with no notification channel at all, When a notification is raised, Then its sound still plays, because on such a desktop the tone is the only alert there is.
+- [ ] Given the plugin option `sound` is `false`, or `LACODE_SOUND` is `0`, `false`, `off` or `no`, When a notification is delivered, Then its sound is `none`; when both are set the environment wins over the option, and any other value — a typo included — leaves sound on, because a misspelt variable must not be how you get silence.
+- [ ] Given a sound name that is not one of `none`, `done`, `question`, `permission` or `error`, When it arrives, Then it is treated as `none` and never becomes a path or a command, because the hop carries data only (see US-18).
+
 ---
 
 ## Epic E — Remote hosts over SSH
@@ -431,6 +443,7 @@ table was filled in.
 | US-11 | D | `tests/stories/d-notifications.test.mjs`, `tests/notify-test.mjs` |
 | US-12 | D | `tests/stories/d-notifications.test.mjs`, `tests/notify-test.mjs` |
 | US-25 | D | `tests/stories/d-notifications.test.mjs` |
+| US-29 | D | `tests/stories/d-notifications.test.mjs` |
 | US-13 | E | `tests/stories/e-remote-ssh.test.mjs`, `tests/notify-test.mjs`, `tests/oc-test.mjs` |
 | US-14 | E | `tests/stories/e-remote-ssh.test.mjs`, `tests/oc-test.mjs` |
 | US-18 | E | `tests/stories/e-remote-ssh.test.mjs`, `tests/oc-test.mjs` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawaty/lacode",
-  "version": "0.2.2",
+  "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",
@@ -43,6 +43,7 @@
   "files": [
     "dist",
     "presets",
+    "sounds",
     "LICENSE",
     "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.",