@lawaty/lacode 0.10.0 → 0.11.0

package/dist/tunnel.js

@@ -1,6 +1,16 @@
 // src/tunnel/index.ts
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { appendFileSync, existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync4, unlinkSync as unlinkSync3 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { join as join4 } from "node:path";
+
+// src/lib/notify.ts
+import { closeSync, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync3, statSync as statSync2, unlinkSync as unlinkSync2, writeSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join3 } from "node:path";
+
+// src/lib/pool.ts
+import { existsSync, mkdirSync, readdirSync, readFileSync as readFileSync2, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join as join2 } from "node:path";
 
@@ -24,6 +34,36 @@ var findPackageRoot = (start) => {
 };
 var PACKAGE_ROOT = findPackageRoot(dirname(fileURLToPath(import.meta.url)));
 
+// src/lib/pool.ts
+var CLAIM_TTL_MS = 10 * 60 * 1e3;
+var DEAD_FILE_MS = 2 * CLAIM_TTL_MS;
+var ORPHAN_TMP_MS = 60 * 1e3;
+var CATALOG_TTL_MS = 10 * 60 * 1e3;
+var STUCK_MIN_AGE_MS = 5 * 60 * 1e3;
+var STUCK_IDLE_MS = 3 * 60 * 1e3;
+var MAX_CLAIM_AGE_MS = 30 * 60 * 1e3;
+var HANG_COOLDOWN_MS = 10 * 60 * 1e3;
+var UNAVAILABLE_COOLDOWN_MS = 60 * 1e3;
+var COOLDOWN_BASE_MS = 60 * 1e3;
+var COOLDOWN_MAX_MS = 15 * 60 * 1e3;
+var QUOTA_COOLDOWN_BASE_MS = 15 * 60 * 1e3;
+var QUOTA_COOLDOWN_MAX_MS = 6 * 60 * 60 * 1e3;
+var STRIKE_DECAY_MS = 30 * 60 * 1e3;
+var PRESETS_DIR = join2(PACKAGE_ROOT, "presets");
+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/notify.ts
+var NOTIFY_SESSION_ENV = "LACODE_NOTIFY_SESSION";
+var NOTIFY_CLOSE_ENV = "LACODE_NOTIFY_CLOSE";
+var notificationStateDir = () => process.env.LACODE_NOTIFY_DIR ?? join3(homedir2(), ".local", "share", "opencode", "lacode", "notify");
+var safeCorrelationKey = (correlationKey) => correlationKey.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 64);
+var notificationIdFile = (correlationKey) => join3(notificationStateDir(), `${safeCorrelationKey(correlationKey)}.ids`);
+
 // src/tunnel/index.ts
 var ICONS = [
   "utilities-terminal",
@@ -46,7 +86,7 @@ function resolveTunnel(env = process.env) {
     user: env.OC_LOCAL_USER ?? "",
     host: env.OC_LOCAL_HOST ?? "",
     port: Number.isFinite(port) && port > 0 ? port : 10022,
-    key: env.OC_NOTIFY_KEY ?? join2(homedir(), ".ssh", "lacode_notify"),
+    key: env.OC_NOTIFY_KEY ?? join4(homedir3(), ".ssh", "lacode_notify"),
     connectTimeoutMs: Number(env.OC_CONNECT_TIMEOUT_MS) || 5e3
   };
 }
@@ -74,16 +114,32 @@ var safeRequestId = (raw) => {
   if (!clean) return void 0;
   return clean.length > 128 ? clean.slice(0, 128) : clean;
 };
