@lawaty/lacode 0.10.0 → 1.0.0

package/docs/USER-STORIES.md

@@ -15,11 +15,7 @@ line. Criteria that cannot be observed without a running server are not in this
 document; everything here is testable offline with a stub client and a
 `mkdtempSync` state directory.
 
-**Terminology.** A *slot* is one entry in `presets/free-tier.json`, carrying a
-model and a `weight`. A *base* is a pooled agent type (`explore`), and its slot
-holders are `<base>-<slot>`, hidden in `opencode.jsonc`. A *claim* is a running
-spawn recorded in `claims.<pid>.json`. A *context map* is the five-file
-`.opencode/context/` codemap described in Epic G.
+**Terminology.** A *slot* is one entry in `presets/free-tier.json`, carrying a model and a `weight`. A slot's `weight` is its active-session budget for one pass: the number of concurrent claims it may hold before the next slot is preferred. A *pass* is one declaration-order sweep of the slot list; the pool runs at most two passes, and a slot's absolute cap is twice its weight. Preference is by declaration order, never by weight. A *base* is a pooled agent type (`explore`), and its slot holders are `<base>-<slot>`, hidden in `opencode.jsonc`. A *claim* is a running spawn recorded in `claims.<pid>.json`. A *context map* is the five-file `.opencode/context/` codemap described in Epic G.
 
 ---
 
@@ -96,16 +92,18 @@ The reconciliation with US-7 is that **acceptance and endorsement are different
 - [ ] Given every model is cooling, When a spawn is routed, Then the least-loaded slot is chosen anyway (degrade, never block).
 - [ ] Given a limit error names a reset time, When the cooldown is recorded, Then the stated reset is used instead of a guessed backoff.
 
-### US-5: Weighted round-robin gives every slot a turn per cycle
-**As a** user, **I want** weights to say how many turns each slot takes per rotation cycle, **so that** no provider is drained to its limit while the others sit idle.
+### US-5: Slots fill in declaration order, in up to two passes
+**As a** user, **I want** work to prefer the first slot and spill to later slots only when the earlier ones are full, **so that** a healthy preferred model is used before fallbacks and no slot is used while an earlier usable slot has room.
 
 **Story ID(s) for tests:** US-5
 **Acceptance criteria:**
-- [ ] Given a heavy slot and a light slot, When spawns are routed below both ceilings, Then the rotation walks the list in order with each slot taking as many consecutive turns as its weight says, rather than the heavy slot being filled and refilled first.
-- [ ] Given a slot is at its ceiling (twice its weight) or cooling, When its turn comes up in the rotation, Then the turn is skipped and the rotation resumes at the following turn.
-- [ ] Given every slot is at its ceiling, When another spawn is routed, Then it goes to the least-loaded slot as overflow.
-- [ ] Given all slots carry equal weight, When spawns are routed, Then the picks round-robin in declaration order.
-- [ ] Given per-slot load is read, When it is asserted, Then a slot's load never exceeds its ceiling (twice its weight) except by overflow.
+- [ ] Given live claims, When the pool has room in the first pass, Then the lowest-index usable slot whose load is below its weight is chosen, and a slot declared later is not used until every earlier usable slot has reached its weight.
+- [ ] Given every usable slot has reached its weight, When another spawn is routed, Then the second pass begins at the lowest-index slot and fills each usable slot up to twice its weight.
+- [ ] Given a slot is cooling or unavailable, When its position in the pass comes up, Then it is skipped and the pass continues to the next slot.
+- [ ] Given a claim is released, When the next spawn is routed, Then the slot that freed capacity is preferred again in declaration order; no stored position keeps it waiting.
+- [ ] Given every usable slot is at its absolute cap, When another spawn is routed, Then it goes to the least-loaded usable slot as overflow, and the pool never refuses work.
+- [ ] Given all slots carry equal weight, When spawns are routed, Then the same ordered two-pass fill applies.
+- [ ] Given per-slot load is read, When it is asserted, Then a slot's load never exceeds twice its weight except through overflow.
 
 ### US-6: Live pool visibility
 **As a** user, **I want** to see per-slot load and which model is cooling and why, **so that** I understand where my subagents are going.
@@ -115,7 +113,8 @@ The reconciliation with US-7 is that **acceptance and endorsement are different
 - [ ] Given claims are held by several processes, When the status view is requested, Then it shows every process's claims and the aggregate load per slot.
 - [ ] Given a model is cooling with a stated reason, When the status view is requested, Then the model is listed as cooling together with that reason.
 - [ ] Given a claim file is older than the dead-file threshold, When the status view is computed, Then the stale claim is pruned rather than counted.
