@lawaty/lacode 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -6,9 +6,228 @@ 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]
 
+## [0.9.0] — the cartographer keeps an active backlog, and the model stops naming slot variants
+
+### Added
+
+- **The cartographer keeps an active backlog, and the plugin enforces its
+  window.** `.opencode/context/active.md` is a sixth file in the map directory:
+  the work in flight, grouped by the ISO week each task was opened in. A task
+  that is not marked `[x]` is open, and an open task is never removed however
+  old it is; a task that is finished and dated is kept for a week after it was
+  finished and is then dropped. The file is therefore a rolling window rather
+  than a history — the question it answers is "what is open, and what just
+  closed", not "what has ever been done". A backlog that only grows is a
+  backlog nobody reads.
+
+  The window is applied by `src/lib/active-backlog.ts` and by the plugin, not
+  by the cartographer's prompt. Deciding when a task has aged out is
+  arithmetic, and arithmetic belongs where a test can pin the boundary: a rule
+  a model applies is a rule the model applies when it feels like it — one run
+  prunes and the next does not, and nothing anywhere reports the difference,
+  so the failure is silent and the backlog just grows. The plugin normalizes
+  the file on every edit of it and once when the session starts, so a hand
+  edit is grouped and pruned whether the cartographer ran or not, and the file
+  is rewritten only when its canonical form differs from what is on disk, so
+  the write cannot loop. The boundary is strict: a task finished exactly seven
+  days ago is still that week's news, and is kept.
+
+### Fixed
+
+- **A slot variant is no longer in the agent list the model is shown, so the model
+  stops naming slots by hand.** opencode builds the system prompt's "Available
+  agent types" block by filtering the agent registry on `mode !== "primary"` and on
+  the caller's task permission. It never reads `hidden`: that flag is honoured only
+  by the TUI, the @-mention pickers, the "agent not found" message and default-agent
+  resolution. Every pooled variant was therefore listed to the model under its own
+  name — "explore-1: Hidden pool variant explore-1" — and a model that can see
+  twelve concrete slot names reaches for them, so the root agent kept spawning
+  `explore-1` and `implement-4` instead of the bare base, and the pool refused
+  every one. The refusal was right and the leak that provoked it was not: naming a
+  variant is how a caller would pick the provider and skip the rotation and the
+  slot's ceiling, so it cannot be allowed to succeed. The variants now carry
+  `mode: "primary"`, the one field that filter respects, which takes them out of
+  the agent list while leaving them spawnable by name — the task tool resolves an
+  agent by name and never reads its mode — and out of the TUI, where `hidden`
+  already kept them. The bare bases are untouched and stay in the list, so the
+  model has nothing but the bases to choose from.
+
+- **A refusal no longer names the variant it refused, and the instructions no
+  longer list the names they forbid.** The refusal was the strongest remaining
+  channel. It is the tool result the model reads at the exact moment it is
+  choosing what to spawn next, and it used to repeat the name that had just been
+  denied — so the denial was the thing that taught the name, and the model copied
+  it back. It now names the base instead, which is what the model should type.
+  The same reasoning applies to the rules themselves: "never name a `-N` variant
+  (`explore-1`..`explore-4`, `implement-1`..)" put eight concrete agent names in
+  front of the model in the sentence that told it what to spawn. A rule that
+  lists the names it forbids teaches the names; the rule now states the rule
+  without an example, in the shipped agent prompts, the project prompts and the
+  global delegation rules.
+
+- **The cartographer no longer leaves empty sessions in the session list.** The
+  session was created before the run started, and only the turn's own success
+  and failure paths retired it. Anything that threw in between — a slot that
+  could not be picked, a claim that could not be written, a prompt that failed
+  before it returned — stranded a session with no messages in it: an entry in
+  the user's list that opens as nothing at all. Retirement now covers the whole
+  gap between the create and the prompt, and the delete is *verified* rather
+  than assumed — it is read back afterwards, retried once, and a failure is
+  logged instead of swallowed. (Archiving is not a way out: opencode's list is
+  served from the session rows themselves, so a session with `time_archived` set
+  is still listed. Only a delete removes an entry.)
+- **A finished cartographer run retires its session and keeps the transcript**
+  was already true, and stays true: the transcript is written first and the
+  session deleted second, because the transcript is the only record of what the
+  run did. The plugin's own last 20 runs are kept in full.
+
+### Changed
+
+- **The bundled default pool no longer ships a model its provider has withdrawn.**
+  `presets/free-tier.json` named `opencode/space-bunny-free` as its first slot at
+  weight 3 — the slot that took the most turns. The opencode provider withdrew that
+  model, and because it was the default, every new session then died at step 0 with
+  `ProviderModelNotFoundError: Model not found: opencode/space-bunny-free`. Nothing
+  in the package could tell: the pool warns about a slot that is missing from the
+  config, not about a slot whose model the provider no longer serves, and the root
+  agent's own model lives in the user's config rather than here.
+
+- **`scripts/retire-cartographer-sessions.mjs` clears the sessions the feature
+  did not reach.** Retirement landed after 250 runs had already piled up across
+  the machine's projects, and those were never cleaned. The tool talks to the
+  opencode server over its HTTP API — the same interface the plugin uses — and
+  writes a compact record of each retired session to
+  `~/.local/share/opencode/lacode/cartographer-archive/` before deleting it, so
+  nothing is lost. `--dry-run` shows what it would do.
+
+## [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
@@ -245,11 +464,14 @@ 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.1...HEAD
+[Unreleased]: https://github.com/lawaty/lacode/compare/v0.9.0...HEAD
+[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
 [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
+[0.4.2]: https://github.com/lawaty/lacode/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/lawaty/lacode/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/lawaty/lacode/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/lawaty/lacode/compare/v0.2.2...v0.3.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
@@ -199,8 +213,9 @@ deliberately *not* injected, are in
 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 files:
-`architecture`, `contexts`, `conventions`, `workflows`, `decisions`) and injects
+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
 inventories: it answers "what should I look at first?" and nothing else, which
@@ -237,7 +252,7 @@ in [docs/CONTEXT.md](docs/CONTEXT.md).
 The project's root `AGENTS.md` 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 five generated context files and any agent's inference about what
+it outranks the generated context files and any agent's inference about what
 matters right now.
 
 The file is per-clone and not committed, so it is yours rather than shared
@@ -258,8 +273,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
 
@@ -352,7 +370,7 @@ want it.
 | [Install and troubleshooting](docs/INSTALL.md) | Where opencode puts the package, what to do when the agents are missing, the version matrix, macOS differences, and the `lacode` CLI. |
 | [Configuration reference](docs/CONFIGURATION.md) | Every plugin option, how the pool resolves its slots, per-agent tool grants, and exactly what gets written into your config. |
 | [OmniRoute gateway](docs/OMNIROUTE.md) | The optional local gateway integration: setup, full option set, a latency-measured free combo, and its troubleshooting table. |
-| [Context map](docs/CONTEXT.md) | The mechanism behind `.opencode/context/` — the one-writer permission rule, the five files, and what the log lines mean. |
+| [Context map](docs/CONTEXT.md) | The mechanism behind `.opencode/context/` — the one-writer permission rule, the files, and what the log lines mean. |
 | [Remote hosts and notifications](docs/TUNNEL.md) | The SSH notification hop, payload format, receiver contract, and holding the forward open. |
 | [Benchmarks](docs/BENCHMARKS.md) | How the cost harness works, and why it deliberately publishes no savings number. |
 | [User stories](docs/USER-STORIES.md) | The behavioural contracts behind all of the above, written so a test can assert them. |

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
@@ -89,8 +90,8 @@ failing, or a runtime message saying no slot is available \u2014 that is not a r
 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 a \`-N\` variant when a refusal
-names one \u2014 the refusal means the pool has a routing problem, not that you
+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 is always available and never wrong, which is why it is the default. But
@@ -449,7 +450,7 @@ if the blocker is understanding rather than execution, report that instead.`,
     }
   },
   "context": {
-    "description": "Repository cartographer and memory maintainer. Bootstraps and incrementally maintains .opencode/context/ (architecture, contexts, conventions, workflows, decisions) as a small navigation map for future agents. Runs automatically after sessions that changed files; can also be invoked with /context-init, /context-update, /context-review. Never use it for general coding tasks.",
+    "description": "Repository cartographer and memory maintainer. Bootstraps and incrementally maintains .opencode/context/ (architecture, contexts, conventions, workflows, decisions) as a small navigation map for future agents, and keeps .opencode/context/active.md \u2014 the active backlog of work in flight, grouped by week. Runs automatically after sessions that changed files; can also be invoked with /context-init, /context-update, /context-review. Never use it for general coding tasks.",
     "mode": "subagent",
     "temperature": 0.1,
     prompt: `# Role
@@ -465,7 +466,7 @@ map is a derived index of it.
 
 # Owned files
 
-You own exactly these five files and nothing else:
+You own exactly these files and nothing else:
 
 - \`.opencode/context/architecture.md\` \u2014 high-level architecture, major layers,
   boundaries, important entry points, dependency rules. Target 50\u2013150 lines.
@@ -480,6 +481,9 @@ You own exactly these five files and nothing else:
 - \`.opencode/context/decisions.md\` \u2014 architectural decisions discovered
   during work that are not already recorded in the project's own decision
   log. Concise; variable length.
+- \`.opencode/context/active.md\` \u2014 the active backlog: work in flight, grouped
+  by the week it was opened. Not part of the navigation map; it is described
+  under "Task backlog" below.
 
 # Current-state only
 
@@ -519,7 +523,8 @@ Explore progressively and stop as soon as you have a usable map:
 You are mapping a city, not auditing every house. Do not attempt to
 understand every file.
 
-Then write the five files. For each significant subsystem, give a short
+Then write the five files. Also create \`.opencode/context/active.md\` with its
+heading and no tasks. For each significant subsystem, give a short
 "Start here" list \u2014 at most about five canonical files, each with a one-phrase
 reason. This is the single most valuable thing you produce: where an agent
 should open its editor next.
@@ -543,7 +548,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
+    - a previously undocumented invariant
 
 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
@@ -551,6 +556,38 @@ that is already stated in another context file \u2014 one fact has one home, and
 the other files link to it. If nothing material changed, make no edits and
 report "no update needed".
 
+Also keep \`.opencode/context/active.md\` current: record work that is in
+flight, and mark a task finished \u2014 with the date it finished \u2014 when it is.
+
+# Task backlog
+
+\`.opencode/context/active.md\` holds the work in flight. It is a rolling
+window, not a history: it answers "what is open, and what just finished".
+
+Format \u2014 one line per task, under the ISO week the task was opened in:
+
+    ## 2026-W43
+
+    - [ ] Ship the release notes \u2014 opened 2026-W43
+    - [x] Fix the flaky test \u2014 opened 2026-W43, finished 2026-10-19
+
+The rules:
+
+- A task that is not marked \`[x]\` is OPEN. An open task is never removed,
+  however old it is.
+- A task is FINISHED when it is marked \`[x]\` AND carries a \`finished\`
+  date. Record the date it actually finished, as \`YYYY-MM-DD\`.
+- The week is \`YYYY-Www\`, Monday to Sunday. \`date +%G-W%V\` prints it.
+- A finished task is dropped once it is more than a week old. The plugin
+  enforces that: record the finished task with its date and let the window
+  close on its own. Do not delete old finished tasks by hand, and do not
+  keep a finished task back to preserve it \u2014 the file is meant to stay
+  small.
+- Never invent a task. Record work that actually happened, and mark a task
+  finished only once it is finished.
+- Keep the file inside the window. If the backlog has grown past a handful
+  of weeks, that is a signal to close finished tasks, not to add sections.
+
 # Minimal exploration
 
 Default shape:
@@ -637,7 +674,7 @@ the lowest-value ones, and link out to authoritative project docs.
 
 Trigger: an explicit review (see the \`context-review\` command).
 
-Audit the five files for:
+Audit the map files and the backlog for:
 
 - stale information \u2014 verify claims against the code
 - contradictions between files, or between the map and the code
@@ -645,10 +682,12 @@ Audit the five files for:
 - duplicated information \u2014 one canonical place per fact
 - missing canonical entry points for significant subsystems
 - unsupported assumptions \u2014 anything unmarked that you cannot verify
+- backlog tasks that are finished but carry no date \u2014 the retention window
+  cannot age those out, so they stay forever
 
-Fix problems only in the five files you own. Never modify source code
-during a review. Report what you found, what you fixed, and what you
-could not verify.
+Fix problems only in the files you own. Never modify source code during a
+review. Report what you found, what you fixed, and what you could not
+verify.
 
 # Reporting
 
@@ -753,20 +792,46 @@ on that.
   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",
@@ -790,7 +855,28 @@ function buildAgentSet() {
       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.`,
-        hidden: true
+        hidden: true,
+        // `mode: "primary"` is what keeps a variant OUT of the model's system
+        // prompt. `hidden` cannot do it.
+        //
+        // opencode builds the "Available agent types" block by filtering the
+        // agent registry on `mode !== "primary"` and on the caller's task
+        // permission. It never looks at `hidden`: that flag is honoured only by
+        // the TUI and the @-mention pickers, by the "agent not found" message,
+        // 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.
+        //
+        // `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
+        // agent by name and runs it -- and every other place that filters on
+        // `mode !== "primary"` also filters on `!hidden`, which these already
+        // are. opencode uses this same pair for its own compaction, title and
+        // summary agents.
+        mode: "primary"
       };
       delete variant.model;
       set[`${base}-${slot}`] = variant;

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
@@ -66,7 +67,8 @@ your system prompt.
 Otherwise follow the bootstrap procedure in your system prompt: progressive
 exploration (README \u2192 existing docs \u2192 manifests \u2192 top-level structure \u2192 build
 and framework config \u2192 entry points \u2192 selective source), then write the five
-context files inside their size targets.
+context files inside their size targets. Also create
+\`.opencode/context/active.md\` with its heading and no tasks.
 
 Remember: write conclusions, not inventories. Link to the project's existing
 documentation instead of duplicating it.
@@ -103,10 +105,10 @@ timestamp-only edits. If nothing material changed, make no edits and report
     subtask: true,
     template: `Context review.
 
-Everything outside the five context files is read-only for this run. Do not
+Everything outside \`.opencode/context/\` is read-only for this run. Do not
 modify source code under any circumstances.
 
-Audit the five context files for:
+Audit the context files and the backlog for:
 
 - stale information \u2014 verify claims against the actual code
 - contradictions between context files, or between the map and the code
@@ -117,6 +119,8 @@ Audit the five context files for:
 - missing canonical entry points for significant subsystems
 - unsupported assumptions \u2014 anything stated as fact that you cannot verify,
   or that lacks a confidence marker
+- backlog tasks that are finished but carry no date \u2014 the retention window
+  cannot age those out, so they stay forever
 
 Fix what you find in \`.opencode/context/\` only, then report: findings, fixes,
 and anything you could not verify.`
@@ -138,7 +142,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 +180,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.