+var CLOSE_REQUEST_PREFIX = "close:";
+var wireCorrelationKey = (raw) => safeText(raw ?? "", "", 200);
+var presentCorrelationKey = (raw) => {
+  const clean = wireCorrelationKey(raw);
+  return clean ? clean : void 0;
+};
+var isCloseRequest = (correlationKey) => typeof correlationKey === "string" && correlationKey.startsWith(CLOSE_REQUEST_PREFIX);
+var closeRequestTarget = (correlationKey) => {
+  if (!isCloseRequest(correlationKey)) return void 0;
+  const target = correlationKey?.slice(CLOSE_REQUEST_PREFIX.length).trim() ?? "";
+  return target ? target : void 0;
+};
 var FIELD_SEPARATOR = "\n";
 function parsePayload(raw) {
-  const [title, message, urgency, icon, sound, requestID] = raw.split(FIELD_SEPARATOR);
+  const [title, message, urgency, icon, sound, requestID, correlationKey] = raw.split(FIELD_SEPARATOR);
+  const key = wireCorrelationKey(correlationKey);
   return {
     title: safeTitle(title),
     message: safeMessage(message),
     urgency: normalizeUrgency(urgency),
     icon: normalizeIcon(icon),
     sound: normalizeSound(sound),
-    requestID: safeRequestId(requestID)
+    requestID: safeRequestId(requestID),
+    // The seventh field, empty when there is none. A close request keeps its
+    // marker here, so the receiver can still tell it apart from a session.
+    ...key ? { correlationKey: key } : {}
   };
 }
 var encodePayload = (request) => [
@@ -94,7 +150,11 @@ var encodePayload = (request) => [
   normalizeSound(request.sound),
   // The sixth field, empty when there is no request id: an absent id and an
   // empty one mean the same thing, and the field count never changes.
-  safeRequestId(request.requestID) ?? ""
+  safeRequestId(request.requestID) ?? "",
+  // The seventh field, the correlation key, empty when there is none. The
+  // `close:` marker of a close request is part of the key and travels with
+  // it, so the far end closes instead of raising.
+  wireCorrelationKey(request.correlationKey)
 ].join(FIELD_SEPARATOR);
 var SSH_OPTS = [
   "-o",
@@ -114,11 +174,16 @@ var CONTROL_OPTS = [
   "-o",
   "ControlPersist=300",
   "-o",
-  `ControlPath=${join2(homedir(), ".ssh", "lacode-cm-%C")}`
+  `ControlPath=${join4(homedir3(), ".ssh", "lacode-cm-%C")}`
 ];
-var run = (command, args, timeout) => {
+var run = (command, args, timeout, extraEnv) => {
   try {
-    const result = spawnSync(command, args, { timeout, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    const result = spawnSync(command, args, {
+      timeout,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      ...extraEnv ? { env: { ...process.env, ...extraEnv } } : {}
+    });
     return {
       ok: result.status === 0,
       stdout: result.stdout ?? "",
@@ -178,20 +243,104 @@ var NO_CHANNEL = {
   darwin: "neither osascript nor terminal-notifier is installed"
 };
 var NEVER_EXPIRE_FLAG = "--expire-time=0";
+var APP_NAME_FLAG = "--app-name=LaCode";
 var NOTIFICATION_ACTIONS = [
   ["once", "Allow once"],
   ["always", "Always allow"],
   ["reject", "Deny"]
 ];
 var ACTION_WAIT_MS = 10 * 6e4;
+var isNotificationId = (id) => /^\d+$/.test(id);
+var recordNotificationId = (correlationKey, id) => {
+  if (!isNotificationId(id)) return false;
+  try {
+    mkdirSync3(notificationStateDir(), { recursive: true });
+    appendFileSync(notificationIdFile(correlationKey), `${id}
+`, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+};
+var sessionBusEnv = () => {
+  if (process.env.DBUS_SESSION_BUS_ADDRESS) return {};
+  const uid = typeof process.getuid === "function" ? process.getuid() : void 0;
+  return uid === void 0 ? {} : { DBUS_SESSION_BUS_ADDRESS: `unix:path=/run/user/${uid}/bus` };
+};
+var CLOSE_TIMEOUT_MS = 5e3;
+function closeNotification(id) {
+  if (!isNotificationId(id)) return false;
+  const env = sessionBusEnv();
+  const viaGdbus = run(
+    "gdbus",
+    [
+      "call",
+      "--session",
+      "--dest",
+      "org.freedesktop.Notifications",
+      "--object-path",
+      "/org/freedesktop/Notifications",
+      "--method",
+      "org.freedesktop.Notifications.CloseNotification",
+      id
+    ],
+    CLOSE_TIMEOUT_MS,
+    env
+  );
+  if (viaGdbus.ok) return true;
+  const viaDbusSend = run(
+    "dbus-send",
+    [
+      "--session",
+      "--dest=org.freedesktop.Notifications",
+      "--type=method_call",
+      "/org/freedesktop/Notifications",
+      "org.freedesktop.Notifications.CloseNotification",
+      `uint32:${id}`
+    ],
+    CLOSE_TIMEOUT_MS,
+    env
+  );
+  return viaDbusSend.ok;
+}
+function closeCorrelationKey(correlationKey) {
+  const file = notificationIdFile(correlationKey);
+  let content = "";
+  try {
+    content = readFileSync4(file, "utf8");
+  } catch {
+    return true;
+  }
+  let closed = true;
+  for (const line of content.split("\n")) {
+    const id = line.trim();
+    if (!isNotificationId(id)) continue;
+    if (!closeNotification(id)) closed = false;
+  }
+  try {
+    unlinkSync3(file);
+  } catch {
+  }
+  return closed;
+}
+var splitNotifyOutput = (stdout) => {
+  const newline = stdout.indexOf("\n");
+  if (newline === -1) return { id: stdout.trim(), action: "" };
+  return { id: stdout.slice(0, newline).trim(), action: stdout.slice(newline + 1).trim() };
+};
 function sendLocal(request, platform = process.platform) {
+  const closing = closeRequestTarget(request.correlationKey);
+  if (closing !== void 0) {
+    const closed = closeCorrelationKey(closing);
+    return { ok: closed, detail: closed ? void 0 : "a popup could not be closed", transport: "local" };
+  }
   const sound = normalizeSound(request.sound);
   const playSound = () => {
     if (sound === "none") return;
     const channel2 = soundChannel(platform);
     if (channel2 === "none") return;
-    const path = join2(PACKAGE_ROOT, "sounds", `${sound}.wav`);
-    if (!existsSync(path)) return;
+    const path = join4(PACKAGE_ROOT, "sounds", `${sound}.wav`);
+    if (!existsSync2(path)) return;
     const child = spawn(channel2, [path], { detached: true, stdio: "ignore" });
     child.on("error", () => {
     });
@@ -207,13 +356,17 @@ function sendLocal(request, platform = process.platform) {
   const requestID = safeRequestId(request.requestID);
   const actionable = channel === "notify-send" && requestID !== void 0;
   const actionArgs = actionable ? NOTIFICATION_ACTIONS.map(([name, label]) => `--action=${name}=${label}`) : [];
+  const correlationKey = presentCorrelationKey(request.correlationKey);
+  const trackable = channel === "notify-send" && correlationKey !== void 0;
   const args = channel === "osascript" ? ["-e", DARWIN_SCRIPT, DARWIN_ARGV_MARKER, title, body] : channel === "terminal-notifier" ? ["-title", title, "-message", body, "-appName", "LaCode", "-priority", normalizeUrgency(request.urgency)] : (
     // Never auto-dismissed: the notification waits for the user to close it.
-    [title, body, `--urgency=${normalizeUrgency(request.urgency)}`, `--icon=${normalizeIcon(request.icon)}`, NEVER_EXPIRE_FLAG, ...actionArgs]
+    [title, body, APP_NAME_FLAG, `--urgency=${normalizeUrgency(request.urgency)}`, `--icon=${normalizeIcon(request.icon)}`, NEVER_EXPIRE_FLAG, ...trackable ? ["--print-id"] : [], ...actionArgs]
   );
   const result = run(CHANNEL_BINARY[channel], args, actionable ? ACTION_WAIT_MS : 5e3);
   playSound();
-  const action = actionable ? result.stdout.trim() : "";
+  const printed = trackable ? splitNotifyOutput(result.stdout) : { id: "", action: result.stdout.trim() };
+  const action = actionable ? printed.action : "";
+  if (correlationKey !== void 0 && printed.id) recordNotificationId(correlationKey, printed.id);
   return {
     ok: result.ok,
     detail: result.ok ? void 0 : result.stderr || result.detail,
@@ -262,7 +415,17 @@ function sendRemote(request, tunnel) {
 }
 function notify(request, env = process.env, platform = process.platform) {
   try {
-    const result = isRemote(env) ? sendRemote(request, resolveTunnel(env)) : sendLocal(request, platform);
+    const closeKey = (env[NOTIFY_CLOSE_ENV] ?? "").trim();
+    if (closeKey) {
+      if (!isRemote(env)) {
+        const closed = closeCorrelationKey(closeKey);
+        return { ok: closed, detail: closed ? void 0 : "a popup could not be closed", transport: "local" };
+      }
+      return sendRemote({ ...request, correlationKey: `${CLOSE_REQUEST_PREFIX}${closeKey}` }, resolveTunnel(env));
+    }
+    const sessionKey = presentCorrelationKey(env[NOTIFY_SESSION_ENV]);
+    const tracked = sessionKey ? { ...request, correlationKey: request.correlationKey ?? sessionKey } : request;
+    const result = isRemote(env) ? sendRemote(tracked, resolveTunnel(env)) : sendLocal(tracked, platform);
     return result.action ? { ...result, action: result.action } : result;
   } catch (error) {
     return { ok: false, detail: String(error), transport: "none" };
@@ -294,21 +457,30 @@ function describe(env = process.env, platform = process.platform) {
   };
 }
 export {
+  CLOSE_REQUEST_PREFIX,
   FIELD_SEPARATOR,
   ICONS,
   NOTIFICATION_ACTIONS,
   SOUNDS,
+  closeCorrelationKey,
+  closeNotification,
+  closeRequestTarget,
   describe,
   encodePayload,
   forward,
+  isCloseRequest,
+  isNotificationId,
   isRemote,
   localChannel,
   normalizeIcon,
   normalizeSound,
   normalizeUrgency,
+  notificationIdFile,
+  notificationStateDir,
   notify,
   parsePayload,
   resolveTunnel,
+  safeCorrelationKey,
   safeMessage,
   safeRequestId,
   safeTitle,

package/docs/CONFIGURATION.md

@@ -7,13 +7,16 @@ The plugin options, where the model pool gets its slots, and exactly what LaCode
 The slot list is the first of these that yields usable slots:
 
 1. plugin options — `models` in the [tuple](../README.md#configure)
-2. `~/.config/lacode/pool.json` (its parent directory is created for you)
-3. the bundled `presets/free-tier.json`
-4. a built-in fallback, so routing always works
+2. `~/.config/lacode/pool.txt` — flat `model [weight]` per line, preferred
+3. `~/.config/lacode/pool.json` (its parent directory is created for you)
+4. the bundled `presets/free-tier.json`
+5. a built-in fallback, so routing always works
 
 A missing, unreadable or structurally broken source falls through to the next and
-logs one warning; nothing here throws into opencode. Nothing hot-reloads —
-change a preset, then restart every opencode process.
+logs one warning; nothing here throws into opencode. Sources 2–4 are watched: a
+change reloads the slot table, re-binds the variant agents and validates every
+slot (one real request per model) without a restart. Only a change to the
+plugin's own code needs one.
 
 **Any model list is accepted, including paid ones** (US-7). There is no free-tier
 allowlist anywhere in the package, and no cost check of any kind: only the
@@ -69,8 +72,19 @@ Note that you cannot *spawn* a variant by name: the pool refuses
 `explore-1` and friends and points you at the bare base, so per-variant
 permissions only ever apply to a spawn the plugin routed itself.
 
-Nothing hot-reloads: after editing your config, restart every running opencode
-process.
+The pool files are the exception to the restart rule: editing `pool.txt`,
+`pool.json` or the bundled preset is picked up live — the table reloads, the
+variant agents re-bind and every slot is validated. A change to `opencode.jsonc`
+itself, or to the plugin's code, still needs a restart.
+
+**The delegation path matters.** The pool routes `task` tool calls whose
+`subagent_type` is `explore`, `implement` or `context`. A spawn with no
+`subagent_type`, an `@explore`/`@implement` mention, or a direct session prompt
+naming a base agent does not pass through that hook: it runs opencode's
+default/subagent path and inherits the caller's model. Spawn the bare base
+through the task tool (`subagent_type: "explore"`), not by mention or variant
+name. The plugin logs a warning for the no-`subagent_type` case; the
+mention/direct-session case cannot be detected before it runs.
 
 
 ## What gets injected

package/docs/OMNIROUTE.md

@@ -104,7 +104,7 @@ work (exploration, implementation, cartography) through the gateway, add an
 # ~/.config/lacode/pool.txt
 omniroute/free-mix
 opencode/big-pickle
-opencode-go/minimax-m3.1-flash-free
+opencode-go/beam-free
 ```
 
 OmniRoute is a provider like any other: the pool decides its place and weight,

package/docs/USER-STORIES.md

@@ -115,7 +115,7 @@ The reconciliation with US-7 is that **acceptance and endorsement are different
 - [ ] Given claims are held by several processes, When the status view is requested, Then it shows every process's claims and the aggregate load per slot.
 - [ ] Given a model is cooling with a stated reason, When the status view is requested, Then the model is listed as cooling together with that reason.
 - [ ] Given a claim file is older than the dead-file threshold, When the status view is computed, Then the stale claim is pruned rather than counted.
-- [ ] Given a slot is at its ceiling, When the status view is requested, Then it is not marked as the slot the next spawn would take, because the rotation's turns are skipped for a full slot until it frees a claim.
+- [ ] Given a slot is at its ceiling, When the status view is requested, Then it is not marked as the slot the next spawn would take, because the rotation's turns are skipped for a full slot until it frees a claim — unless no other slot is available and under its ceiling, in which case that full slot is the next one.
 
 ### US-7: Non-free models still work
 **As a** user who wants a paid model in the pool, **I want** to supply any model list, **so that** the pool is not restricted to free tiers.
@@ -151,6 +151,23 @@ does not.
 - [ ] Given OmniRoute is disabled, enabled with an invalid block, unhealthy, or returns no usable models, When the config hook runs, Then no provider is registered, no pool slot changes, and a failure is warned about once.
 - [ ] Given the gateway is unreachable, When pooled work runs, Then the only thing affected is a slot that names `omniroute/<model>`; every other slot keeps working, because the plugin never put an `omniroute` slot in the pool.
 
+### US-31: A limit that hangs is killed, and the retry lands on a slot that answers
+**As a** user whose provider has run out of allowance, **I want** the stalled task killed and the retry sent to a slot that is not on cooldown, **so that** one exhausted provider does not strand the session.
+
+A limit does not always arrive as an error. Sometimes the provider accepts the request and then says nothing, and opencode keeps retrying the refused model — so the task is neither done nor failed, and the session waits on a provider that has already said no. The plugin has to end that wait itself: abort the stalled session, cool the model that was refused, and let the retry pick a slot that answers. When the provider names itself, the whole provider is benched; when it does not, only the model the session was running on is cooled — that is the one the refusal is evidence about.
+
+**Story ID(s) for tests:** US-31
+**Acceptance criteria:**
+- [ ] Given a pooled session's provider reports a limit in a retry status that names no provider, When the status is handled, Then the model that session is running on is cooled and a cooldown file is written for it.
+- [ ] Given a pooled session reports a limit and then goes silent, When the limit is handled, Then that session is aborted and its claim is released, so the slot is not held by a task that will never answer.
+- [ ] Given the refused model is cooling, When the caller retries the spawn, Then the retry is routed to a different slot whose model is not on cooldown.
+- [ ] Given a limit names its provider, When the limit is handled, Then every slot on that provider is cooled and a slot on another provider is not.
+- [ ] Given a limit-shaped error whose text is exactly `limit reached` and which carries no status code, When the error is matched, Then the model is cooled and the in-flight session is aborted.
+- [ ] Given an error whose text is `context limit reached`, When the error is matched, Then nothing is cooled and nothing is aborted, because a prompt that is too long is not a provider quota.
+- [ ] Given a session stalls with no limit signal at all, When the reaper sweeps, Then the session is aborted, its model cooled, and the next spawn routes to a slot that is not on cooldown.
+- [ ] Given a provider reports a transient upstream outage rather than a limit, When the status is handled, Then the model is cooled for one short flat window instead of the quota window, and the session is still aborted, because an outage lifts on its own and must not bench a healthy model.
+- [ ] Given a transient outage was cooled, When the same model later fails with a real limit, Then the cooldown starts at the first strike rather than an escalated one, because an outage lifts on its own and must not make the next quota window longer.
+
 ---
 
 ## Epic C — Hang detection and auto-recovery
@@ -240,6 +257,22 @@ does not.
 - [ ] Given the plugin option `sound` is `false`, or `LACODE_SOUND` is `0`, `false`, `off` or `no`, When a notification is delivered, Then its sound is `none`; when both are set the environment wins over the option, and any other value — a typo included — leaves sound on, because a misspelt variable must not be how you get silence.
 - [ ] Given a sound name that is not one of `none`, `done`, `question`, `permission` or `error`, When it arrives, Then it is treated as `none` and never becomes a path or a command, because the hop carries data only (see US-18).
 
+### US-30: A notification fades once you are working in that chat
+**As a** user with several sessions open, **I want** the popup of the session I am working in to close itself, **so that** a notice I have already dealt with stops sitting on my screen waiting for an X I was never going to press.
+
+A popup the user is already looking past has said everything it is going to say: once they answer the permission, answer the question, or type into that session's chat, the answer is on their screen already. So the popup fades on its own — but never sooner than five seconds after it was raised, because a notice nobody could read is no notice, and a popup nobody touched still waits for them, exactly as before.
+
+The popup belongs to its session: working in one chat closes that chat's popup and no other. The close is the **helper's** job, never the plugin's, because the popup lives on the desktop and only the desktop knows the notification id the daemon gave it. One code path, two topologies: the helper closes locally, or over the hop where the popup was actually raised.
+
+**Story ID(s) for tests:** US-30
+**Acceptance criteria:**
+- [ ] Given a notification has been delivered, When the user answers a permission, answers a question, or types into that session's chat, Then that session's notification closes by itself, without the user clicking the popup's close button.
+- [ ] Given a notification was delivered less than five seconds ago, When the user works in that chat, Then the notification stays until five seconds have passed, because a notice nobody could read is no notice.
+- [ ] Given the user works in one session's chat, When another session still has a popup up, Then that popup stays: a notification belongs to its session, and only that session's user is looking at it.
+- [ ] Given the user never works in that chat, When the notification was delivered, Then it stays until the user closes it, exactly as before.
+- [ ] Given a permission popup is closed this way, When the permission was already answered in the terminal, Then nothing is answered twice: the close takes the popup down and answers nothing.
+- [ ] Given the notification was delivered by a session on a remote host and reached the desktop over the tunnel, When the user works in that chat, Then the popup on the desktop closes too, because the popup lives on the desktop and only the desktop knows its notification id.
+
 ---
 
 ## Epic E — Remote hosts over SSH
@@ -380,7 +413,7 @@ agents read it before they explore, then keeps it current on its own.
 **Acceptance criteria:**
 - [ ] Given a config that defines none of LaCode's agents, When the config hook runs, Then a `context` subagent is injected, and it carries no model of its own, because the pool is the only thing that decides which model runs it.
 - [ ] Given the injected agent set, When the slot variants are built, Then a hidden `context-<slot>` variant exists for every slot the pool can hand out, so a cartography run borrows shared capacity instead of a dedicated model.
-- [ ] Given a user config with no `instructions` array, When the config hook runs, Then the standing context-map rule is injected, naming all five map files, telling the agent to check with `ls` and never the `glob` tool, to read only the file relevant to the task, and to start from the canonical entry points the map lists.
+- [ ] Given the shipped agent prompts and the context agent, When they are inspected, Then they carry the standing context-map rule — naming all five map files, checking with `ls` and never the `glob` tool, reading only the file relevant to the task, and starting from the canonical entry points the map lists — because that rule now lives in the repo-level `AGENTS.md` rather than being injected into the user's `instructions` array.
 - [ ] Given the injected `context`, When its prompt is inspected, Then it names the five files it owns, requires a short "Start here" list of canonical files per significant subsystem, and forbids file inventories — the map answers "what should I look at first?", never "tell me everything".
 
 ### US-20: The map stays current without being asked
@@ -424,10 +457,49 @@ Enforcement is split deliberately, and the split matters: **what the permission
 
 ---
 
+## Epic H — Retention (sweeps)
+
+### US-32: Retire old sessions
+**As an** opencode user whose session list only ever grows, **I want** a sweep that retires sessions past a retention window together with everything that belongs to them, **so that** the database stays usable and I keep a compact record of what went.
+
+**Story ID(s) for tests:** US-32
+**Acceptance criteria:**
+- [ ] Given sessions whose `time_created` is older than `--days` (default 30) and whose `time_updated` is older than `--grace-hours` (default 24), When the sweep runs, Then those sessions are retired together with their messages, parts, todos, shares, inputs, context epochs and event rows.
+- [ ] Given a session that is old but was touched inside the grace window, When the sweep runs, Then it is left alone, because the grace window is a stop, not a speed.
+- [ ] Given an old parent session with a child, When the sweep runs, Then the child is retired together with the parent, so no orphan remains.
+- [ ] Given `--directory D`, When the sweep runs, Then only sessions rooted in that directory are selected, and a child in another directory goes with its parent.
+- [ ] Given `--limit N`, When the sweep runs, Then at most N top-level sessions (with their descendants) are retired.
+- [ ] Given `--dry-run`, When the sweep runs, Then it reports what would go and changes nothing on disk.
+- [ ] Given `--no-events`, When the sweep runs, Then the event rows of the retired sessions are kept.
+- [ ] Given `--vacuum`, When the sweep runs, Then the database is rewritten afterwards so the freed pages go back to the filesystem.
+- [ ] Given sessions are retired, When the sweep completes, Then a compact record (id, title, directory, project, created, updated) is written under the session archive, which is the recovery path.
+
+### US-33: Prune the event log
+**As an** opencode user whose `event` table grows without bound, **I want** a sweep that deletes event rows older than a window except those belonging to protected sessions, **so that** the database stops growing while the transcript and sync stay intact.
+
+**Story ID(s) for tests:** US-33
+**Acceptance criteria:**
+- [ ] Given event rows whose id is older than `--days` (default 7), When the sweep runs, Then those rows are candidates and newer rows are not, because the id carries the row's creation time.
+- [ ] Given a session that takes part in session sync (`event_sequence.owner_id` set), When the sweep runs, Then none of its event rows are pruned.
+- [ ] Given a session that belongs to a workspace, When the sweep runs, Then none of its event rows are pruned.
+- [ ] Given a session touched inside the grace window (`--grace-hours`, default 1), When the sweep runs, Then all of its event rows are kept.
+- [ ] Given an event whose session row is gone, When the sweep runs, Then that event is pruned, because it is garbage.
+- [ ] Given `--dry-run`, When the sweep runs, Then it reports the counts and deletes nothing, and still writes one JSON line to the run log.
+- [ ] Given `--limit N`, When the sweep runs, Then at most N rows are deleted, oldest first, and the remainder is reported for a later run.
+- [ ] Given a window longer than the id era, When the sweep runs, Then the window is clamped to the era and the table is not wiped, and the operator is warned.
+- [ ] Given candidate rows, When they are deleted, Then deletion happens in chunks and a failure mid-run leaves the rest for a later run.
+- [ ] Given `--vacuum` (and not `--dry-run`), When the sweep runs, Then the database is rewritten afterwards.
+- [ ] Given the sweep runs, When it completes, Then the `event_sequence` and `session` tables are never changed.
+- [ ] Given a run, When it completes, Then one JSON line is appended to `~/.local/share/opencode/lacode/event-prune.jsonl` carrying ts, days, graceHours, cutoff, rows, bytes, aggregates, dryRun and elapsedMs.
+
+---
+
 ## Coverage
 
-Every story below has at least one behavioural test in `tests/stories/`, and
-`tests/stories/coverage.test.mjs` enforces that mechanically in both directions:
+Every story below has at least one behavioural test. The story suites live in
+`tests/stories/`, and the root-level suites `tests/*-test.mjs` are scanned too
+(US-32, US-33), so `tests/stories/coverage.test.mjs` enforces coverage in both
+directions:
 it fails if a story here has no test, and it fails if a test names a story this
 document does not define. The acceptance criteria above are unchanged; only this
 table was filled in.
@@ -443,6 +515,7 @@ table was filled in.
 | US-6 | B | `tests/stories/b-provider-resilience.test.mjs` |
 | US-7 | B | `tests/stories/b-provider-resilience.test.mjs`, `tests/pool-models-test.mjs` |
 | US-28 | B | `tests/stories/i-omniroute.test.mjs` |
+| US-31 | B | `tests/stories/b-provider-resilience.test.mjs`, `tests/stories/c-hang-recovery.test.mjs` |
 | US-8 | C | `tests/stories/c-hang-recovery.test.mjs`, `tests/pool-hang-test.mjs` |
 | US-9 | C | `tests/stories/c-hang-recovery.test.mjs`, `tests/pool-hang-test.mjs`, `tests/pool-shared-test.mjs` |
 | US-10 | C | `tests/stories/c-hang-recovery.test.mjs`, `tests/pool-hang-test.mjs`, `tests/pool-timer-test.mjs` |
@@ -450,6 +523,7 @@ table was filled in.
 | US-12 | D | `tests/stories/d-notifications.test.mjs`, `tests/notify-test.mjs` |
 | US-25 | D | `tests/stories/d-notifications.test.mjs` |
 | US-29 | D | `tests/stories/d-notifications.test.mjs` |
+| US-30 | D | `tests/stories/d-notifications.test.mjs`, `tests/stories/e-remote-ssh.test.mjs`, `tests/oc-test.mjs` |
 | US-13 | E | `tests/stories/e-remote-ssh.test.mjs`, `tests/notify-test.mjs`, `tests/oc-test.mjs` |
 | US-14 | E | `tests/stories/e-remote-ssh.test.mjs`, `tests/oc-test.mjs` |
 | US-18 | E | `tests/stories/e-remote-ssh.test.mjs`, `tests/oc-test.mjs` |
@@ -463,10 +537,15 @@ table was filled in.
 | US-20 | G | `tests/stories/g-context-management.test.mjs` |
 | US-21 | G | `tests/stories/g-context-management.test.mjs`, `tests/permission-test.mjs` |
 | US-22 | G | `tests/stories/g-context-management.test.mjs` |
+| US-32 | H | `tests/retire-old-sessions-test.mjs` |
+| US-33 | H | `tests/prune-old-events-test.mjs` |
 
 The nine suites under `tests/` are unit-style; the `tests/stories/` suites are
 the behavioural layer, written one epic per file with every test name carrying
 its story id. Run everything with `npm test`.
 
-**No story is uncovered.** US-1, US-2, US-3, US-6, and all of epic F have tests,
-and the coverage guard fails the build if any of them loses one.
+**No story is uncovered.** The guard reports 33 stories, 325 test cases, and
+33/33 stories with at least one behavioural test; US-1, US-2, US-3, US-6, and
+all of epic F have tests, and the coverage guard fails the build if any of them
+loses one. The scan covers the `tests/stories/` suites and the root-level
+`tests/*-test.mjs` suites.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawaty/lacode",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",

package/presets/README.md

@@ -26,8 +26,9 @@ file in without `mkdir` first.
 Sources 1 and 2 win outright: if they parse, the bundled preset is never read.
 Source 3 is a default, not a floor.
 
-Nothing is hot-reloaded. Change a preset, then restart every running opencode
-process.
+The pool files are not frozen at startup: the running process watches them,
+reloads the slot table, re-binds the variant agents and validates every slot, so a
+change here takes effect without a restart. Plugin CODE still needs one.
 
 ## The flat pool file (recommended)
 
@@ -37,7 +38,7 @@ in place, no JSON and no objects:
 ```text
 # provider/model-id                       weight
 opencode/big-pickle                       3
-opencode-go/minimax-m3.1-flash-free       2
+opencode-go/beam-free       2
 opencode/deepseek-v4.1-flash-free         1
 opencode/glm-5.3-flash-free               1
 ```

package/presets/free-tier.json

@@ -26,7 +26,7 @@
     "  3. once EVERY slot is at its ceiling, the overflow goes to the least loaded slot,",
     "     so a burst past the summed ceilings degrades to even spreading and never blocks",
     "",
-    "With this file: big-pickle takes 3 consecutive turns, then minimax-m3.1-flash-free",
+    "With this file: big-pickle takes 3 consecutive turns, then beam-free",
     "(opencode-go) takes 2, then deepseek-v4.1-flash-free and glm-5.3-flash-free take 1",
     "each -- sequence 1,1,1,2,2,3,4,...",
     "Equal weights give a plain round robin in list order. 2,2,1,1 reproduces the old",
@@ -80,11 +80,11 @@
     "Re-check any model you substitute against models.dev; this project does not look prices",
     "up at runtime and will not guess at them for you.",
     "",
-    "Changing this file requires restarting every opencode process: plugins are not hot-reloaded."
+    "Changing this file is picked up live: the pool watches its sources, reloads the slot table and validates every slot. A restart is only needed for plugin CODE, not for a pool edit."
   ],
   "slots": [
     { "model": "opencode/big-pickle", "weight": 3 },
-    { "model": "opencode-go/minimax-m3.1-flash-free", "weight": 2 },
+    { "model": "opencode-go/beam-free", "weight": 2 },
     { "model": "opencode/deepseek-v4.1-flash-free", "weight": 1 },
     { "model": "opencode/glm-5.3-flash-free", "weight": 1 }
   ]