@lawaty/lacode 0.9.0 → 0.11.0

package/docs/TUNNEL.md

@@ -15,8 +15,12 @@ gets it back.
   │      ▼           │   ONE argument:          │   forced command)      │
   │ lacode notify    │   title\nmessage\n       │      │                 │
   │                  │   urgency\nicon\nsound   │      ▼                 │
-  │                  │                          │  notify-send /         │
+  │                  │   \nrequestID            │  notify-send /         │
   │                  │                          │  osascript             │
+  │      ▲           │ ◄─────────────────────── │                        │
+  │                  │   the clicked button's   │                        │
+  │                  │   name, on the forced    │                        │
+  │                  │   command's stdout       │                        │
   └──────────────────┘                          └────────────────────────┘
 ```
 
@@ -27,27 +31,67 @@ listening port, no systemd unit and nothing to sync: the plugin owns the
 transport, and it exists only while opencode runs — which is the only time a
 notification matters.
 
-**One argument, not five.** ssh concatenates everything after the host into a
+**One argument, not six.** ssh concatenates everything after the host into a
 single command string, and a forced command starts with *no* positional
-parameters. A sender that passes five quoted arguments arrives as the single
-string `"a b c d e"`; a receiver reading `$1..$5` sees five empty strings, falls
-back to five defaults, and pops up a blank notification. So the payload crosses
-as one newline-delimited argument:
+parameters. A sender that passes six quoted arguments arrives as the single
+string `"a b c d e f"`; a receiver reading `$1..$6` sees six empty strings,
+falls back to six defaults, and pops up a blank notification. So the payload
+crosses as one newline-delimited argument:
 
 ```
