@lawaty/lacode 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -9,6 +9,142 @@ commit as the changelog entry it describes.
 
 ## [Unreleased]
 
+## [0.8.0] — cooldowns are probed instead of trusted, and the instructions agent can read the map
+
+### Added
+
+- **Benched models are now checked by using them.** A model that rate-limits or runs
+  out of quota is benched until its window ends, and that window is computed
+  backoff rather than a promise from the provider — a quota-shaped one reaches six
+  hours, long enough for a provider that recovered, or whose quota was reset by hand
+  in its own console, to stay excluded while every delegated spawn queues behind the
+  survivors. `pool_recheck` asks instead of guessing: one real request on that exact
+  model, with a one-word prompt and its own system string so the check costs
+  handfuls of tokens rather than shipping a subagent's instructions. A model that
+  answers is re-admitted at once — no restart, no reload, because `readLimits`
+  rebuilds the cooldown state from disk on every routing decision — and one that is
+  still limited keeps exactly the window it had. `src/lib/probe.ts` owns the probe;
+  it runs every fifteen minutes while anything is cooling (`probeMs`, `0` disables)
+  and on demand through the tool, one model at a time, silent when nothing changed
+  and reported as a toast plus a log line when something did.
+
+  Three rules keep a health check from becoming the thing it is checking for. A
+  probe's own failure is never counted as a strike, or repeated checks would drive
+  the window to the six-hour cap and no probe could ever pass; the only window it
+  may change is one the provider itself stated, which is the provider correcting a
+  guess. A probe's 429 never benches a whole provider — one request is evidence
+  about one request. And a probe is a root session like any other, so it is marked
+  in the shared pool state to keep the cartographer's idle trigger from starting a
+  context run on its way past.
+
+### Changed
+
+- **A finished cartographer run leaves the session list.** opencode's list shows
+  root sessions, and the cartographer was created with no `parentID` — so every
+  automatic run landed in the user's main list and buried real work (112 of them
+  on one machine). Nesting it under the triggering session is unsafe:
+  `pool.bindChild` adopts a fresh child into any claim the parent holds without a
+  target, which is exactly what a root has while its own explore tasks are in
+  flight, and the reaper would abort the cartographer as though it were the hung
+  task. Archiving is unavailable in 1.18.34 — no archive method, and `session.list`
+  takes only `directory`. So the run now exports its transcript to
+  `~/.local/share/opencode/lacode/cartographer/` (last 20 kept, override with
+  `LACODE_TRANSCRIPT_DIR`) and deletes the session, on the failure path as well as
+  the success path, since a retrying cartographer is what fills a list fastest.
+  Its notifications were already suppressed.
+
+- **A slot's concurrency ceiling is now twice its weight.** Weight still sets how
+  many turns a slot takes per weighted round-robin rotation, but the ceiling is
+  `2 × weight`, so one full rotation fills only half the pool and the run is walked
+  twice before every slot is full. `pool_status` prints the ceiling as `load=n/2w`,
+  and a weight-3 slot may now hold 6 concurrent sessions.
+
+- **The `instructions` agent can read the context map.** Its `read` grant was
+  scoped to `AGENTS.md` alone, so an `/agent-instructions` directive was applied
+  without sight of what the project has already settled — the agent could restate
+  a fact `conventions.md` records, or contradict one it had never read. The map is
+  now readable through both path spellings (`.opencode/context/**` and
+  `*/.opencode/context/**`), declared after the broad deny so the grant is not
+  inert. The **write** grant is unchanged and still reaches `AGENTS.md` only: the
+  map stays read-only to this agent, `context` remains its only writer, and the
+  writer guard — which reads `edit` alone — needs no new exemption.
+
+### Fixed
+
+- **The pool no longer grows without bound.** The per-session `activity` and
+  `children` maps were written on every message event and every `session.created`
+  and never pruned, so a long-running server accumulated an entry per session for
+  the life of the process. Both are now swept by the reaper and on every spawn, and
+  the notifier's per-session bookkeeping (`active` / `titles`) is capped at 500.
+
+- **The routing log no longer prints a slot variant's name.** It read
+  `routed explore -> explore-2`, which is read by the very agent being routed and
+  hands it a valid-looking agent name in the exact place it decides what to spawn.
+  The refusals that followed were the model copying those names back —
+  `implement-4` 23 times, `implement-2` 20, `explore-2` 12, roughly one per routed
+  spawn. The line now names the slot and the model, which is the same diagnostic
+  value with nothing for the model to echo. The refusal itself is unchanged.
+
+- **The notification helper spawn is bounded.** Question, permission and error
+  outcomes bypass the notification cooldown on purpose — a session blocked on a
+  prompt the user was never told about is the silent stall this plugin exists to
+  prevent — so a failure storm could start one detached helper per event, each
+  `bin/oc-notify` → `bin/oc` → an ssh attempt, with nothing reaping them. The
+  bound is on the transport, not on the decision: at most 4 helpers in flight,
+  and one that has not answered in 30s is killed. Which notifications fire is
+  unchanged.
+
+- **A provider-stated reset can no longer bench a model for days.** A stated
+  window ("Resets in 35min") is still trusted over the computed backoff, but the
+  parse was unbounded, so one malformed upstream number removed a slot from
+  rotation indefinitely: an `account_rate_limit` carrying `retry in 329917s`
+  (~3.8 days) cooled a model for **91.6 hours**, long past the window it was
+  waiting for, and every delegated spawn queued behind the survivors. A stated
+  window is now discarded past `STATED_COOLDOWN_MAX_MS` (6h, the quota cap) so
+  the caller falls back to the ordinary strike backoff instead of trusting a
+  number it cannot believe. A limit already on disk is unaffected — delete its
+  `limit.<model>.json` to re-admit the model now.
+
+- **`"Resets in 2hr 17min"` is no longer read as 2h00.** The unit alternations
+  were ordered `h|hr|hour`, so `2hr 17min` matched the bare `h`, left `r 17min`
+  unparsed and silently dropped the minutes — a window too *short* by exactly the
+  part it discarded, despite the docstring claiming that spelling was handled.
+  Alternations are now longest-first (`hour|hr|h`, `minute|min|m`, `second|sec|s`).
+
+- **The OmniRoute sticky-assignment table is bounded.** It is keyed by session and
+  only a *failure* deleted an entry, so it grew with every session the process ever
+  served rather than with the sessions in flight. It is now capped at 500,
+  evicting oldest-first, and a `select()` that returns an existing assignment
+  re-inserts it — previously a long-running session kept its original position and
+  was evicted as "oldest" while still actively in use.
+
+- **A pinned agent whose model is cooling now says so.** `basic` and `expert`
+  hard-code a model and are not pooled, so a spawn of either falls through routing
+  with nothing logged: when that provider was benched the escalation agent simply
+  read as "cancelled". The pool now warns once, naming the model, the reason and
+  the fact that only `explore`/`implement`/`context` can fail over.
+
+- **The shared state directory now cleans itself without needing traffic.** Dead
+  claims files and lapsed cooldowns were reclaimed only as a side effect of
+  `snapshot()`, which runs when something spawns — so an idle machine, or one
+  whose process was killed before its next spawn, carried a dead process's claims
+  file and every lapsed cooldown indefinitely, and those files are read on every
+  routing decision. `sweepStateDir` applies the same policy on an hourly clock,
+  and once at startup so the previous run's debris goes immediately. It never
+  touches this process's own claims file, `cursor.json`, a running cooldown, or a
+  lapsed cooldown still inside its strike-decay window (deleting that would reset
+  the strike count and restart the backoff at 1).
+
+## [0.7.1] — /agent-instructions creates AGENTS.md on first use
+
+### Changed
+
+- **`/agent-instructions` creates `AGENTS.md` on first use.** The hidden
+  `instructions` agent now creates the project's root `AGENTS.md` when it does
+  not exist, seeded with the instruction you pass, instead of refusing. Nothing
+  is created at startup and no placeholder content is written — the file appears
+  only when you run the command, and holds only what you asked for.
+
 ## [0.7.0] — standing instructions move to the project AGENTS.md
 
 ### Changed