-- [ ] Given a slot is at its ceiling, When the status view is requested, Then it is not marked as the slot the next spawn would take, because the rotation's turns are skipped for a full slot until it frees a claim.
+- [ ] Given a slot is at its absolute cap, When the status view is requested, Then it is not marked as the slot the next spawn would take while any usable slot is below its current pass target; when every usable slot is at its absolute cap, the least-loaded slot is marked next.
+- [ ] Given the pool is filling, When the status view is requested, Then it shows whether the next spawn belongs to the first pass, the second pass, or overflow.
 
 ### US-7: Non-free models still work
 **As a** user who wants a paid model in the pool, **I want** to supply any model list, **so that** the pool is not restricted to free tiers.
@@ -151,6 +150,23 @@ does not.
 - [ ] Given OmniRoute is disabled, enabled with an invalid block, unhealthy, or returns no usable models, When the config hook runs, Then no provider is registered, no pool slot changes, and a failure is warned about once.
 - [ ] Given the gateway is unreachable, When pooled work runs, Then the only thing affected is a slot that names `omniroute/<model>`; every other slot keeps working, because the plugin never put an `omniroute` slot in the pool.
 
+### US-31: A limit that hangs is killed, and the retry lands on a slot that answers
+**As a** user whose provider has run out of allowance, **I want** the stalled task killed and the retry sent to a slot that is not on cooldown, **so that** one exhausted provider does not strand the session.
+
+A limit does not always arrive as an error. Sometimes the provider accepts the request and then says nothing, and opencode keeps retrying the refused model — so the task is neither done nor failed, and the session waits on a provider that has already said no. The plugin has to end that wait itself: abort the stalled session, cool the model that was refused, and let the retry pick a slot that answers. When the provider names itself, the whole provider is benched; when it does not, only the model the session was running on is cooled — that is the one the refusal is evidence about.
+
+**Story ID(s) for tests:** US-31
+**Acceptance criteria:**
+- [ ] Given a pooled session's provider reports a limit in a retry status that names no provider, When the status is handled, Then the model that session is running on is cooled and a cooldown file is written for it.
+- [ ] Given a pooled session reports a limit and then goes silent, When the limit is handled, Then that session is aborted and its claim is released, so the slot is not held by a task that will never answer.
+- [ ] Given the refused model is cooling, When the caller retries the spawn, Then the retry is routed to a different slot whose model is not on cooldown.
+- [ ] Given a limit names its provider, When the limit is handled, Then every slot on that provider is cooled and a slot on another provider is not.
+- [ ] Given a limit-shaped error whose text is exactly `limit reached` and which carries no status code, When the error is matched, Then the model is cooled and the in-flight session is aborted.
+- [ ] Given an error whose text is `context limit reached`, When the error is matched, Then nothing is cooled and nothing is aborted, because a prompt that is too long is not a provider quota.
+- [ ] Given a session stalls with no limit signal at all, When the reaper sweeps, Then the session is aborted, its model cooled, and the next spawn routes to a slot that is not on cooldown.
+- [ ] Given a provider reports a transient upstream outage rather than a limit, When the status is handled, Then the model is cooled for one short flat window instead of the quota window, and the session is still aborted, because an outage lifts on its own and must not bench a healthy model.
+- [ ] Given a transient outage was cooled, When the same model later fails with a real limit, Then the cooldown starts at the first strike rather than an escalated one, because an outage lifts on its own and must not make the next quota window longer.
+
 ---
 
 ## Epic C — Hang detection and auto-recovery
@@ -240,6 +256,22 @@ does not.
 - [ ] 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).
 
