@lawaty/lacode 0.11.0 → 1.0.0

package/CHANGELOG.md

@@ -6,6 +6,64 @@ 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.
+
+## [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
@@ -703,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
 
@@ -132,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
 
@@ -146,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
@@ -156,7 +168,7 @@ lacode version
 ```
 
 ```
-version    0.4.1
+version    1.0.0
 root       /home/you/lacode
 source     checkout
 commit     <hash> (dirty)
@@ -182,16 +194,16 @@ 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
@@ -200,30 +212,42 @@ 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 no longer
-serves 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
+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.
 
-Seven commands: `/context-init`, `/context-update`, `/context-review`,
-`/lacode-doctor`, `/agent-instructions`, `/pool` and `/pool-recheck`. Everything is added **only
-when your config does not already
+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.
 
@@ -244,6 +268,8 @@ are reading:
 /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; 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
@@ -252,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
@@ -345,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
@@ -356,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
@@ -180,11 +180,11 @@ 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 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.
 
@@ -207,6 +207,14 @@ $ARGUMENTS
 - 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) {