@lawaty/lacode 2.3.0-beta.3 → 2.3.0-beta.4

package/CHANGELOG.md

@@ -9,6 +9,15 @@ commit as the changelog entry it describes.
 
 ## [Unreleased]
 
+## [2.3.0-beta.4] — status never benches, structure is the contract
+
+### Fixed
+
+- Pool: only a hard outage (a gating `go`/`free` service reporting `down`) with a structurally intact pool may skip a refresh scan. A mere `degraded` never skips, because models routinely answer while the status page says degraded. Paid-tier (`payg`) and roll-up (`inference`) components can no longer freeze the free pool.
+- Pool: the fail-closed guard now enforces structure, not just count. A selection that drops the opencode-go head or the opencode tail is refused even at full count, and the keep threshold is anchored to the contract pool size (10) instead of the current file, so repeated writes can no longer ratchet the pool down. `--force-write` overrides the guard for a genuinely changed catalogue.
+- Pool: per-request probe deadline is 12 seconds (was 45), so a flapping provider stretches a scan far less; `--timeout MS` still overrides it.
+- Pool: a failed scorer run or a refused write now schedules a 5-minute recheck like every other failed run, instead of waiting for the next 6-hour slot.
+
 ## [2.3.0-beta.3] — persist autonomy modes in global config
 
 ### Changed

package/docs/USER-STORIES.md

@@ -194,7 +194,9 @@ A refresh once replaced a healthy ten-slot pool with a two-slot scan because not
 **Story ID(s) for tests:** US-40
 **Acceptance criteria:**
 - [ ] Given a healthy pool and a scan that returns fewer slots than half of it (minimum four), When the refresh finishes, Then the previous pool file is left untouched, the refusal is logged, and a recheck is scheduled in 5 minutes.
-- [ ] Given opencode's serving path reports degraded on the live status and the current pool is intact, When the refresh runs, Then no scan is started, the pool is kept, and a recheck is scheduled in 5 minutes.
+- [ ] Given a scan that drops the opencode-go head or the opencode tail the current pool has, When the refresh finishes, Then the previous pool is kept even at full count, because the structure is the contract.
+- [ ] Given opencode's serving path reports a hard outage on the live status and the current pool is structurally intact, When the refresh runs, Then no scan is started, the pool is kept, and a recheck is scheduled in 5 minutes.
+- [ ] Given the status reports degraded (latency, elevated errors) rather than down, When the refresh runs, Then the scan proceeds as normal, because models routinely answer while the page says degraded.
 - [ ] Given any failed run with a stated reset hours out, When the retry is scheduled, Then the recheck still happens within 5 minutes; a sooner provider reset is honoured.
 - [ ] Given the degradation lifts, When the next 5-minute recheck runs, Then a full scan restores the pool instead of waiting for the next 6-hour slot.
 - [ ] Given a thin or missing pool, When a fuller scan completes, Then it is always written — the guard only ever blocks shrinking, never recovery.
@@ -654,6 +656,6 @@ The root-level suites under `tests/` are unit-style; the `tests/stories/` suites
 the behavioural layer, written one epic per file with every test name carrying
 its story id. Run everything with `npm test`.
 
-40/40 stories covered by 376 test case(s); thinnest story has 1.
+40/40 stories covered by 377 test case(s); thinnest story has 1.
 No story is untested. 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": "2.3.0-beta.3",
+  "version": "2.3.0-beta.4",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",

package/scripts/refresh-pool.mjs

