@lawaty/lacode 0.10.0 → 1.0.0

package/CHANGELOG.md

@@ -6,7 +6,238 @@ All notable changes to LaCode are recorded here. The format follows
 
 Versions come from git release commits; the npm version is bumped in the same
 commit as the changelog entry it describes.
-## [Unreleased]
+
+## [1.0.0] — images, ordered slot fill, and a limit that fails over
+
+### Added
+
+- **Image attachments from the clipboard or from files.** `/image-in-cb` reads
+  the system clipboard through `wl-paste`/`xclip` on Linux, `pngpaste` on macOS,
+  or PowerShell on Windows, and `/image` attaches one or more image files. Paths
+  honour quotes, `~` and globs; identical bytes are deduped within a message;
+  each file is capped at 4 MiB, at 10 images, and at 20 MiB total. Images are
+  archived content-addressed under `~/.local/share/opencode/lacode/images` and
+  delivered to the model as `FilePart`s. Configure with `imagePaste`
+  (`enabled`, `maxBytes`, `maxImages`, `dir`) or `LACODE_IMAGE_DIR`.
+- **A system-prompt guard against slot-variant names.** Every system string is
+  scrubbed by `scrubSlotNames()` before the model sees it, so a stale prompt
+  cannot teach the model `explore-1` and friends. The transform logs once when
+  it has to strip a literal.
+
+### Changed
+
+- **Slot routing fills slots in declaration order in up to two passes.** A
+  slot's `weight` is its active-session budget for one pass. Pass 1 fills each
+  usable slot to its weight in declaration order; once every usable slot has
+  reached its weight, pass 2 fills each to twice its weight. Live claims decide
+  the next slot, a released claim immediately reopens its slot, and overflow
+  goes to the least-loaded usable slot. There is no stored position.
+- **A hand-named slot variant is coerced to its base, not refused.** The task
+  hook rewrites `explore-1` to `explore` before routing, so a caller cannot pin
+  a provider or skip ordered fill. Injected agent prompts no longer name
+  variants, and `expert` is explicitly opt-in.
+- **Rate-limit failover uses the authenticated plugin client.** Aborting a
+  limited child goes through `client.session.abort`, not a bare `fetch`, so an
+  `opencode serve` protected by `OPENCODE_SERVER_USERNAME/PASSWORD` no longer
+  answers 401 and leaves the child running. A failed abort holds the claim for
+  the reaper to retry instead of releasing the slot while the session lives.
+- **A limit on a pooled child with no local claim is identified and handled.**
+  The failover path reads the session's `parentID` and user message to recognise
+  a pooled variant (`implement-1`, `explore-2`, `context-N`), cools that slot,
+  and aborts the child. Root, non-pooled, and unidentifiable sessions are left
+  alone.
+
+### Fixed
+
+- **A limited or hung session no longer survives its slot.** The rate-limit path
+  aborts it immediately, including the transient-outage path in
+  `message.updated`, and a failed abort no longer frees the slot.
+- **`pool_status` says a cooling slot is unavailable.** A cooling slot is marked
+  `UNAVAILABLE (COOLING …)`, and the summary reads `unavailable/cooling: …`.
+- **A `done` popup is raised once per idle period, and an `error` suppresses the
+  `done` that follows it in the same turn.** The per-session completion marker
+  is cleared when the session goes busy again or is deleted.
+
+### Documented
+
+- README documents `/image`, `/image-in-cb`, `imagePaste`, the `latest` dist-tag
+  for 1.0.0, and the ordered two-pass fill. `OPERATIONS.md`, `presets/README.md`
+  and the preset comments describe the same routing rule.
+
+## [0.11.0] — the old sessions and the old event rows are swept away on their own, and a pool edit takes effect without a restart
+
+### Added
+
+- **A pool edit is picked up live, and a model the provider has withdrawn no
+  longer takes its slot down with it.** The slot table used to be read once per
+  process, so editing `pool.txt`, `pool.json` or the bundled preset did nothing
+  until a restart — and a slot whose model id had been retired failed every
+  spawn routed to it. The plugin now watches the three file sources (`watchMs`,
+  default 1s; `watchDebounceMs`, default 250ms; both configurable, `watchMs: 0`
+  disables). When the resolved table actually changes it reassigns `s.slots`,
+  re-binds the variant agents and provider whitelists from the same config
+  object, and validates every slot with one real request — cooling or not. A
+  provider answering "Model not found" is now a first-class outcome:
+  `pool_recheck` benches that model for the quota cap (`model-missing`) so
+  routing stops choosing it, and names it in the report. Given `models`,
+  `pool_recheck` validates those even when they are not cooling; omitting
+  `models` keeps the old, cheap "probe what is cooling" contract. The watcher is
+  closed in `dispose`, so a torn-down plugin stops polling.
+
+### Fixed
+
+- **The bundled preset and the built-in fallback no longer name a withdrawn
+  model.** `opencode-go/minimax-m3.1-flash-free` is `deprecated` on models.dev
+  and is hidden from `opencode models`; it is replaced by
+  `opencode-go/beam-free`, which is active, free and in a different model family.
+  `tests/models-snapshot.json` was refreshed for the new slot.
+
+- **A build no longer unloads the pool from a process that starts during it.**
+  `npm run build` deleted `dist/` before rebuilding, so an opencode process that
+  imported `file://…/dist/index.js` in that window failed to load LaCode at all
+  and ran every `task` spawn on the caller's own model — `explore` appeared to
+  ignore the pool. Each entry is now staged and renamed into place, and stale
+  files are removed only after the live ones are in place.
+
+- **A task spawn with no `subagent_type` is reported instead of silently
+  bypassing the pool.** opencode runs the default subagent, which carries no
+  pool model, so it inherits the caller's model; the hook cannot route it after
+  the fact, but it now logs a warning naming the fix (`subagent_type: "explore"`
+  or `"implement"`). An `@explore` mention or a direct session prompt has the
+  same limitation: the plugin API exposes the model read-only, so it cannot be
+  re-routed there either.
+
+- **A provider limit the pool did not recognise left the task hanging until the
+  watchdog found it.** opencode reports a limit in two shapes: an `action` block
+  naming the provider and a reason, or — for every provider whose error body
+  opencode does not know — a retry status carrying nothing but the provider's
+  own words. The pool only read the first shape, and only when the reason
+  happened to be one of its own, so a limit that said "limit reached" was not a
+  limit to it: nothing was cooled, the session kept retrying the refused model,
+  and the task waited out the watchdog's minutes before anything killed it.
+  Worse, the retry went back to the same slot, because nothing had been put on
+  cooldown for the pool to route around.
+
+  The limit vocabulary now reads the provider's own phrasing — "limit reached",
+  "daily limit reached", "usage limit exceeded" — and a retry status is read for
+  its message as well as for its reason. The context family is deliberately
+  excluded: "context limit reached" is a prompt that is too long, not a
+  provider that has run out of allowance, and benching a model for it would take
+  a healthy provider out of rotation over the user's own prompt.
+
+  A limit that names its provider still benches the whole provider. A limit that
+  does not name a provider cools only the model the session was running on — the
+  one the refusal is evidence about — and either way the stalled session is
+  aborted at once, so the caller retries onto a slot that answers instead of
+  waiting for the watchdog.
+
+- **A transient outage no longer benches a model as if it had run out of
+  allowance.** "Endpoint is unavailable" is a provider that is briefly down, not
+  one that has spent its quota: it lifts on its own. Reported in a retry
+  status, it took the quota path — fifteen minutes off the rotation, filed
+  under "rate-limited" — and it counted as a strike, so the next real limit on
+  that model started at strike two and got a thirty-minute window. An outage now
+  takes the flat one-minute window the assistant-error path has always given
+  it, and it is never counted as a strike: the model is benched, the session is
+  still killed, and the quota window that follows starts where it should.
+
+- **Two processes could raise the same notification.** A notification is claimed
+  with an exclusive create, so only the process that wins the claim raises it,
+  and a claim older than its window may be taken over so a holder that died
+  mid-popup cannot silence every later one. The takeover deleted the stale claim
+  and then created its own — but the delete was unconditional and never
+  re-checked that the file it removed was still the stale claim it had judged a
+  moment earlier. Two processes that both saw the same stale claim both reached
+  the takeover: the first replaced it with a fresh claim, the second deleted
+  that fresh claim and made its own, and both returned "won", so both notified.
+  The takeover is now a compare-and-swap: an exclusive takeover lock, an
+  immediate refusal for whoever did not get it, and a re-read of the claim
+  inside the lock, so the loser leaves a live holder's fresh claim untouched.
+  The staleness rule itself is unchanged — a fresh claim is never stolen and a
+  stale one is still reclaimed.
+
+- **A `busy` session counted as you answering a prompt.** The five-second floor
+  before a notification is raised exists so it does not land while you are
+  already at the keyboard, and it is meant to be reset by real interaction.
+  `session.status: busy` was counted as that interaction — but `busy` is raised
+  whenever the session starts working, including when opencode resumes on its
+  own, so the floor was refreshed without you touching anything and the popup
+  you were owed could be suppressed. The signal is now a `message.updated` with
+  the user's own role on it, plus the reply events for permissions and
+  questions; `busy` no longer counts.
+
+- **A tunnel unit could be installed with a preflight it cannot run.** The unit
+  writer put `ExecStartPre=<preflight>` in unconditionally, so on a host where
+  the preflight was never installed systemd failed the unit and the tunnel never
+  came up — and the up-to-date check kept the broken unit because it demanded
+  the line. The line is now written only when the preflight is installed, which
+  degrades to "no preflight" rather than "no tunnel", and an already-broken unit
+  is repaired on the next run. The up-to-date check no longer requires the line.
+
+- **A strike for an unavailable provider is filed where it belongs.** An outage
+  reported through the strike path could still be counted as a quota strike and
+  handed the long window, because only one of the two call sites delegated to
+  the outage handler. Both now do, and a strike never counts an outage. A limit
+  that names a provider is also no longer overridden by the model the session
+  happened to be running on.
+
+- **Two acceptance criteria were corrected to match the shipped behaviour.**
+  US-6 criterion 4 stated the "a full slot is not the next one" rule without its
+  exception, so it contradicted the overflow path; it now says a full slot is
+  next only when no other slot is available and under its ceiling. US-19
+  criterion 3 stated a standing rule as if the product injected it, when it now
+  lives in the repo-level `AGENTS.md`.
+
+### Added
+
+- **The limit vocabulary is read from one place.** `pool.limitReason()` names
+  the limit a text reports, and the pool, the prober and the fail-over path all
+  take the reason from it, so a log line and a cooldown file never spell the
+  same fault two ways.
+
+- **US-31 — a limit that hangs is killed, and the retry lands on a slot that
+  answers.** The contract is written down as a user story with acceptance
+  criteria in `docs/USER-STORIES.md`, and every criterion has a test in
+  `tests/stories/`.
+
+- **Two retention sweeps take the old rows away before they become the whole
+  database.** `scripts/retire-old-sessions.mjs` archives then removes sessions
+  past a window (30 days, 24 hours of grace) and
+  `scripts/prune-old-events.mjs` deletes old transcript rows from `event`
+  (7 days, 1 hour of grace), in chunks, ordering by id — the id carries the
+  timestamp, so the primary-key index turns "older than" into a range scan
+  instead of a full table walk. Both refuse to touch a row that something still
+  depends on: a session an `event_sequence` cursor owns, a session bound to a
+  workspace, and anything inside the grace window. Neither ever removes or
+  resets a cursor. A session is written to a JSON archive before it is deleted,
+  and the archive is the recovery path if the window was wrong.
+
+  Both run by hand with `--dry-run`, support `--limit`, and the event prune also
+  takes `--vacuum`; a window larger than the id's own era is clamped, so a
+  mistyped number cannot be read as "delete everything". Each ships a systemd
+  service and timer (daily; `Persistent=true`, with a randomized delay on the
+  event prune so it does not run inside the session sweep's write window) and
+  appends one JSONL line per real run to a log under the state directory.
+
+- **US-32 and US-33 document the sweeps, and the coverage guard reads the root
+  suites.** Both have acceptance criteria in `docs/USER-STORIES.md` and story
+  markers on their tests. The guard now scans the root-level `tests/*-test.mjs`
+  suites as well as `tests/stories/`, so a story whose tests legitimately live
+  outside the story directory is counted instead of reported uncovered.
+
+- **Every acceptance criterion that could not be falsified now has a test that
+  fails when the behaviour regresses.** The audit found criteria whose tests
+  would have passed for the opposite behaviour: the least-loaded slot under a
+  full cooldown, a ceiling turn being skipped rather than consumed, a full slot
+  left unmarked, a macOS prompt carrying no buttons, a question carrying none,
+  a missing sound player costing only the sound, the bus path coming from the
+  local user rather than the remote, the sound playing where the notice is
+  rendered and never on the headless host, the self-update CLI, its argv and its
+  state file, cost control with no price information, the cartographer carrying
+  no model of its own, the map being reported rather than edited, an OmniRoute
+  gateway leaving a user's pool alone, and the notification doc leading with the
+  shipped path. Each new test was shown to fail by breaking the behaviour it
+  covers.
 
 ## [0.10.0] — a notification waits for you instead of timing out, and a permission can be answered from the popup
 
@@ -530,7 +761,9 @@ experimental; `latest` remains 0.4.2.
 
 - First published release: pooled subagents over a shared set of models.
 
-[Unreleased]: https://github.com/lawaty/lacode/compare/v0.10.0...HEAD
+[Unreleased]: https://github.com/lawaty/lacode/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/lawaty/lacode/compare/v0.11.0...v1.0.0
+[0.11.0]: https://github.com/lawaty/lacode/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/lawaty/lacode/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/lawaty/lacode/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/lawaty/lacode/compare/v0.7.1...v0.8.0

package/README.md

@@ -2,10 +2,8 @@
 
 > Ultimate opencode setup for Go users
 
-> **Beta — experimental, changing fast.** LaCode ships on the npm **`beta`**
-> dist-tag rather than `latest`, so nothing pulls it by accident: install
-> `@lawaty/lacode@beta`, or pin an exact version. Interfaces here can change
-> between releases without a major bump.
+> LaCode 1.0.0 ships on the npm **`latest`** dist-tag. Prereleases use
+> `beta`: install `@lawaty/lacode@beta`, or pin an exact version.
 
 LaCode is an opencode plugin. It routes delegated work onto a weighted pool of
 cheap models instead of the expensive one, reaps subagents that hang without
@@ -29,8 +27,13 @@ is also on disk at `node_modules/@lawaty/lacode/CHANGELOG.md`.
 | Per-model cooldowns and failover | A provider rate-limits mid-session and the whole thing hard-fails, while other providers sit idle. |
 | Hang reaper | A wedged subagent holds its slot forever, so the session stalls with no error and no timeout. |
 | Desktop notifications | With several sessions open you cannot see which one finished, or which is blocked on a question. |
+| Permission answers on the popup | An approval blocks a background session, and finding that session just to click Allow is the interruption. |
+| Distinct notification sounds | A popup says something happened, but not at a glance whether it is a finish, a question or a block. |
 | SSH notification tunnel | Work on a remote host raises its notification on that host, which has no desktop. |
-| Repository context map | Every task starts by exploring your codebase cold, and every agent re-discovers the same layout, the same entry points and the same boundaries — paid for again on every run. |
+| Repository context map | Every task starts by exploring your codebase cold, re-deriving the same layout, entry points and boundaries. |
+| Active backlog | What is half-done, and what can be dropped, lives in chat history the next session cannot see. |
+| Standing instructions | The same direction gets repeated every session, or buried in config that is not per-clone. |
+| Image attachments anywhere | A TUI with no image support locks vision models out entirely. |
 
 ## Getting started
 
@@ -58,9 +61,11 @@ opencode plugin @lawaty/lacode -g
 
 ### 2. Restart opencode
 
-**Nothing here hot-reloads.** The `plugin` array is read at startup, so without a
-restart the change does not take effect and the agent set will look stale for no
-visible reason.
+**Plugin code is not hot-reloaded.** The `plugin` array is read at startup, so
+without a restart the change does not take effect and the agent set will look
+stale for no visible reason. (The pool's slot files are the exception: editing
+`pool.txt`, `pool.json` or the bundled preset is picked up live — see
+[Configure](#configure).)
 
 ### 3. Check it loaded
 
@@ -91,6 +96,7 @@ To see what the pool is doing underneath:
 
 ```bash
 /lacode-doctor        # slots, model resolution, OmniRoute — report only, changes nothing
+/pool-recheck         # probe the benched models now; re-admit the ones that answer
 lacode version        # which LaCode is actually running, and whether opencode loads that one
 ```
 
@@ -129,6 +135,9 @@ option is optional:
 | `selfUpdate` | `true` | Check for a newer release at most once per ~6h and install it in the background; it applies on the next opencode start. `false` — or `LACODE_NO_SELFUPDATE=1` — turns the check off. |
 | `sound` | `true` | Play a short tone with each notification, one per outcome, so you can tell a finished session from a question or a permission prompt without reading the popup. It is opt-out: `false` — or `LACODE_SOUND=0` (`false`, `off`, `no` work too, and beat the option) — turns the sound off, and anything else, a typo included, leaves it on. |
 | `omniroute` | — | Optional [OmniRoute](docs/OMNIROUTE.md) gateway integration. Absent or `{ enabled: false }` changes nothing. |
+| `watchMs` | `1000` | How often the pool files are checked for changes. `0` disables live reload. |
+| `watchDebounceMs` | `250` | Collapse a burst of editor writes into one reload. |
+| `imagePaste` | — | Image attachments: `maxBytes` (4 MiB), `maxImages` (10) and `dir`. |
 
 ### Staying up to date
 
@@ -143,6 +152,12 @@ The running session keeps its loaded code; the new version takes effect on the
 next start, and the log says so. Run `lacode update` to do it on demand, or
 `lacode update --check` to just report.
 
+1.0.0 is published to the `latest` dist-tag; prereleases use `beta`. This check
+follows `latest`. A beta install is therefore reported as current even when a
+newer beta exists,
+and `lacode update` will not move it: pin the version you want in the `plugin`
+entry, because a new specifier is what forces a fresh resolve.
+
 ### Which LaCode is running
 
 `lacode version` answers it — and the answer is often not the version number you
@@ -153,7 +168,7 @@ lacode version
 ```
 
 ```
-version    0.4.1
+version    1.0.0
 root       /home/you/lacode
 source     checkout
 commit     <hash> (dirty)
@@ -179,45 +194,60 @@ When it reports `stale`, rebuild with `npm run build`. No network is touched;
 
 ## What you get
 
-Three agents, pooled and rotated: `explore`, `implement` and `context`. You spawn
-the base name and the pool picks a cheap model slot for it. Behind each base sits
-up to four hidden variants — one per slot — and a spawn of the bare name is the
-only thing that works: naming a variant lets the caller choose the provider
-directly, which is exactly what the rotation and the per-slot ceiling exist to
-prevent, so it is refused.
+Three pooled agents: `explore`, `implement` and `context`. You spawn the base
+name and the pool picks a cheap model slot for it. Behind each base sits up to
+four hidden variants — one per slot — and a spawn of the bare name is the only
+thing that works: a hand-named variant such as `explore-1` is coerced to its
+base and routed by the pool, so naming one cannot pin a provider or skip
+ordered slot filling.
 
-A model that rate-limits or runs out of quota is benched and taken out of the
-rotation until its window ends, so one sick provider does not take the pool with
-it. Those windows are computed backoff rather than a promise from the provider,
+A model that rate-limits or runs out of quota is benched until its window ends,
+so one sick provider does not take the pool with it.
+Those windows are computed backoff rather than a promise from the provider,
 and a quota-shaped one can run for hours — long enough for a provider that has
 since recovered, or whose quota you reset in its own console, to stay excluded
 while every delegated spawn queues behind the survivors. So LaCode asks instead
-of guessing: every fifteen minutes, and on demand via the `pool_recheck` tool, it
-probes each benched model with one real request on that exact model. A model that
-answers is re-admitted immediately — nothing restarts, nothing reloads — and a
-model that is still limited keeps exactly the window it had, because a check must
-never be the thing that extends the wait. A change is reported as a toast and a
-log line; a pass that finds nothing changed says nothing at all.
-
-Six commands: `/context-init`, `/context-update`, `/context-review`,
-`/lacode-doctor`, `/agent-instructions` and `/pool`. Everything is added **only
-when your config does not already
+of guessing: every fifteen minutes, on demand via the `pool_recheck` tool, and
+the moment a pool file changes (where it validates every slot, cooling or not),
+it probes each benched model with one real request on that exact model. A model
+that answers is re-admitted immediately — nothing restarts, nothing reloads — and
+a model that is still limited keeps exactly the window it had, because a check
+must never be the thing that extends the wait. A model the provider does not
+serve at all is benched for the quota cap and named in the report.
+A change is reported as a toast and a log line; a pass that finds nothing changed says
+nothing at all.
+
+Nine commands: `/context-init`, `/context-update`, `/context-review`,
+`/lacode-doctor`, `/agent-instructions`, `/pool`, `/pool-recheck`, `/image-in-cb`
+and `/image`. Everything is added **only when your config does not already
 define it** — an agent or command you wrote yourself is left byte-identical,
 never patched or partially merged. `{"enabled": false}` turns the whole thing off
 without leaving a trace. The exact injection list, and the five keys that are
 deliberately *not* injected, are in
 [docs/CONFIGURATION.md](docs/CONFIGURATION.md#what-gets-injected).
 
+Two more surfaces that need no configuration:
+
+- **`pool_status`** — the live view `/lacode-doctor` uses: per-slot load against
+  its ceiling, which slot the next spawn takes, cooldowns, hung claims and
+  whether the watcher is on. Ask for it when you want to know what the pool is
+  doing; it never changes slot selection.
+- **Notifications that wait** — a notification is never auto-dismissed; it stays
+  until you close it. On Linux a permission request carries **Allow once**,
+  **Always allow** and **Deny** buttons, and LaCode waits up to ten minutes for
+  the click.
+
 ## Context map
 
 Agents are stateless between tasks, and exploring your repository is the most
 expensive part of any task — so every agent pays for it again, re-deriving the
 same layout, entry points and boundaries from scratch. LaCode keeps a short,
-maintained map of the repository in `.opencode/context/` (five navigation files:
-`architecture`, `contexts`, `conventions`, `workflows`, `decisions`, plus
-`active.md` — the active backlog) and injects
-a standing rule that every agent reads the relevant file before exploring and
-starts from the canonical entry points it lists. The map holds conclusions, not
+maintained map of the repository in `.opencode/context/` — five navigation files
+(`architecture`, `contexts`, `conventions`, `workflows`, `decisions`) plus
+`active.md`, the active backlog, where a finished task stays a week and an open
+one stays until done — and injects a standing rule that every agent reads the
+relevant file before exploring and starts from the canonical entry points it
+lists. The map holds conclusions, not
 inventories: it answers "what should I look at first?" and nothing else, which
 is what makes reading it cheaper than the exploration it replaces.
 
@@ -236,7 +266,10 @@ are reading:
 /context-review    # audit it for staleness, contradictions, duplication and bloat
 /lacode-doctor     # check the pool, model resolution and the OmniRoute gateway. Report only
 /agent-instructions # apply a client instruction to the project's AGENTS.md — client-only, see below
-/pool              # rewrite the pool slot table in ~/.config/lacode/pool.txt; restart to apply
+/pool              # rewrite the pool slot table in ~/.config/lacode/pool.txt; picked up automatically
+/pool-recheck      # probe the pool now; accepts an optional provider/model list
+/image-in-cb       # attach the clipboard image to this message; macOS needs pngpaste, Linux needs wl-paste or xclip
+/image             # attach one or more image files to this message; paths honour quotes, ~ and globs
 ```
 
 The map is local and untracked — it describes your checkout on your machine, so
@@ -245,11 +278,16 @@ nothing and carry on without it. What this buys is tokens not spent
 re-discovering structure; as with everything else here, no savings percentage is
 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).
+in [docs/CONTEXT.md](docs/CONTEXT.md). Automatic map runs also clean up after
+themselves: each run's session is deleted once its transcript is written, and
+the last 20 transcripts are kept under
+`~/.local/share/opencode/lacode/cartographer` (`LACODE_TRANSCRIPT_DIR` overrides
+the directory).
 
 ## Standing instructions
 
-The project's root `AGENTS.md` is your own statement of intent: it records
+The project's root `AGENTS.md` — created on first use by `/agent-instructions` —
+is your own statement of intent: it records
 what you want worked on and how you want it approached. It says nothing about
 where code lives, so it can never contradict the code, and within that domain
 it outranks the generated context files and any agent's inference about what
@@ -338,7 +376,8 @@ which explains the harness and deliberately contains no results.
 ## Remote hosts
 
 Notifications raised on a remote host need a way back to your desktop. The
-reverse SSH forward is what carries them:
+default hop is a direct `ssh` to your desktop over one warm `ControlMaster`
+connection; a reverse forward is the fallback used when `OC_LOCAL_HOST` is unset:
 
 ```bash
 lacode notify "build finished" "4 files changed"      # local desktop, or forwarded if remote
@@ -349,6 +388,8 @@ lacode doctor                                        # what the environment reso
 must never be able to fail the process that tried to notify you. The one
 exception is an actionable notification — one carrying a permission request id
 — which waits for the click, because the answer is the whole point of it.
+That click path is Linux-only: the popup carries **Allow once**, **Always allow**
+and **Deny**, and macOS gets a plain notice without buttons.
 `lacode forward HOST -- COMMAND` runs a command on another host over ssh and
 exits with its status.
 

package/dist/agents.js

@@ -78,9 +78,12 @@ 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.
 
-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.
+Spawn the pooled base \u2014 \`explore\`, \`implement\` or \`context\`. The plugin decides
+which model runs the work; do not try to choose one yourself.
+
+\`expert\` is not part of the pool and is expensive: spawn it only when the user
+explicitly asks for it. Never escalate to it on your own, and never as a
+fallback when a pooled spawn fails.
 
 # When the pool is unavailable
 
@@ -89,12 +92,12 @@ pool cannot serve a spawn \u2014 every slot cooling or exhausted, spawns repeate
 failing, or a runtime message saying no slot is available \u2014 that is not a reason
 to do the work yourself, and not a reason to stop and ask.
 
-**Retry.** A refused or cooling slot is transient and costs you nothing but a
-turn. Spawn the bare base again. Do not escalate to a numbered variant after a
-refusal \u2014 the refusal means the pool has a routing problem, not that you
-picked the wrong number.
+**Retry.** A cooling model is transient and costs you nothing but a turn. Spawn
+the same base again. If a spawn fails, do not switch to a different name \u2014 a
+failure means the pool has a routing problem, not that you picked the wrong one.
 
-Retry is always available and never wrong, which is why it is the default. But
+Retry is always available
+ and never wrong, which is why it is the default. But
 "never wrong" is not "sufficient": looping silently against a pool with every
 model cooling goes nowhere and burns the slot doing it. So separate the two
 failures. **Transient** \u2014 a cooldown, a rate limit, one slot at its ceiling \u2014
@@ -102,7 +105,8 @@ means retry. **Persistent or structural** \u2014 every slot cooling, the same sp
 failing repeatedly with the same error, a malformed model id \u2014 means stop
 retrying and *report* it: say what failed (slot, model, error) and continue
 with whatever else the task needs, or ask the user. Surface the failure; do not
-spin on it and do not let it end the whole task.
+spin on it and do not let it end the whole task. Do not escalate to \`expert\` as
+a workaround; it is opt-in by the user.
 
 **Never fall back to reading, grepping, exploring or implementing on your own.**
 Do not "just quickly" inspect a file because a spawn failed. A failed spawn is
@@ -219,8 +223,11 @@ 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
 
-Spawn the BARE pooled base (\`explore\`, \`implement\`, \`context\`); the pool
-refuses \`-N\` variants, and a refusal means spawn the bare base, not another number.
+Spawn the pooled base (\`explore\`, \`implement\`, \`context\`); the plugin decides
+which model runs the work. Do not try to choose one yourself.
+
+\`expert\` is not part of the pool and is expensive: spawn it only when the user
+explicitly asks for it.
 
 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.
@@ -548,7 +555,7 @@ Trigger: \`.opencode/context/\` exists and work has just been done here.
    - an architectural decision
    - a new dependency between subsystems
    - a renamed or relocated subsystem
-    - a previously undocumented invariant
+   - an invariant not yet recorded in the map
 
 Do not update documentation merely because source files changed. Do not
 rewrite files wholesale. Do not make timestamp-only edits. Do not add a fact
@@ -854,7 +861,7 @@ function buildAgentSet() {
     for (let slot = 1; slot <= MAX_SLOTS; slot++) {
       const variant = {
         ...def,
-        description: `Hidden pool variant ${base}-${slot}: slot ${slot}. Its model is NOT set here -- LaCode injects it from the resolved pool preset at config time, so the preset is the only place a pool model is written down. Spawn '${base}' and let the pool route.`,
+        description: `Hidden pool slot ${slot} for ${base}. Its model is NOT set here -- LaCode injects it from the resolved pool preset at config time, so the preset is the only place a pool model is written down. Spawn '${base}' and let the pool route.`,
         hidden: true,
         // `mode: "primary"` is what keeps a variant OUT of the model's system
         // prompt. `hidden` cannot do it.
@@ -866,9 +873,10 @@ function buildAgentSet() {
         // and by default-agent resolution. A variant left as `mode: "subagent"`
         // is therefore listed to the model under its own name -- "explore-1:
         // Hidden pool variant explore-1" -- and the model copies that name
-        // straight into its next spawn. The pool then refuses it, because
-        // naming a variant is how a caller would pick the provider and skip the
-        // rotation. The refusal is right; the leak that provokes it is not.
+        // straight into its next spawn. The task hook coerces a hand-named
+        // variant back to its base, because naming one is how a caller would
+        // pick the provider and skip ordered slot fill and the slot ceiling. The coercion is right; the
+        // leak that provokes it is not.
         //
         // `mode` is the only field that filter respects, and setting it here is
         // safe: the task tool never reads an agent's mode -- it resolves the

package/dist/commands.js

@@ -93,7 +93,7 @@ context file only if this work introduced or revealed information that will
 materially help future agents \u2014 a new boundary or module, a new or moved
 canonical entry point, a changed workflow, a new convention, an architectural
 decision, a new dependency between subsystems, a renamed or moved subsystem,
-or a previously undocumented invariant.
+or an invariant not yet recorded.
 
 Do not edit documentation just because source files changed. No
 timestamp-only edits. If nothing material changed, make no edits and report
@@ -168,7 +168,7 @@ Print one PASS/FAIL line per check below, with the exact fix for any FAIL.
 Change nothing. Print a final one-line summary of failures.`
   },
   "pool": {
-    description: "Modify this machine's LaCode pool from a short instruction \u2014 the shared free-model slot table in ~/.config/lacode/pool.txt. Restarts opencode afterwards.",
+    description: "Modify this machine's LaCode pool from a short instruction \u2014 the shared free-model slot table in ~/.config/lacode/pool.txt. Picked up live; no restart.",
     template: `Apply this change to the LaCode pool on this machine:
 
 $ARGUMENTS
@@ -180,22 +180,41 @@ The pool is ONE global slot table shared by every pooled base (explore, implemen
 2. Resolve the instruction above into a target slot table. These are the rules the loader enforces \u2014 never write a file that breaks one:
    - one slot per line: \`<provider>/<model-id>  [weight]\`
    - at most ${MAX_SLOTS} slots, and a model may appear only once
-   - weight is optional (default 1) and must be a number in (0, ${MAX_WEIGHT}]. It is the slot's share of the rotation \u2014 how many turns it takes per cycle \u2014 and its concurrency ceiling is twice that. NOT a priority; pick order follows line order.
+   - weight is optional (default 1) and must be a number in (0, ${MAX_WEIGHT}]. It is the slot's active-session budget for one pass \u2014 how many turns it takes per cycle \u2014 and its concurrency ceiling is twice that. NOT a priority; pick order follows line order.
    - \`#\` starts a comment (whole-line or trailing); blank lines are ignored.
    If the instruction names a model ambiguously, or would need more than ${MAX_SLOTS} slots, stop and ask rather than guessing.
 
-3. Write the WHOLE file, not a patch. This file is an override, not an edit target: any slot you drop disappears, and slot numbers are line positions, so a partial write silently renumbers the rotation. Keep the existing comment header. If the write fails on a missing directory, create \`~/.config/lacode\` first and retry.
+3. Write the WHOLE file, not a patch. This file is an override, not an edit target: any slot you drop disappears, and slot numbers are line positions, so a partial write silently renumbers slots. Keep the existing comment header. If the write fails on a missing directory, create \`~/.config/lacode\` first and retry.
 
-4. Report the before \u2192 after slot table, the resolved path, and this reminder in substance: nothing hot-reloads, so every running opencode process must be restarted before the new pool takes effect.
+4. Report the before \u2192 after slot table and the resolved path. The running process watches the pool files: it reloads the table, re-binds the variant agents and validates every slot, so no restart is needed. If a slot names a model the provider does not serve, it will be benched and named in the log and toast \u2014 report that instead of claiming the swap succeeded.
 
 Two traps that fail silently, so check and state them explicitly:
 - A slot's provider must already exist in the user's opencode config, or that slot cannot resolve at all. If the instruction adds a model on a provider that is not configured, say so.
 - If a slot model is \`omniroute/<id>\`, that id must also appear in the plugin's \`omniroute.models\` allowlist (or be the \`combo\` id, which needs no entry) \u2014 otherwise the pool resolves and every spawn fails with \`ProviderModelNotFoundError\`.
 - A provider \`whitelist\` is an allowlist, and the plugin appends your model to it at config time. Nothing for you to do there.
 
-If the instruction is to RESET or REVERT rather than to change models, delete \`${USER_MODELS_TXT}\` instead, and report that the pool falls back to the bundled preset \u2014 with the same restart reminder.
+If the instruction is to RESET or REVERT rather than to change models, delete \`${USER_MODELS_TXT}\` instead, and report that the pool falls back to the bundled preset \u2014 the running process picks that up automatically too.
 
 Change nothing else. In particular do not touch \`presets/free-tier.json\`, \`~/.config/lacode/pool.json\`, \`FALLBACK_SLOTS\` in \`src/lib/pool.ts\`, or \`tests/models-snapshot.json\`: this command owns the per-machine override and nothing else.`
+  },
+  "pool-recheck": {
+    description: "Probe the pool now \u2014 re-admit benched models that answer, keep the ones still limited, and bench a model the provider no longer serves.",
+    template: `Probe the LaCode pool now and report the result. Run inline; do not spawn a subagent and do not edit the pool.
+
+$ARGUMENTS
+
+- If the text above names one or more models, call the \`pool_recheck\` tool with those ids in \`models\` (provider/model-id).
+- Otherwise call \`pool_recheck\` with no arguments; it probes every model that is currently cooling.
+
+Report the tool's output as it came back, then add one short line naming what changed: re-admitted, still limited, or benched because the provider does not serve the model. If a model was benched as \`model-missing\`, say so and name the replacement in \`~/.config/lacode/pool.txt\` \u2014 but change nothing yourself.`
+  },
+  "image-in-cb": {
+    description: "Attach the clipboard image to this message \u2014 macOS needs pngpaste, Linux needs wl-paste or xclip.",
+    template: "$ARGUMENTS"
+  },
+  "image": {
+    description: "Attach one or more image files to this message",
+    template: "$ARGUMENTS"
   }
 };
 function applyCommands(cfg, commands = COMMANDS) {