+### US-30: A notification fades once you are working in that chat
+**As a** user with several sessions open, **I want** the popup of the session I am working in to close itself, **so that** a notice I have already dealt with stops sitting on my screen waiting for an X I was never going to press.
+
+A popup the user is already looking past has said everything it is going to say: once they answer the permission, answer the question, or type into that session's chat, the answer is on their screen already. So the popup fades on its own — but never sooner than five seconds after it was raised, because a notice nobody could read is no notice, and a popup nobody touched still waits for them, exactly as before.
+
+The popup belongs to its session: working in one chat closes that chat's popup and no other. The close is the **helper's** job, never the plugin's, because the popup lives on the desktop and only the desktop knows the notification id the daemon gave it. One code path, two topologies: the helper closes locally, or over the hop where the popup was actually raised.
+
+**Story ID(s) for tests:** US-30
+**Acceptance criteria:**
+- [ ] Given a notification has been delivered, When the user answers a permission, answers a question, or types into that session's chat, Then that session's notification closes by itself, without the user clicking the popup's close button.
+- [ ] Given a notification was delivered less than five seconds ago, When the user works in that chat, Then the notification stays until five seconds have passed, because a notice nobody could read is no notice.
+- [ ] Given the user works in one session's chat, When another session still has a popup up, Then that popup stays: a notification belongs to its session, and only that session's user is looking at it.
+- [ ] Given the user never works in that chat, When the notification was delivered, Then it stays until the user closes it, exactly as before.
+- [ ] Given a permission popup is closed this way, When the permission was already answered in the terminal, Then nothing is answered twice: the close takes the popup down and answers nothing.
+- [ ] Given the notification was delivered by a session on a remote host and reached the desktop over the tunnel, When the user works in that chat, Then the popup on the desktop closes too, because the popup lives on the desktop and only the desktop knows its notification id.
+
 ---
 
 ## Epic E — Remote hosts over SSH
@@ -287,7 +319,7 @@ does not.
 - [ ] Given a body containing `"`, `'`, `;`, `$(…)` or backticks, When the macOS send runs, Then it reaches `display notification` byte-for-byte as data and nothing is executed.
 - [ ] Given a machine has no notifier for its platform, When a notification is sent, Then the result is a failed delivery with a reason and no exception, and `lacode doctor` names the channel that would run — or reports that there is none — instead of reporting a binary that is not used there.
 - [ ] Given the CLI runs on macOS, When the send does not complete, Then it is still bounded by a timeout, exactly as on Linux.
-- [ ] Given the notification hop, When it is documented, Then the doc leads with the shipped path — the npm-installed plugin, a direct ssh hop (`ControlMaster`) set up by `lacode tunnel setup`, and the portable `lacode receive` forced command that delivers through the platform channel (`notify-send` or `osascript`) — and marks the reverse-forward scripts (`bin/oc`, `bin/oc-notify`, `bin/oc-notify-receiver`, `bin/oc-sync`) as the author's legacy tooling, so a Mac user is not sent to debug a script that was never meant to run on their machine.
+- [ ] Given the notification hop, When it is documented, Then the doc leads with the shipped path — the npm-installed plugin, a direct ssh hop (`ControlMaster`) set up by `lacode tunnel setup`, and the portable `lacode receive` forced command that delivers through the platform channel (`notify-send` or `osascript`) — and marks the reverse-forward scripts (`bin/oc`, `bin/oc-notify`, `bin/oc-notify-receiver`, `bin/oc-sync`) as the author's own scripts, so a Mac user is not sent to debug a script that was never meant to run on their machine.
 - [ ] Given a machine without GNU `timeout` or with bash older than 4.0, When `bin/oc-sync` runs, Then it refuses **before** touching anything, names each missing prerequisite, and names the `lacode` subcommand to use instead. It must never report a misleading cause: the host list is read with `mapfile`, so without it the run dies at "no hosts configured" — a confident wrong answer that sends the reader to edit `.env`.
 - [ ] Given `bin/oc-notify-receiver` runs where `notify-send` does not exist, When it is invoked, Then it exits non-zero and names both the missing channel and the portable path, because its stderr reaches whoever opened the ssh connection and nobody else, and a bare "command not found" reads as a desktop that quietly stopped notifying.
 - [ ] Given the payload is parsed, When the receiver splits `$SSH_ORIGINAL_COMMAND`, Then it splits on newlines only using constructs that exist in bash 3.2 as well as bash 5, and the suite **proves the split by running the receiver** rather than by finding the word `mapfile` in the file. Under bash 3.2 — the version macOS ships — a bash-4-only builtin leaves every field at its default, so the popup says "LaCode" with an empty body and no error anywhere: the same silent blank notification the argv bug causes, reached through a different door.
@@ -380,7 +412,7 @@ agents read it before they explore, then keeps it current on its own.
 **Acceptance criteria:**
 - [ ] Given a config that defines none of LaCode's agents, When the config hook runs, Then a `context` subagent is injected, and it carries no model of its own, because the pool is the only thing that decides which model runs it.
 - [ ] Given the injected agent set, When the slot variants are built, Then a hidden `context-<slot>` variant exists for every slot the pool can hand out, so a cartography run borrows shared capacity instead of a dedicated model.