@@ -24,6 +24,7 @@ import { homedir, userInfo } from "node:os"
 import { dirname, join, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 import { fetchProviderStatus } from "./provider-status.mjs"
+import { POOL_SIZE } from "./pool-selection.mjs"
 
 const HOME = homedir()
 export const DEFAULT_SCORES_PATH = join(HOME, ".config", "lacode", "model-scores.json")
@@ -209,23 +210,83 @@ export function poolSlotCount(text) {
   return splitHeaderAndSlots(text).slots.filter(isSlotLine).length
 }
 
+/** The pool's structural contract: an opencode-go head and an opencode tail. */
+export function poolHasHead(text) {
+  const slots = splitHeaderAndSlots(text).slots.filter(isSlotLine)
+  return slots.length > 0 && slots[0].split("#")[0].trim().startsWith("opencode-go/")
+}
+
+export function poolHasTail(text) {
+  const slots = splitHeaderAndSlots(text).slots.filter(isSlotLine)
+  if (slots.length === 0) return false
+  const last = slots[slots.length - 1].split("#")[0].trim()
+  return last.startsWith("opencode/") && /(^|\s)b:opencode(\s|$)/.test(last)
+}
+
+/**
+ * Pure scan-skip decision. Only a hard `down` on a gating opencode service may
+ * skip a scan — `degraded` never does, because models routinely answer while
+ * the page says degraded. A structurally broken pool is never skipped either:
+ * the scan is its repair path.
+ */
+export function shouldSkipScan({ providerStatus, currentPoolText }) {
+  if (!providerStatus?.ok || providerStatus.stale) {
+    return { skip: false, reason: "no trustworthy live signal; scanning" }
+  }
+  const down = Array.isArray(providerStatus.down) ? providerStatus.down : []
+  if (down.length === 0) {
+    return { skip: false, reason: "no hard outage on the live status; scanning" }
+  }
+  if (!poolHasHead(currentPoolText) || !poolHasTail(currentPoolText)) {
+    return { skip: false, reason: "pool structure already broken; scanning to repair it" }
+  }
+  return {
+    skip: true,
+    reason: `opencode status reports down: ${down.join(", ")}; keeping the current pool and rechecking in ${DEGRADED_RETRY_S / 60} minutes`,
+  }
+}
+
 /**
- * Pure fail-closed guard. A refresh must never replace a working pool with a
- * degenerate selection: when the new slot count falls below half the previous
- * pool (floored at MIN_POOL_SLOTS), the previous pool is kept. There is no
- * previous pool on a first-ever run, so there is nothing to protect and the
- * guard passes.
+ * Pure fail-closed guard. A refresh must never break the pool's structure or
+ * replace a working pool with a degenerate selection: the new pool must keep
+ * the opencode-go head and the opencode tail the current pool has, and hold at
+ * least half of POOL_SIZE. The baseline is the contract size, never the
+ * current file — a previously shrunk pool can always grow back, but no write
+ * may shrink or behead it. There is no previous pool on a first-ever run, so
+ * there is nothing to protect and the guard passes. `--force-write` is the
+ * human override for a genuinely changed catalogue.
  */
-export function shouldKeepPool({ currentPoolText, newSlotCount }) {
+export function shouldKeepPool({ currentPoolText, newSlots }) {
   const prev = poolSlotCount(currentPoolText ?? "")
   if (prev <= 0) return { keep: false, prev, threshold: 0, reason: "no previous pool to protect" }
-  const threshold = Math.max(MIN_POOL_SLOTS, Math.floor(prev / 2))
-  if (newSlotCount >= threshold) return { keep: false, prev, threshold, reason: "" }
+  const slots = Array.isArray(newSlots) ? newSlots : []
+  const threshold = Math.max(MIN_POOL_SLOTS, Math.floor(POOL_SIZE / 2))
+  if (poolHasHead(currentPoolText) && !slots.some((line) => String(line).split("#")[0].trim().startsWith("opencode-go/"))) {
+    return {
+      keep: true,
+      prev,
+      threshold,
+      reason: `new selection has no opencode-go head slot while the previous pool has one; refusing to behead the pool`,
+    }
+  }
+  const tailKept = slots.some((line) => {
+    const stripped = String(line).split("#")[0].trim()
+    return stripped.startsWith("opencode/") && /(^|\s)b:opencode(\s|$)/.test(stripped)
+  })
+  if (poolHasTail(currentPoolText) && !tailKept) {
+    return {
+      keep: true,
+      prev,
+      threshold,
+      reason: `new selection has no opencode tail slot while the previous pool has one; refusing to dock the tail`,
+    }
+  }
+  if (slots.length >= threshold) return { keep: false, prev, threshold, reason: "" }
   return {
     keep: true,
     prev,
     threshold,
-    reason: `new selection has ${newSlotCount} usable slot(s), below the keep threshold of ${threshold} (previous pool had ${prev}); refusing to shrink the pool`,
+    reason: `new selection has ${slots.length} usable slot(s), below the keep threshold of ${threshold} (contract pool size ${POOL_SIZE}); refusing to shrink the pool`,
   }
 }
 
@@ -383,15 +444,19 @@ function usage() {
   --max N           models per provider passed to the scorer (default: 50)
   --scores PATH     scores file (default: ${DEFAULT_SCORES_PATH})
   --pool PATH       pool file to read/compare/write (default: ${DEFAULT_POOL_PATH})
+  --force-write   write the new selection even when the fail-closed guard would
+                    keep the previous pool (human override for a changed catalogue)
   -h, --help        this message
 
 Degradation behaviour: before scanning, the refresh checks
-https://status.opencode.ai/api/status. When opencode's serving path reports
-degraded and the current pool is intact, the scan is skipped, the pool is kept,
-and a recheck is scheduled in 5 minutes. After a scan, a selection below half
-the previous pool (minimum ${MIN_POOL_SLOTS} slots) is never written; the previous pool
-is kept and a 5-minute recheck is scheduled. A retry is always rechecked
-within 5 minutes while anything failed, even when the stated reset is hours out.`)
+https://status.opencode.ai/api/status. Only a hard outage (a gating service
+reporting down) with a structurally intact pool skips the scan; a mere degraded
+never does, because models routinely answer while the page says degraded. After
+a scan, a selection that beheads the pool (no opencode-go head), docks the tail
+(no opencode slot), or falls below half the contract pool size (minimum ${MIN_POOL_SLOTS}
+slots) is never written; the previous pool is kept and a 5-minute recheck is
+scheduled. A retry is always rechecked within 5 minutes while anything failed,
+even when the stated reset is hours out.`)
 }
 
 async function main() {
@@ -404,6 +469,7 @@ async function main() {
   const fromScores = argv.includes("--from-scores")
   const printOnly = argv.includes("--print") || argv.includes("--dry-run")
   const noRetry = argv.includes("--no-retry")
+  const forceWrite = argv.includes("--force-write")
   const value = (flag, fallback) => {
     const hit = argv.find((a) => a === flag || a.startsWith(`${flag}=`))
     if (!hit) return fallback
@@ -423,23 +489,21 @@ async function main() {
 
   const currentPoolText = readTextFile(poolPath)
 
-  // Live degradation signal. When opencode's own serving path reports degraded
-  // and the current pool is intact, probing now can only shrink it: keep the
-  // pool untouched and recheck in 5 minutes. A thin pool is still scanned, so
-  // a first-ever run (or a previously clobbered one) can recover, and the
-  // write guard below protects it if the scan comes back degenerate.
-  let providerStatus = { ok: false, providers: [], services: [] }
+  // Live degradation signal. Only a hard `down` on opencode's serving path may
+  // skip the scan — and only when the current pool is structurally intact, so
+  // a broken pool always gets its repair scan. `degraded` never skips: models
+  // routinely answer while the page says degraded, and the write guard below
+  // protects the pool if the scan comes back degenerate.
+  let providerStatus = { ok: false, providers: [], services: [], down: [] }
   if (!printOnly) {
     try {
       providerStatus = await fetchProviderStatus()
     } catch (error) {
-      providerStatus = { ok: false, providers: [], services: [], reason: String(error?.message ?? error) }
+      providerStatus = { ok: false, providers: [], services: [], down: [], reason: String(error?.message ?? error) }
     }
-    if (providerStatus.ok && providerStatus.providers.length > 0 && poolSlotCount(currentPoolText) >= MIN_POOL_SLOTS) {
-      const detail = providerStatus.services.map((entry) => `${entry.service}=${entry.status}`).join(", ")
-      console.log(
-        `opencode status degraded (${detail}); keeping the current pool of ${poolSlotCount(currentPoolText)} slots and rechecking in ${DEGRADED_RETRY_S / 60} minutes`,
-      )
+    const skip = shouldSkipScan({ providerStatus, currentPoolText })
+    if (skip.skip) {
+      console.log(`${skip.reason}; keeping the current pool of ${poolSlotCount(currentPoolText)} slots`)
       if (!noRetry) {
         const scheduled = scheduleRetrySoon()
         console.log(
@@ -457,6 +521,14 @@ async function main() {
       runScorer(max)
     } catch (error) {
       console.error(`scorer failed; pool.txt not written: ${String(error?.message ?? error)}`)
+      if (!printOnly && !noRetry) {
+        const scheduled = scheduleRetrySoon()
+        console.log(
+          scheduled.scheduled
+            ? `scheduled degraded recheck in ${scheduled.seconds}s`
+            : `degraded recheck not scheduled: ${scheduled.reason}`,
+        )
+      }
       process.exitCode = 1
       return
     }
@@ -476,6 +548,14 @@ async function main() {
     built = buildPool({ scores, currentPoolText, now: new Date() })
   } catch (error) {
     console.error(`refresh refused (fail closed): ${String(error?.message ?? error)}`)
+    if (!printOnly && !noRetry) {
+      const scheduled = scheduleRetrySoon()
+      console.log(
+        scheduled.scheduled
+          ? `scheduled degraded recheck in ${scheduled.seconds}s`
+          : `degraded recheck not scheduled: ${scheduled.reason}`,
+      )
+    }
     process.exitCode = 1
     return
   }
@@ -491,8 +571,9 @@ async function main() {
 
   // Fail closed on a degenerate selection: keep the previous pool, say so
   // loudly, and recheck in 5 minutes instead of waiting out a long reset.
-  if (!printOnly) {
-    const kept = shouldKeepPool({ currentPoolText, newSlotCount })
+  // --force-write is the human override for a genuinely changed catalogue.
+  if (!printOnly && !forceWrite) {
+    const kept = shouldKeepPool({ currentPoolText, newSlots: built.slots })
     if (kept.keep) {
       console.error(`refresh refused (fail closed): ${kept.reason}`)
       if (!noRetry) {

package/scripts/score-models.mjs

@@ -104,7 +104,7 @@ const value = (flag, fallback) => {
   --min-context N   exclude models whose context limit is below N (default: ${MIN_CONTEXT})
   --min-score N     do not rank models scoring below N (default: ${MIN_SCORE})
   --free-only        only probe catalogue cost 0/0 models on every provider
-  --timeout MS      per-request deadline in ms (default: 45000)
+  --timeout MS      per-request deadline in ms (default: 12000)
   --delay MS        pause between requests in ms (default: 300)
   --budget-min N    stop starting new probes after N minutes and write what was
                     measured; providers not scanned keep their previous rows
@@ -129,7 +129,7 @@ const providers = providerArg ? String(providerArg).split(",").map((s) => s.trim
 const maxPerProvider = Math.max(1, Number(value("--max", "50")) || 50)
 const minContext = Math.max(0, Number(value("--min-context", String(MIN_CONTEXT))) || MIN_CONTEXT)
 const minScore = Math.max(0, Number(value("--min-score", String(MIN_SCORE))) || MIN_SCORE)
-const timeoutMs = Math.max(1_000, Number(value("--timeout", "45000")) || 45_000)
+const timeoutMs = Math.max(1_000, Number(value("--timeout", "12000")) || 12_000)
 const delayMs = Math.max(0, Number(value("--delay", "300")) || 300)
 const budgetMin = Math.max(1, Number(value("--budget-min", "30")) || 30)
 const budgetMs = budgetMin * 60_000