@lawaty/lacode 2.3.0-beta.5 → 2.3.0-beta.6

package/dist/lacode.js

@@ -60,6 +60,7 @@ 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 TRANSIENT_UPSTREAM_COOLDOWN_MS = 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");

package/dist/pool.js

@@ -45,9 +45,10 @@ var PROVIDER_DEGRADED_MIN_MODELS = 2;
 var TRANSIENT_DEGRADATION_REASONS = /^(?:no answer|no-answer|hang|timeout|timed out|endpoint-unavailable|provider-degraded|empty response|network|server)$/i;
 var FLAT_OUTAGE_REASONS = /* @__PURE__ */ new Set([UNAVAILABLE_REASON, PROVIDER_DEGRADED_REASON]);
 var MAX_WEIGHT = 100;
+var MAX_CEILING = MAX_WEIGHT;
 var MIN_SLOT_CONTEXT = 1e5;
 var MIN_SLOT_TPM = 2e4;
-var slotCeiling = (slot) => slot.weight;
+var slotCeiling = (slot) => slot.ceiling ?? slot.weight;
 var slotBucket = (slot) => slot.bucket ?? slot.model;
 var NOTIFY_DEFAULT_ON_PROVIDERS = /* @__PURE__ */ new Set(["opencode", "opencode-go"]);
 var notifyDefault = (model) => {
@@ -67,7 +68,7 @@ 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 STATED_COOLDOWN_MAX_MS = QUOTA_COOLDOWN_MAX_MS;
-var isQuotaReason = (reason) => /quota|limit|rate|too-many|overloaded|429/i.test(reason);
+var isQuotaReason = (reason) => /quota|limit|rate|too-many|overloaded|budget|429/i.test(reason);
 var MODEL_MISSING_REASON = "model-missing";
 var MODEL_MISSING_COOLDOWN_MS = QUOTA_COOLDOWN_MAX_MS;
 var AUTH_FAILURE_REASON = "auth-failed";
@@ -76,6 +77,16 @@ var MODEL_MISSING_PATTERN = /model\s+(?:not\s+found|does\s+not\s+exist|is\s+not\
 var isModelMissingText = (text) => MODEL_MISSING_PATTERN.test(text);
 var AUTH_FAILURE_PATTERN = /\b401\b|\b403\b|unauthori[sz]ed|not\s+authori[sz]ed|invalid[\s_-]+(?:api[\s_-]?(?:key|token)|token|credential|bearer)|api[\s_-]?key\s+(?:is\s+)?(?:invalid|missing|expired|not\s+valid)|authentication\s+(?:failed|error|required)|incorrect[\s_-]+api[\s_-]?key/i;
 var isAuthFailureText = (text) => AUTH_FAILURE_PATTERN.test(text);
+var ABORT_PATTERN = /MessageAbortedError|"name"\s*:\s*"[^"]*Abort/i;
+var isAbortText = (text) => ABORT_PATTERN.test(text);
+var INVALID_REQUEST_REASON = "invalid-request";
+var INVALID_REQUEST_COOLDOWN_MS = MODEL_MISSING_COOLDOWN_MS;
+var UNSUPPORTED_PARAMETER_PATTERN = /not\s+a\s+supported\s+value|unsupported\s+(?:value|parameter|field)|(?:invalid|unknown)\s+(?:value|parameter)\s+for|is\s+not\s+supported/i;
+var isUnsupportedParameterText = (text) => UNSUPPORTED_PARAMETER_PATTERN.test(text);
+var TRANSIENT_UPSTREAM_REASON = "upstream-transient";
+var TRANSIENT_UPSTREAM_COOLDOWN_MS = 60 * 1e3;
+var TRANSIENT_UPSTREAM_PATTERN = /reasoning_display/i;
+var isTransientUpstreamText = (text) => TRANSIENT_UPSTREAM_PATTERN.test(text);
 var BASES = ["explore", "implement", "context"];
 var LEARNED_TPM_FILE = "learned-tpm.json";
 var PRESETS_DIR = join2(PACKAGE_ROOT, "presets");
@@ -102,64 +113,100 @@ var coerceNotify = (raw, at, model, problems) => {
   problems.push(`${at} (${model}): notify must be a boolean or one of on/off, got ${JSON.stringify(raw)}; keeping the provider default`);
   return notifyDefault(model);
 };
+var FALLBACK_MARKER = /^(?:#\s*-*\s*fallback(?:\s+slots)?\s*-*|\[fallback\])$/i;
+var isFallbackMarker = (line) => FALLBACK_MARKER.test(String(line).trim());
+function parseSlotEntry(entry, at, problems) {
+  const model = typeof entry?.model === "string" ? entry.model.trim() : "";
+  if (!model.includes("/")) {
+    problems.push(`${at}: model must be written provider/model-id, got "${model}"`);
+    return void 0;
+  }
+  const weight = readWeight(entry, at, model, problems);
+  const ceiling = readCeiling(entry, weight, at, model, problems);
+  const rawBucket = entry?.bucket;
+  const bucket = typeof rawBucket === "string" ? rawBucket.trim() : void 0;
+  if (rawBucket !== void 0 && !bucket) {
+    problems.push(`${at} (${model}): bucket must be a non-empty name; using the model id`);
+  }
+  const notify = coerceNotify(entry.notify, at, model, problems);
+  const rawContext = entry?.context;
+  let context;
+  if (rawContext !== void 0) {
+    const parsedContext = typeof rawContext === "number" ? rawContext : Number(rawContext);
+    if (Number.isFinite(parsedContext) && parsedContext > 0) context = parsedContext;
+    else problems.push(`${at} (${model}): context must be a positive number, got ${JSON.stringify(rawContext)}; ignoring it`);
+  }
+  if (context !== void 0 && context < MIN_SLOT_CONTEXT) {
+    problems.push(`${at} (${model}): context ${context} is below the ${MIN_SLOT_CONTEXT}-token minimum; dropping the slot`);
+    return void 0;
+  }
+  const rawTpm = entry?.tpm;
+  let tpm;
+  if (rawTpm !== void 0) {
+    const parsedTpm = typeof rawTpm === "number" ? rawTpm : Number(rawTpm);
+    if (Number.isFinite(parsedTpm) && parsedTpm > 0) tpm = parsedTpm;
+    else problems.push(`${at} (${model}): tpm must be a positive number, got ${JSON.stringify(rawTpm)}; ignoring it`);
+  }
+  if (tpm !== void 0 && tpm < MIN_SLOT_TPM) {
+    problems.push(`${at} (${model}): tpm ${tpm} is below the ${MIN_SLOT_TPM}-token/minute minimum; dropping the slot`);
+    return void 0;
+  }
+  return { index: 0, model, weight, ...ceiling === void 0 ? {} : { ceiling }, ...bucket ? { bucket } : {}, notify, ...context === void 0 ? {} : { context }, ...tpm === void 0 ? {} : { tpm } };
+}
 function parseSlots(parsed, origin) {
   const problems = [];
-  const entries = parsed?.slots;
-  if (!Array.isArray(entries) || entries.length === 0) {
+  const primaryEntries = parsed?.slots;
+  const fallbackEntries = parsed?.fallbackSlots;
+  if ((!Array.isArray(primaryEntries) || primaryEntries.length === 0) && (!Array.isArray(fallbackEntries) || fallbackEntries.length === 0)) {
     return { slots: FALLBACK_SLOTS, problems: [`${origin} has no non-empty "slots" array; using built-in defaults`] };
   }
-  const slots = [];
-  entries.forEach((entry, i) => {
-    const model = typeof entry?.model === "string" ? entry.model.trim() : "";
-    const at = `slot ${i + 1}`;
-    if (!model.includes("/")) return problems.push(`${at}: model must be written provider/model-id, got "${model}"`);
-    const weight = readWeight(entry, at, model, problems);
-    const rawBucket = entry?.bucket;
-    const bucket = typeof rawBucket === "string" ? rawBucket.trim() : void 0;
-    if (rawBucket !== void 0 && !bucket) {
-      problems.push(`${at} (${model}): bucket must be a non-empty name; using the model id`);
-    }
-    const notify = coerceNotify(entry.notify, at, model, problems);
-    const rawContext = entry?.context;
-    let context;
-    if (rawContext !== void 0) {
-      const parsedContext = typeof rawContext === "number" ? rawContext : Number(rawContext);
-      if (Number.isFinite(parsedContext) && parsedContext > 0) context = parsedContext;
-      else problems.push(`${at} (${model}): context must be a positive number, got ${JSON.stringify(rawContext)}; ignoring it`);
-    }
-    if (context !== void 0 && context < MIN_SLOT_CONTEXT) {
-      problems.push(`${at} (${model}): context ${context} is below the ${MIN_SLOT_CONTEXT}-token minimum; dropping the slot`);
-      return;
-    }
-    const rawTpm = entry?.tpm;
-    let tpm;
-    if (rawTpm !== void 0) {
-      const parsedTpm = typeof rawTpm === "number" ? rawTpm : Number(rawTpm);
-      if (Number.isFinite(parsedTpm) && parsedTpm > 0) tpm = parsedTpm;
-      else problems.push(`${at} (${model}): tpm must be a positive number, got ${JSON.stringify(rawTpm)}; ignoring it`);
-    }
-    if (tpm !== void 0 && tpm < MIN_SLOT_TPM) {
-      problems.push(`${at} (${model}): tpm ${tpm} is below the ${MIN_SLOT_TPM}-token/minute minimum; dropping the slot`);
-      return;
+  const parseList = (list, fallback2) => {
+    if (!Array.isArray(list)) return [];
+    const out = [];
+    list.forEach((entry, i) => {
+      const slot = parseSlotEntry(entry, `${fallback2 ? "fallback slot" : "slot"} ${i + 1}`, problems);
+      if (slot) out.push({ ...slot, ...fallback2 ? { fallback: true } : {} });
+    });
+    return out;
+  };
+  const primary = parseList(primaryEntries, false);
+  let fallback = parseList(fallbackEntries, true);
+  const primaryBuckets = new Set(primary.map((slot) => slotBucket(slot)));
+  const primaryModels = new Set(primary.map((slot) => slot.model));
+  fallback = fallback.filter((slot) => {
+    const shared = primaryModels.has(slot.model) || primaryBuckets.has(slotBucket(slot));
+    if (shared) {
+      problems.push(
+        `fallback slot (${slot.model}): shares a limit window with the primary pool (${slotBucket(slot)}); dropping it`
+      );
+      return false;
     }
-    slots.push({ index: slots.length + 1, model, weight, ...bucket ? { bucket } : {}, notify, ...context === void 0 ? {} : { context }, ...tpm === void 0 ? {} : { tpm } });
+    return true;
   });
+  const slots = [...primary, ...fallback].map((slot, i) => ({ ...slot, index: i + 1 }));
   if (slots.length > SLOTS_WARN_AT) {
     problems.push(`${origin}: ${slots.length} slots is unusually large, but every entry is kept (the pool has no slot cap)`);
   }
-  if (slots.length === 0) {
-    problems.push(`${origin} yielded no usable slot; using built-in defaults`);
+  if (primary.length === 0) {
+    problems.push(`${origin} yielded no usable primary slot; using built-in defaults`);
     return { slots: FALLBACK_SLOTS, problems };
   }
   return { slots, problems };
 }
 function parseTextSlots(text, origin) {
   const entries = [];
+  const fallbackEntries = [];
+  let section = "primary";
   for (const raw of text.split(/\r?\n/)) {
+    if (isFallbackMarker(raw)) {
+      section = "fallback";
+      continue;
+    }
     const line = raw.split("#")[0].trim();
     if (!line) continue;
     const [model, ...rest] = line.split(/\s+/);
     let weight;
+    let ceiling;
     let bucket;
     let notify;
     let context;
@@ -169,6 +216,13 @@ function parseTextSlots(text, origin) {
         if (notify === void 0) notify = token.slice("notify:".length);
         continue;
       }
+      if (token.startsWith("ceil:")) {
+        if (ceiling === void 0) {
+          const parsedCeiling = Number(token.slice("ceil:".length));
+          if (Number.isFinite(parsedCeiling) && parsedCeiling > 0) ceiling = parsedCeiling;
+        }
+        continue;
+      }
       if (token.startsWith("c:")) {
         if (context === void 0) {
           const parsedContext = Number(token.slice(2));
@@ -189,9 +243,11 @@ function parseTextSlots(text, origin) {
         weight = token;
       }
     }
-    entries.push({ model, ...weight === void 0 ? {} : { weight }, ...bucket === void 0 ? {} : { bucket }, ...notify === void 0 ? {} : { notify }, ...context === void 0 ? {} : { context }, ...tpm === void 0 ? {} : { tpm } });
+    const entry = { model, ...weight === void 0 ? {} : { weight }, ...ceiling === void 0 ? {} : { ceiling }, ...bucket === void 0 ? {} : { bucket }, ...notify === void 0 ? {} : { notify }, ...context === void 0 ? {} : { context }, ...tpm === void 0 ? {} : { tpm } };
+    if (section === "fallback") fallbackEntries.push(entry);
+    else entries.push(entry);
   }
-  return parseSlots({ slots: entries }, origin);
+  return parseSlots({ slots: entries, ...fallbackEntries.length > 0 ? { fallbackSlots: fallbackEntries } : {} }, origin);
 }
 function parseSlotText(text, origin) {
   if (text.trimStart().startsWith("{")) {
@@ -296,6 +352,20 @@ function readWeight(entry, at, model, problems) {
   }
   return weight;
 }
+function readCeiling(entry, weight, at, model, problems) {
+  const raw = entry?.ceiling;
+  if (raw === void 0) return void 0;
+  const ceiling = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(ceiling) || ceiling <= 0 || ceiling > MAX_CEILING) {
+    problems.push(`${at} (${model}): ceiling must be a number in (0, ${MAX_CEILING}], got ${JSON.stringify(raw)}; using the weight`);
+    return void 0;
+  }
+  if (ceiling < weight) {
+    problems.push(`${at} (${model}): ceiling ${ceiling} is below weight ${weight}; using the weight as the ceiling`);
+    return void 0;
+  }
+  return Math.floor(ceiling);
+}
 var UNAVAILABLE_PATTERN = /endpoint\s+is\s+unavailable/i;
 var LIMIT_PATTERNS = [
   /rate[\s_-]?limit/i,
@@ -303,6 +373,7 @@ var LIMIT_PATTERNS = [
   /too many requests/i,
   /\b429\b/,
   /quota/i,
+  /budget\s+exhausted|api\s+budget/i,
   /freelimiterror/i,
   /overloaded/i,
   UNAVAILABLE_PATTERN
@@ -346,7 +417,7 @@ function parseRateLimitHeaders(headers) {
   }
   return void 0;
 }
-var LIMIT_REASON_PATTERN = /rate[\s_-]?limit|usage limit|too many requests|quota|freelimiterror|overloaded|limits?[\s_-]?(?:reached|exceeded)/i;
+var LIMIT_REASON_PATTERN = /rate[\s_-]?limit|usage limit|too many requests|quota|budget\s+exhausted|freelimiterror|overloaded|limits?[\s_-]?(?:reached|exceeded)/i;
 var isLimitText = (text) => LIMIT_PATTERNS.some((re) => re.test(text)) || LIMIT_REACHED_PATTERN.test(text) && !CONTEXT_LIMIT_PATTERN.test(text);
 var limitReason = (text) => {
   if (!isLimitText(text)) return void 0;
@@ -436,7 +507,7 @@ function ensureSlots(s, onWarn) {
   for (const problem of problems) onWarn(problem);
   return slots;
 }
-var slotSignature = (origin, slots) => `${origin}\0${slots.map((slot) => `${slot.index}:${slot.model}:${slot.weight}:${slot.bucket ?? ""}:${slotNotify(slot) ? "1" : "0"}:${slot.tpm ?? ""}`).join("|")}`;
+var slotSignature = (origin, slots) => `${origin}\0${slots.map((slot) => `${slot.index}:${slot.model}:${slot.weight}:${slot.ceiling ?? ""}:${slot.bucket ?? ""}:${slotNotify(slot) ? "1" : "0"}:${slot.tpm ?? ""}:${slot.fallback ? "f" : "p"}`).join("|")}`;
 function reloadSlots(s, onWarn) {
   const { slots, problems, origin } = resolveModels({ models: s.inlineModels, modelsFile: s.modelsFile });
   const effective = applyLearnedTpm(s, slots, onWarn);
@@ -850,52 +921,54 @@ function snapshot(s) {
 }
 var loadOf = (counts, slot) => counts.get(slot) ?? 0;
 var underCeiling = (slot, counts) => loadOf(counts, slot.index) < slotCeiling(slot);
+var fillPassIndex = (slot, counts) => Math.floor(loadOf(counts, slot.index) / Math.max(1, slot.weight));
+var pickByPass = (group, counts, prefer) => {
+  const open = group.filter((slot) => underCeiling(slot, counts));
+  if (open.length === 0) return void 0;
+  const lowest = Math.min(...open.map((slot) => fillPassIndex(slot, counts)));
+  const atPass = open.filter((slot) => fillPassIndex(slot, counts) === lowest);
+  return prefer ? atPass.reduce(prefer, atPass[0]) : atPass[0];
+};
 function pickSlot(s, snap, neededContext) {
   const slots = s.slots.length > 0 ? s.slots : FALLBACK_SLOTS;
-  const usable = slots.filter((slot) => isAvailable(s, slot.model, snap.cooling));
+  const primary = slots.filter((slot) => !slot.fallback);
+  const fallback = slots.filter((slot) => slot.fallback);
+  const usablePrimary = primary.filter((slot) => isAvailable(s, slot.model, snap.cooling));
+  const usable = usablePrimary.length > 0 ? usablePrimary : fallback.filter((slot) => isAvailable(s, slot.model, snap.cooling));
   if (usable.length === 0) return void 0;
   const effective = (slot) => Math.min(slot.context ?? Number.POSITIVE_INFINITY, slot.tpm ?? Number.POSITIVE_INFINITY);
+  const leastLoaded = (best, slot) => loadOf(snap.counts, slot.index) < loadOf(snap.counts, best.index) ? slot : best;
   if (neededContext === void 0) {
-    for (const slot of usable) {
-      if (loadOf(snap.counts, slot.index) < slot.weight) return slot;
-    }
-    return usable.reduce((best, slot) => loadOf(snap.counts, slot.index) < loadOf(snap.counts, best.index) ? slot : best, usable[0]);
+    return pickByPass(usable, snap.counts) ?? usable.reduce(leastLoaded, usable[0]);
   }
   const adequate = usable.filter((slot) => effective(slot) >= neededContext);
   const adequateKnown = adequate.filter((slot) => Number.isFinite(effective(slot)));
   const candidates = adequate.length > 0 ? adequate : usable;
+  const smallest = (best, slot) => Number.isFinite(effective(slot)) && effective(slot) < effective(best) ? slot : best;
   if (adequateKnown.length === 0) {
     const known = usable.filter((slot) => Number.isFinite(effective(slot)));
     if (known.length > 0) {
       const largest = Math.max(...known.map((slot) => effective(slot)));
       const largestSlots = known.filter((slot) => effective(slot) === largest);
-      for (const slot of largestSlots) {
-        if (loadOf(snap.counts, slot.index) < slot.weight) return slot;
-      }
-      return largestSlots.reduce((best, slot) => loadOf(snap.counts, slot.index) < loadOf(snap.counts, best.index) ? slot : best, largestSlots[0]);
+      return pickByPass(largestSlots, snap.counts) ?? largestSlots.reduce(leastLoaded, largestSlots[0]);
     }
-    for (const slot of candidates) {
-      if (loadOf(snap.counts, slot.index) < slot.weight) return slot;
-    }
-    return candidates.reduce((best, slot) => loadOf(snap.counts, slot.index) < loadOf(snap.counts, best.index) ? slot : best, candidates[0]);
-  }
-  const underWeight = candidates.filter((slot) => loadOf(snap.counts, slot.index) < slot.weight);
-  if (underWeight.length > 0) {
-    const known = underWeight.filter((slot) => Number.isFinite(effective(slot)));
-    if (known.length === 0) return underWeight[0];
-    return known.reduce((best, slot) => effective(slot) < effective(best) ? slot : best, known[0]);
+    return pickByPass(candidates, snap.counts) ?? candidates.reduce(leastLoaded, candidates[0]);
   }
-  return candidates.reduce((best, slot) => loadOf(snap.counts, slot.index) < loadOf(snap.counts, best.index) ? slot : best, candidates[0]);
+  return pickByPass(candidates, snap.counts, smallest) ?? candidates.reduce(leastLoaded, candidates[0]);
 }
 function poolPass(s, snap, neededContext) {
   const slots = s.slots.length > 0 ? s.slots : FALLBACK_SLOTS;
-  const usable = slots.filter((slot) => isAvailable(s, slot.model, snap.cooling));
+  const primary = slots.filter((slot) => !slot.fallback);
+  const fallback = slots.filter((slot) => slot.fallback);
+  const usablePrimary = primary.filter((slot) => isAvailable(s, slot.model, snap.cooling));
+  const usable = usablePrimary.length > 0 ? usablePrimary : fallback.filter((slot) => isAvailable(s, slot.model, snap.cooling));
   if (usable.length === 0) return "none";
   const effective = (slot) => Math.min(slot.context ?? Number.POSITIVE_INFINITY, slot.tpm ?? Number.POSITIVE_INFINITY);
   const candidates = neededContext === void 0 ? usable : usable.filter((slot) => effective(slot) >= neededContext);
   const pool = candidates.length > 0 ? candidates : usable;
-  if (pool.some((slot) => loadOf(snap.counts, slot.index) < slot.weight)) return 1;
-  return "overflow";
+  const open = pool.filter((slot) => underCeiling(slot, snap.counts));
+  if (open.length === 0) return "overflow";
+  return Math.min(...open.map((slot) => fillPassIndex(slot, snap.counts))) + 1;
 }
 function agentFor(base, slot) {
   return `${base}-${slot}`;
@@ -1084,7 +1157,10 @@ export {
   FALLBACK_SLOTS,
   HANG_COOLDOWN_MS,
   HEARTBEAT_PUBLISH_MS,
+  INVALID_REQUEST_COOLDOWN_MS,
+  INVALID_REQUEST_REASON,
   LEARNED_TPM_FILE,
+  MAX_CEILING,
   MAX_CLAIM_AGE_MS,
   MAX_WEIGHT,
   MIN_SLOT_CONTEXT,
@@ -1105,6 +1181,8 @@ export {
   STATE_SWEEP_INTERVAL_MS,
   STUCK_IDLE_MS,
   STUCK_MIN_AGE_MS,
+  TRANSIENT_UPSTREAM_COOLDOWN_MS,
+  TRANSIENT_UPSTREAM_REASON,
   UNAVAILABLE_COOLDOWN_MS,
   UNAVAILABLE_REASON,
   UNBOUND_CLAIM_MS,
@@ -1127,16 +1205,20 @@ export {
   findStuck,
   idleFor,
   init,
+  isAbortText,
   isAuthFailureText,
   isAvailable,
   isContextOverflowText,
+  isFallbackMarker,
   isLimitText,
   isModelMissingText,
   isProbe,
   isQuotaReason,
   isRequestTooLargeText,
   isTransientGatewayText,
+  isTransientUpstreamText,
   isUnavailableText,
+  isUnsupportedParameterText,
   limitReason,
   manualVariant,
   markProbe,

package/dist/tunnel.js

@@ -53,6 +53,7 @@ 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 TRANSIENT_UPSTREAM_COOLDOWN_MS = 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");

package/docs/CONFIGURATION.md

@@ -23,10 +23,21 @@ allowlist anywhere in the package, and no cost check of any kind: only the
 structure is validated. The bundled preset is built from free models because
 that is a sensible default, not because the pool requires it.
 
-A slot's `weight` (default 1) is both its concurrency budget and its cap. The
-pool fills slots in declaration order in one pass; there is no slot cap, and a
-model may appear on more than one line — each line is its own slot with its own
-weight. A `tier` key is the deprecated spelling of `weight`.
+A slot's `weight` (default 1) is its per-pass concurrency budget. Its hard cap is
+its `ceiling` (max parallel sessions), which defaults to the weight and can be
+raised with a `ceiling` field (flat form `ceil:<n>`; it must be at least the
+weight). The pool fills slots in declaration order; when every usable slot has
+reached its weight, later passes deepen a slot toward its ceiling. There is no
+slot cap, and a model may appear on more than one line — each line is its own
+slot with its own weight and ceiling. A `tier` key is the deprecated spelling of
+`weight`.
+
+A slot table may also declare a **fallback pool**: a `fallbackSlots` array in
+JSON, or a line that is exactly `# --- fallback ---` (or `[fallback]`) followed
+by more slots in `pool.txt`. Fallback slots are used only when no primary slot is
+usable — they are not overflow capacity. A fallback slot that shares a quota
+bucket (or model) with any primary slot is dropped with a warning, because the
+same limit would bench both.
 
 A slot may also declare a shared quota bucket with `b:<name>` on the line (or a
 `bucket` field in JSON). A limit on any member benches the whole bucket, because

package/docs/USER-STORIES.md

@@ -15,7 +15,7 @@ line. Criteria that cannot be observed without a running server are not in this
 document; everything here is testable offline with a stub client and a
 `mkdtempSync` state directory.
 
-**Terminology.** A *slot* is one entry in `presets/free-tier.json`, carrying a model and a `weight`. A slot's `weight` is its active-session budget for one pass: the number of concurrent claims it may hold before the next slot is preferred. A *pass* is one declaration-order sweep of the slot list; the pool runs one pass, and a slot's cap is its weight. There is no slot cap, and a model may appear on more than one line — each line is its own slot with its own weight. Preference is by declaration order, never by weight. A *base* is a pooled agent type (`explore`), and its slot holders are `<base>-<slot>`, hidden in `opencode.jsonc`. A *claim* is a running spawn recorded in `claims.<pid>.json`. A *context map* is the five-file `.opencode/context/` codemap described in Epic G.
+**Terminology.** A *slot* is one entry in `presets/free-tier.json`, carrying a model, a `weight` and an optional `ceiling`. A slot's `weight` is its per-pass budget: the number of concurrent claims one pass may add before the next slot is preferred. Its `ceiling` (max parallel sessions) is the hard cap and defaults to the weight. A *pass* is one declaration-order sweep of the slot list; when every usable slot has reached its weight, later passes fill toward each slot's ceiling. There is no slot cap, and a model may appear on more than one line — each line is its own slot with its own weight and ceiling. Preference is by declaration order, never by weight. A *base* is a pooled agent type (`explore`), and its slot holders are `<base>-<slot>`, hidden in `opencode.jsonc`. A *claim* is a running spawn recorded in `claims.<pid>.json`. A *context map* is the five-file `.opencode/context/` codemap described in Epic G.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawaty/lacode",
-  "version": "2.3.0-beta.5",
+  "version": "2.3.0-beta.6",
   "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

@@ -32,30 +32,42 @@ change here takes effect without a restart. Plugin CODE still needs one.
 
 ## The flat pool file (recommended)
 
-`~/.config/lacode/pool.txt` is one model per line — edit a model id or a weight
-in place, no JSON and no objects:
+`~/.config/lacode/pool.txt` is one model per line — edit a model id, a weight or
+a ceiling in place, no JSON and no objects:
 
 ```text
-# provider/model-id                       weight  c:<context>
-opencode/big-pickle                       3       c:200000
+# provider/model-id                       weight  ceil:<max-parallel>  c:<context>
+opencode/big-pickle                       3       ceil:6                c:200000
 opencode-go/beam-free       2       c:200000
 opencode/deepseek-v4.1-flash-free         1       c:200000
 opencode/glm-5.3-flash-free               1       c:200000
 ```
 
 `#` starts a comment (whole-line or trailing), blank lines are ignored, and the
-weight is optional (default 1). `c:<context>` is the model's context window in tokens; the router uses it to prefer the smallest model that fits the task, and it is optional for hand-written lines. The rules are exactly the same as the JSON form
+weight is optional (default 1). `ceil:<max-parallel>` is optional and is the
+slot's hard concurrency cap (max parallel sessions); it must be at least the
+weight, and absent means the ceiling is the weight. `c:<context>` is the model's context window in tokens; the router uses it to prefer the smallest model that fits the task, and it is optional for hand-written lines. The rules are exactly the same as the JSON form
 below: any number of slots, a model may repeat on another line, split on the
 first slash only. The loader accepts either shape in the same file, so a leading
 `{` means JSON and anything else means the flat form.
 
+A line that is exactly `# --- fallback ---` (or `[fallback]`) starts the
+**fallback section**. Those slots are used only when no primary slot is usable;
+they are not extra overflow capacity. A fallback slot that shares a quota bucket
+(or model) with any primary slot is dropped with a warning, because a limit that
+benches the primary would bench it too. The JSON form is `"fallbackSlots": [...]`
+beside `"slots"`.
+
 ## Schema
 
 ```jsonc
 {
   "slots": [
-    { "model": "provider/model-id", "weight": 3 },
-    { "model": "provider/another-id" }        // weight defaults to 1
+    { "model": "provider/model-id", "weight": 3, "ceiling": 6 },
+    { "model": "provider/another-id" }        // weight defaults to 1, ceiling to the weight
+  ],
+  "fallbackSlots": [
+    { "model": "other-provider/reserve-id", "weight": 1 }
   ]
 }
 ```
@@ -63,7 +75,9 @@ first slash only. The loader accepts either shape in the same file, so a leading
 | Field | Required | Meaning |
 |-------|----------|---------|
 | `model` | yes | `provider/model-id`, split on the **first** slash only |
-| `weight` | no | active-session budget; the pool's capacity is the sum of the weights. Absent = 1 |
+| `weight` | no | per-pass concurrency budget; absent = 1 |
+| `ceiling` | no | hard concurrency cap (max parallel sessions); must be >= `weight`. Absent = the weight |
+| `fallbackSlots` | no | slots used only when no primary slot is usable; each must be disjoint from the primary's buckets |
 
 `$comment` is a JSON-legal array of strings and is ignored by the loader; the
 bundled preset uses it to explain itself in place.
@@ -92,18 +106,23 @@ because the pool requires it.
 
 ## Weight, precisely
 
-A weight is a slot's active-session budget: the number of concurrent claims it
-may hold before the next slot is preferred. The pool's capacity is the **sum of
-the weights**, so a weight-3 slot may hold 3 concurrent sessions and listing a
-model on two lines gives it two independent budgets.
+A weight is a slot's per-pass budget: the number of concurrent claims one pass
+may add to it before the next slot is preferred. Its hard cap is the `ceiling`
+(max parallel sessions), which defaults to the weight and can be raised per slot
+with a `ceiling` field (flat form `ceil:<n>`). The pool's capacity is the **sum
+of the ceilings**, so a weight-3 slot with ceiling 6 may hold 6 concurrent
+sessions, and listing a model on two lines gives it two independent budgets.
 
-Routing is one pass:
+Routing repeats the pass:
 
 1. fill each usable slot up to its weight, in declaration order
+2. once every usable slot has reached its weight, the next pass deepens each
+   usable slot toward its ceiling
 
-A slot is skipped when it is cooling or unavailable. When every usable slot is
-at its weight, the pool is at capacity and overflow goes to the least loaded
-usable slot; the pool never refuses work.
+A slot is skipped when it is cooling, unavailable, or at its ceiling. When every
+usable slot is at its ceiling, the pool is at capacity and overflow goes to the
+least loaded usable slot; the pool never refuses work. With no ceiling set the
+slot stops at its weight, so the historical one-pass behaviour is unchanged.
 
 Live claims decide the next slot: a released claim immediately reopens its
 slot, and there is no stored position.

package/presets/free-tier.json

@@ -14,18 +14,26 @@
     "ANY NUMBER OF SLOTS: one hidden variant per base per slot is declared from the resolved",
     "table, and the watcher declares a variant when a reload grows the table. There is no slot cap.",
     "",
-    "WEIGHT IS THE ACTIVE-SESSION BUDGET FOR ONE PASS: a slot may hold up to its weight in",
-    "concurrent claims before the next slot is preferred. Slots are filled in declaration",
-    "order; preference is order, never weight.",
-    "Routing is ONE ordered pass: each usable slot fills up to its weight, in declaration",
-    "order. A slot is skipped when it is cooling or unavailable. When every usable slot is at",
-    "its weight, the pool is at capacity (the sum of the weights) and overflow goes to the",
-    "least-loaded usable slot; the pool never refuses work.",
+    "WEIGHT IS THE PER-PASS BUDGET: a slot may be given up to its weight concurrent claims",
+    "in one pass before the next slot is preferred. Slots are filled in declaration order;",
+    "preference is order, never weight.",
+    "Routing repeats the pass: each pass fills every usable slot to its weight, then the",
+    "next pass deepens a slot toward its CEILING (its max parallel sessions), stopping",
+    "when every usable slot is at its ceiling. A slot is skipped when it is cooling or",
+    "unavailable. With no ceiling configured the ceiling is the weight, so the pool does",
+    "one pass and its capacity is the sum of the weights; overflow then goes to the",
+    "least-loaded usable slot and the pool never refuses work.",
+    "An optional per-slot 'ceiling' (flat format: ceil:<max-parallel>) raises the hard cap",
+    "above the weight. It must be at least the weight.",
+    "An optional 'fallbackSlots' array (flat format: a line that is exactly",
+    "'# --- fallback ---', then the fallback lines below it) is used only when no primary",
+    "slot is usable. A fallback slot must not share a bucket or model with the primary,",
+    "or it is dropped: a limit that benches the primary would bench it too.",
     "Live claims decide the next slot: a released claim immediately reopens its slot, and",
     "there is no stored position.",
     "",
-    "With this file: weights 3,2,1,1 give 7 active sessions in total. To give a model more",
-    "capacity, list it again on another line with its own weight.",
+    "With this file: weights 3,2,1,1 (no ceilings) give 7 active sessions in total. To give",
+    "a model more capacity, raise its ceiling or list it again on another line.",
     "Equal weights give a plain pass in list order.",
     "",
     "DECLARATION ORDER IS PREFERENCE. Slots are filled in declaration order, so the slot",