-- [ ] Given a user config with no `instructions` array, When the config hook runs, Then the standing context-map rule is injected, naming all five map files, telling the agent to check with `ls` and never the `glob` tool, to read only the file relevant to the task, and to start from the canonical entry points the map lists.
+- [ ] Given the shipped agent prompts and the context agent, When they are inspected, Then they carry the standing context-map rule — naming all five map files, checking with `ls` and never the `glob` tool, reading only the file relevant to the task, and starting from the canonical entry points the map lists — because that rule now lives in the repo-level `AGENTS.md` rather than being injected into the user's `instructions` array.
 - [ ] Given the injected `context`, When its prompt is inspected, Then it names the five files it owns, requires a short "Start here" list of canonical files per significant subsystem, and forbids file inventories — the map answers "what should I look at first?", never "tell me everything".
 
 ### US-20: The map stays current without being asked
@@ -424,10 +456,49 @@ Enforcement is split deliberately, and the split matters: **what the permission
 
 ---
 
+## Epic H — Retention (sweeps)
+
+### US-32: Retire old sessions
+**As an** opencode user whose session list only ever grows, **I want** a sweep that retires sessions past a retention window together with everything that belongs to them, **so that** the database stays usable and I keep a compact record of what went.
+
+**Story ID(s) for tests:** US-32
+**Acceptance criteria:**
+- [ ] Given sessions whose `time_created` is older than `--days` (default 30) and whose `time_updated` is older than `--grace-hours` (default 24), When the sweep runs, Then those sessions are retired together with their messages, parts, todos, shares, inputs, context epochs and event rows.
+- [ ] Given a session that is old but was touched inside the grace window, When the sweep runs, Then it is left alone, because the grace window is a stop, not a speed.
+- [ ] Given an old parent session with a child, When the sweep runs, Then the child is retired together with the parent, so no orphan remains.
+- [ ] Given `--directory D`, When the sweep runs, Then only sessions rooted in that directory are selected, and a child in another directory goes with its parent.
+- [ ] Given `--limit N`, When the sweep runs, Then at most N top-level sessions (with their descendants) are retired.
+- [ ] Given `--dry-run`, When the sweep runs, Then it reports what would go and changes nothing on disk.
+- [ ] Given `--no-events`, When the sweep runs, Then the event rows of the retired sessions are kept.
+- [ ] Given `--vacuum`, When the sweep runs, Then the database is rewritten afterwards so the freed pages go back to the filesystem.
+- [ ] Given sessions are retired, When the sweep completes, Then a compact record (id, title, directory, project, created, updated) is written under the session archive, which is the recovery path.
+
+### US-33: Prune the event log
+**As an** opencode user whose `event` table grows without bound, **I want** a sweep that deletes event rows older than a window except those belonging to protected sessions, **so that** the database stops growing while the transcript and sync stay intact.
+
+**Story ID(s) for tests:** US-33
+**Acceptance criteria:**
+- [ ] Given event rows whose id is older than `--days` (default 7), When the sweep runs, Then those rows are candidates and newer rows are not, because the id carries the row's creation time.
+- [ ] Given a session that takes part in session sync (`event_sequence.owner_id` set), When the sweep runs, Then none of its event rows are pruned.
+- [ ] Given a session that belongs to a workspace, When the sweep runs, Then none of its event rows are pruned.
+- [ ] Given a session touched inside the grace window (`--grace-hours`, default 1), When the sweep runs, Then all of its event rows are kept.
+- [ ] Given an event whose session row is gone, When the sweep runs, Then that event is pruned, because it is garbage.
+- [ ] Given `--dry-run`, When the sweep runs, Then it reports the counts and deletes nothing, and still writes one JSON line to the run log.
+- [ ] Given `--limit N`, When the sweep runs, Then at most N rows are deleted, oldest first, and the remainder is reported for a later run.
+- [ ] Given a window longer than the id era, When the sweep runs, Then the window is clamped to the era and the table is not wiped, and the operator is warned.
+- [ ] Given candidate rows, When they are deleted, Then deletion happens in chunks and a failure mid-run leaves the rest for a later run.
+- [ ] Given `--vacuum` (and not `--dry-run`), When the sweep runs, Then the database is rewritten afterwards.
+- [ ] Given the sweep runs, When it completes, Then the `event_sequence` and `session` tables are never changed.
+- [ ] Given a run, When it completes, Then one JSON line is appended to `~/.local/share/opencode/lacode/event-prune.jsonl` carrying ts, days, graceHours, cutoff, rows, bytes, aggregates, dryRun and elapsedMs.
+
+---
+
 ## Coverage
 