@@ -235,7 +371,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.7.0...HEAD
+[Unreleased]: https://github.com/lawaty/lacode/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/lawaty/lacode/compare/v0.7.1...v0.8.0
+[0.7.1]: https://github.com/lawaty/lacode/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/lawaty/lacode/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/lawaty/lacode/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/lawaty/lacode/compare/v0.4.2...v0.5.0

package/README.md

@@ -125,6 +125,7 @@ option is optional:
 | `models` | — | An inline slot list. Highest-priority source. |
 | `modelsFile` | — | An explicit slot file; short-circuits the [resolution chain](docs/CONFIGURATION.md#pool-preset-resolution). |
 | `reapMs` | `30000` | Hang-reaper interval. |
+| `probeMs` | `900000` | How often benched models are checked by actually using them. `0` turns the periodic check off and leaves the `pool_recheck` tool as the only way to ask. |
 | `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. |
@@ -185,6 +186,19 @@ 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.
 
+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,
+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
@@ -258,8 +272,11 @@ is the hidden `instructions` agent, reachable solely through the
 instruction you have given to `AGENTS.md`, then reports what it changed. It is
 a normal agent turn, not a dead append: tell it what you want and review the
 result. The `instructions` agent is the one agent permitted to edit that file,
-its grant is scoped to `AGENTS.md` alone, and no other agent can spawn it —
-the command is the only route in.
+its write grant is scoped to `AGENTS.md` alone, and no other agent can spawn it —
+the command is the only route in. It may also **read** `.opencode/context/`, so a
+directive does not restate a fact the map has already settled or contradict one it
+has not read; the map stays read-only to it, and the `context` agent remains its
+only writer.
 
 ## Cost
 

package/dist/agents.js

@@ -44,6 +44,7 @@ var DEFAULT_PRESET = join2(PRESETS_DIR, "free-tier.json");
 var USER_CONFIG_DIR = join2(homedir(), ".config", "lacode");
 var USER_MODELS_PATH = join2(USER_CONFIG_DIR, "pool.json");
 var USER_MODELS_TXT = join2(USER_CONFIG_DIR, "pool.txt");
+var STATE_SWEEP_INTERVAL_MS = 60 * 60 * 1e3;
 var CHILD_MEMORY_MS = 30 * 6e4;
 
 // src/lib/agent-instructions.ts
@@ -747,23 +748,52 @@ on that.
   tidy, reorder or delete content the client did not ask you to touch.
 - Prefer current-state wording: state how things are, not how they changed.
 - Keep the file concise. If it is growing past roughly 150 lines, say so.
-- If \`AGENTS.md\` does not exist, stop and report that there is nothing to edit.
-  Do not create it.
+- If \`AGENTS.md\` does not exist, create it and record the client's instruction in
+  it \u2014 that instruction is the file's first content.
+- Do NOT add placeholder comments, empty template headings, or example text;
+  write only what the client asked for.
+- Say plainly in your report that you created the file.
+
+# Before you write
+
+Read \`.opencode/context/\` first when it is there \u2014 \`architecture.md\`,
+\`conventions.md\` or \`contexts.md\`, whichever bears on the directive \u2014 so you do
+not record a fact the project has already settled, and do not contradict one you
+do not know yet. Read only what is relevant, and carry on if it is missing.
+
+That map is READ-ONLY to you: the \`context\` agent is its only writer. If the
+directive contradicts it, say so plainly in your report and still write what the
+client asked for. Never edit the map to agree with \`AGENTS.md\` \u2014 the two are
+different files with different jobs, and this one is yours alone.
 
 # Reporting
 
 Report briefly what you changed and where. Do not edit any other file.`,
   permission: {
-    // Read is scoped to the one file too: the directive is about AGENTS.md, and
-    // nothing else is any of this agent's business.
+    // Read reaches AGENTS.md and the context map, and nothing else.
+    //
+    // The map is here because the directive is about how work is DONE in this
+    // project and the map is the maintained record of what the project IS: reading
+    // it is how this agent avoids recording a fact the code already settles, and
+    // avoids contradicting one it does not know yet. It stays READ-ONLY — `edit`
+    // below still denies the map, so this grant cannot turn the one-writer rule
+    // into a two-writer rule, and the writer guard does not have to care about it
+    // (it reads `edit` alone).
+    //
+    // Both spellings are required, and every allow must sit AFTER the broad deny:
+    // LAST match wins, so an allow written before "*": "deny" is silently inert.
     read: {
       "*": "deny",
       "AGENTS.md": "allow",
-      "*/AGENTS.md": "allow"
+      "*/AGENTS.md": "allow",
+      "*/.opencode/context/**": "allow",
+      ".opencode/context/**": "allow"
     },
     glob: "deny",
     grep: "deny",
     list: "deny",
+    // Still exactly one writable path. The map is readable (see above) and stays
+    // unwritable: `context` is its only writer, and this agent is not it.
     edit: {
       "*": "deny",
       "AGENTS.md": "allow",

package/dist/commands.js

@@ -49,6 +49,7 @@ var DEFAULT_PRESET = join2(PRESETS_DIR, "free-tier.json");
 var USER_CONFIG_DIR = join2(homedir(), ".config", "lacode");
 var USER_MODELS_PATH = join2(USER_CONFIG_DIR, "pool.json");
 var USER_MODELS_TXT = join2(USER_CONFIG_DIR, "pool.txt");
+var STATE_SWEEP_INTERVAL_MS = 60 * 60 * 1e3;
 var CHILD_MEMORY_MS = 30 * 6e4;
 
 // src/commands.ts
@@ -138,7 +139,8 @@ Follow the rules for the file in your system prompt, then report what you change
 Print one PASS/FAIL line per check below, with the exact fix for any FAIL.
 
 1. Pool status \u2014 call the \`pool_status\` tool. Report the slot list, each
-   slot's load against its weight ceiling, and which models are cooling.
+   slot's load against its ceiling (twice the slot's weight), and which models
+   are cooling.
 
 2. OmniRoute configured \u2014 inspect the \`@lawaty/lacode\` plugin options in the
    user's opencode config for an \`omniroute\` block with \`enabled: true\`. If it
@@ -175,7 +177,7 @@ 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 soft ceiling on concurrent claims and the slot's share of the rotation \u2014 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 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.
    - \`#\` 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.