-title\nmessage\nurgency\nicon\nsound
+title\nmessage\nurgency\nicon\nsound\nrequestID
 ```
 
-Five fields — `title`, `message`, `urgency`, `icon`, `sound`. `sound` is `none`,
-`done`, `question`, `permission` or `error`. A sender that stops at `icon`
-simply leaves it empty, and an empty or unrecognised name is `none`, so a
-four-field payload is a valid one.
+Six fields — `title`, `message`, `urgency`, `icon`, `sound`, `requestID`.
+`sound` is `none`, `done`, `question`, `permission` or `error`. The request id
+is **last**, and it is opaque: it is never shown to you, never passed to a
+command, and never used to build an argument — the only thing it decides is
+whether the notification carries buttons. A sender that stops at `icon`
+simply leaves the rest empty, and an empty or unrecognised name is `none`, so a
+four-field payload is a valid one; a payload with fewer than six fields carries
+no request id at all, and therefore no buttons, so an older sender still works
+against a receiver that expects six.
 
 Newline is safe as the delimiter because both ends strip control characters from
 the free-text fields before assembling or reading it, and `urgency`, `icon` and
 `sound` come from whitelists. No field can contain the delimiter, so a message
 full of spaces, quotes or `*` survives intact.
 
+## The way back
+
+The hop was one-way until now: the notification went up to the desktop and
+nothing came back, because there was nothing on the wire to carry an answer.
+It is two-way now, and what made it two-way was not a new mechanism. **The
+desktop end is an ssh forced command, so its stdout comes back down the same
+ssh connection the notification went up.** That channel was already there and
+nobody used it: a forced command's stdout is carried to whoever opened the
+connection, so the answer rides home on the connection that is already open —
+no second connection, no listener, no port, no new key, no HTTP server.
+
+A permission notification that carries a request id is raised with three
+buttons: **Allow once**, **Always allow** and **Deny**. `notify-send` waits
+for the click and prints the chosen button's *name* on stdout — `once`,
+`always` or `reject`, and "reject" is opencode's own word for deny, not ours.
+The name needs no translation: it is already one of the values the server
+accepts as a permission reply. The plugin reads it off the helper's stdout and
+answers the permission through opencode's own reply route.
+
+Two things follow from the shape. An **empty** stdout means the popup was
+dismissed without a button being chosen: nothing is answered, and the
+permission is left exactly as it was. And a permission that was **already
+answered** — most often in the terminal — comes back as "not found" rather
+than as a failure, because the user did what they had to do and clicking a
+stale notification is not an error.
+
+The wait is bounded: ten minutes on the desktop side, and the hop's own
+deadline is stretched to outlast it, because an answer cut off by a timeout is
+worse than no answer at all.
+
+The buttons are **Linux-only**. `notify-send --action` is the only one of the
+three channels that can offer one — `osascript` and `terminal-notifier` have no
+action support — so a macOS desktop gets a plain notice, and the answer there
+still has to be given in the terminal.
+
 ## Setting it up
 
 Once, on the **remote host** (where opencode runs):
@@ -95,11 +139,20 @@ SOUND is optional and last: `none`, `done`, `question`, `permission` or `error`,
 one bundled tone per outcome. Leave it off and nothing plays; the line above
 without a fifth word is correct.
 
-`notify` is fire-and-forget by design. An unreachable desktop, a missing key, no
-notifier installed at all — all of them print a warning on stderr and exit 0. A
-notification must never be able to fail the process that tried to send one; an
-agent must not go down because a laptop went to sleep. `forward` is the
-exception: it exits with the remote's status, because its caller wants to know.
+`LACODE_REQUEST_ID` in the environment is the one thing that makes a send
+actionable: it is the permission request id, it is opaque, and it is set on the
+helper by the plugin rather than by you. A send with it carries the three
+buttons on Linux and prints the name of the clicked one on stdout; a send
+without it is an ordinary notice that prints nothing.
+
+A plain `notify` is fire-and-forget by design. An unreachable desktop, a
+missing key, no notifier installed at all — all of them print a warning on
+stderr and exit 0. A notification must never be able to fail the process that
+tried to send one; an agent must not go down because a laptop went to sleep.
+`forward` is the exception: it exits with the remote's status, because its
+caller wants to know. An **actionable** notify is the other exception, and it
+is bounded rather than open-ended: it waits for the click, because the answer
+is the whole point of it, and it still exits 0 whatever happens.
 
 On macOS the text is passed to `osascript` as arguments to an `on run argv`
 handler, never spliced into the script source — a session title is not trusted
@@ -115,6 +168,14 @@ delivers locally through the platform channel — `notify-send` on Linux,
 channel as a local send, **the desktop half is not Linux-only**: a Mac desktop
 receives notifications too.
 
+The buttons are the exception to that. Only `notify-send` can offer one, so a
+payload with a request id is an actionable notification on Linux and a plain
+notice — one that prints nothing — on macOS. What the receiver prints on stdout
+is the chosen button's name, and that stdout is what carries the answer back up
+the connection (see [The way back](#the-way-back)). The request id itself is
+never passed to a command and never printed — only its emptiness is ever
+tested.
+
 It never forwards: `SSH_CLIENT` is set for a forced command as well, so it calls
 the local channel directly rather than `notify()` (which would loop back).
 
@@ -152,6 +213,11 @@ documented with the other plugin options in the README. Set it to `0`, `false`,
 `off` or `no` to silence notifications; anything else — a typo included — leaves
 sound on, because a misspelt variable must not be how you turn a feature off.
 
+`LACODE_REQUEST_ID` is absent for the same kind of reason, and it is not yours
+to set either: the plugin puts the permission request id on the helper
+process, and the helper carries it as the payload's sixth field. The hop only
+ever asks whether it is there.
+
 ## The reverse forward
 
 A host that sets `OC_TUNNEL_PORT` and leaves `OC_LOCAL_HOST` unset reaches the
@@ -161,3 +227,7 @@ desktop through a reverse forward: `sendRemote` falls back to an ssh call to
 (`bin/oc-notify-receiver`). That receiver is the Linux end of the hop: it
 delivers through `notify-send`, and libnotify is a Linux thing, so a Mac cannot
 be this end of the tunnel.
+
+The way back works the same way here: the receiver's stdout comes back down
+the forward, on the connection the notification went up, so a click on one of
+the three buttons is carried home the same way it is on the direct hop.

package/docs/USER-STORIES.md

@@ -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 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 ceiling, When the status view is requested, Then it is not marked as the slot the next spawn would take, because the rotation's turns are skipped for a full slot until it frees a claim — unless no other slot is available and under its ceiling, in which case that full slot is the next one.
 
 ### 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 +151,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
@@ -193,7 +210,7 @@ does not.
 
 **Story ID(s) for tests:** US-11
 **Acceptance criteria:**
-- [ ] Given a session went busy and is now idle, When the idle event fires, Then a `done` notification is delivered.
+- [ ] Given a session went busy and is now idle, When the idle event fires, Then a `done` notification is delivered and stays on the desktop until the user closes it.
 - [ ] Given a session ends with an unrecognized error, When the error event fires, Then an `error` notification is delivered, it bypasses the duplicate-suppression cooldown, and it carries the error's own message.
 - [ ] Given a recognized rate-limit or quota error, or a user abort, When a session error event fires, Then no failure notification is raised — the pool already handles the former and the user already knows the latter.
 - [ ] Given a session that never went busy, When it goes idle, Then no notification is sent.
@@ -211,7 +228,7 @@ does not.
 - [ ] Given a question and a completion occur inside the same cooldown window, When both are evaluated, Then they are not deduplicated against each other.
 
 ### US-25: Notification when opencode asks for permission
-**As a** user, **I want** to be notified when opencode is blocked asking me for permission — including permission to reach a directory outside the worktree — **so that** a silent permission prompt is never mistaken for a hung agent.
+**As a** user, **I want** to be notified when opencode is blocked asking me for permission — including permission to reach a directory outside the worktree — **so that** a silent permission prompt is never mistaken for a hung agent, and so that I can allow or deny it where the notification reaches me instead of going back to the terminal.
 
 **Story ID(s) for tests:** US-25
 **Acceptance criteria:**
@@ -219,8 +236,14 @@ does not.
 - [ ] Given opencode asks to reach a directory outside the worktree, When the prompt fires, Then the notification names that directory, resolved from `metadata.parentDir`/`metadata.filepath` and with the trailing glob trimmed, because a glob is not something the user can judge.
 - [ ] Given the permission is granted, denied, or dismissed, When `permission.replied` fires, Then no notification is sent — the prompt was the thing worth interrupting for, not the answer — and only the parked-session block is cleared.
 - [ ] Given a session is parked on a permission prompt, When the idle event fires, Then no "finished" notification is sent, because nothing finished.
-- [ ] 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 the plugin observes a permission prompt, When it handles the event, Then it registers no `permission.ask` hook and mutates nothing in the payload — that hook's `output.status` is the permission decision itself, and deciding a prompt inside a handler is not the same as answering the one the user was asked for. A permission is answered through the server's own reply route, and only when the user says which answer they meant.
 - [ ] 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.
+- [ ] Given a permission prompt on Linux, When the notification is delivered, Then it is exactly one notification carrying three buttons — **Allow once**, **Always allow** and **Deny** — and the click raises no second notification.
+- [ ] Given one of those buttons is clicked, When the answer comes back over the hop the notification came up, Then the permission is answered with that button's meaning through the server's reply route; the button names are opencode's own reply values (`once`, `always` and `reject` — the server's word for deny), so a click needs no translation to become an answer.
+- [ ] Given the popup is dismissed without a button being chosen, When the notification returns, Then nothing is answered and the permission is left exactly as it was.
+- [ ] Given the permission was already answered in the terminal, When a button is clicked, Then the reply is a no-op and is not reported as a failure.
+- [ ] Given the desktop is a macOS one, When the same prompt is delivered, Then it is a plain notice with no buttons, because `osascript` and `terminal-notifier` have no action support and the answer still has to be given in the terminal there.
+- [ ] Given a question is asked, When its notification is delivered, Then it carries no buttons and answers nothing, because a question is not a permission: the v1 client this plugin has has no question API at all, and the v2 routes need a bound socket the default TUI does not have.
 
 ### 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.
@@ -234,6 +257,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
@@ -374,7 +413,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
@@ -418,10 +457,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.
@@ -437,6 +515,7 @@ table was filled in.
 | US-6 | B | `tests/stories/b-provider-resilience.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` |
@@ -444,6 +523,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` |
@@ -457,10 +537,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.9.0",
+  "version": "0.11.0",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",

package/presets/README.md

@@ -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
 ```

package/presets/free-tier.json

@@ -26,7 +26,7 @@
     "  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: big-pickle takes 3 consecutive turns, then minimax-m3.1-flash-free",
+    "With this file: big-pickle takes 3 consecutive turns, then beam-free",
     "(opencode-go) takes 2, then deepseek-v4.1-flash-free and glm-5.3-flash-free take 1",
     "each -- sequence 1,1,1,2,2,3,4,...",
     "Equal weights give a plain round robin in list order. 2,2,1,1 reproduces the old",
@@ -80,11 +80,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 }
   ]