-Every story below has at least one behavioural test in `tests/stories/`, and
-`tests/stories/coverage.test.mjs` enforces that mechanically in both directions:
+Every story below has at least one behavioural test. The story suites live in
+`tests/stories/`, and the root-level suites `tests/*-test.mjs` are scanned too
+(US-32, US-33), so `tests/stories/coverage.test.mjs` enforces coverage in both
+directions:
 it fails if a story here has no test, and it fails if a test names a story this
 document does not define. The acceptance criteria above are unchanged; only this
 table was filled in.
@@ -439,10 +510,11 @@ table was filled in.
 | US-3 | A | `tests/stories/a-cost-control.test.mjs` (harness: `tests/benchmark/run.mjs`) |
 | US-23 | A | `tests/stories/a-cost-control.test.mjs` |
 | US-4 | B | `tests/stories/b-provider-resilience.test.mjs`, `tests/pool-limits-test.mjs` |
-| US-5 | B | `tests/stories/b-provider-resilience.test.mjs`, `tests/pool-test.mjs`, `tests/pool-models-test.mjs` |
-| US-6 | B | `tests/stories/b-provider-resilience.test.mjs` |
+| US-5 | B | `tests/stories/b-slot-fill.test.mjs`, `tests/stories/b-provider-resilience.test.mjs`, `tests/pool-test.mjs`, `tests/pool-models-test.mjs` |
+| US-6 | B | `tests/stories/b-provider-resilience.test.mjs`, `tests/stories/b-slot-fill.test.mjs` |
 | US-7 | B | `tests/stories/b-provider-resilience.test.mjs`, `tests/pool-models-test.mjs` |
 | US-28 | B | `tests/stories/i-omniroute.test.mjs` |
+| US-31 | B | `tests/stories/b-provider-resilience.test.mjs`, `tests/stories/c-hang-recovery.test.mjs` |
 | US-8 | C | `tests/stories/c-hang-recovery.test.mjs`, `tests/pool-hang-test.mjs` |
 | US-9 | C | `tests/stories/c-hang-recovery.test.mjs`, `tests/pool-hang-test.mjs`, `tests/pool-shared-test.mjs` |
 | US-10 | C | `tests/stories/c-hang-recovery.test.mjs`, `tests/pool-hang-test.mjs`, `tests/pool-timer-test.mjs` |
@@ -450,6 +522,7 @@ table was filled in.
 | 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-30 | D | `tests/stories/d-notifications.test.mjs`, `tests/stories/e-remote-ssh.test.mjs`, `tests/oc-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` |
@@ -463,10 +536,15 @@ table was filled in.
 | US-20 | G | `tests/stories/g-context-management.test.mjs` |
 | US-21 | G | `tests/stories/g-context-management.test.mjs`, `tests/permission-test.mjs` |
 | US-22 | G | `tests/stories/g-context-management.test.mjs` |
+| US-32 | H | `tests/retire-old-sessions-test.mjs` |
+| US-33 | H | `tests/prune-old-events-test.mjs` |
 
 The nine suites under `tests/` are unit-style; the `tests/stories/` suites are
 the behavioural layer, written one epic per file with every test name carrying
 its story id. Run everything with `npm test`.
 
-**No story is uncovered.** US-1, US-2, US-3, US-6, and all of epic F have tests,
-and the coverage guard fails the build if any of them loses one.
+**No story is uncovered.** The guard reports 33 stories, 325 test cases, and
+33/33 stories with at least one behavioural test; US-1, US-2, US-3, US-6, and
+all of epic F have tests, and the coverage guard fails the build if any of them
+loses one. The scan covers the `tests/stories/` suites and the root-level
+`tests/*-test.mjs` suites.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawaty/lacode",
-  "version": "0.10.0",
+  "version": "1.0.0",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",
@@ -38,7 +38,7 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "lacode": "./dist/lacode.js"
+    "lacode": "dist/lacode.js"
   },
   "files": [
     "dist",
@@ -62,6 +62,6 @@
     "@opencode-ai/plugin": "1.18.34"
   },
   "publishConfig": {
-    "tag": "beta"
+    "tag": "latest"
   }
 }

package/presets/README.md

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

package/presets/free-tier.json

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