@lawaty/lacode 2.2.0-beta.0 → 2.3.0-beta.0

package/docs/USER-STORIES.md

@@ -30,6 +30,7 @@ document; everything here is testable offline with a stub client and a
 | **E — Remote hosts** | Remote SSH notification. Work runs on remote hosts, so notifications raised there die on that host's nonexistent desktop instead of reaching the local one. |
 | **F — Adoption and safety** | Installability. A personal config cannot be adopted safely: it either clobbers what you already have, or needs manual surgery before it runs. |
 | **G — Context and cost** | Cold exploration. Every task starts by re-discovering the structure of the codebase from scratch, so the same layout is re-read — and re-paid for — on every single run. |
+| **K — Autonomy modes** | Stalls. A long run stops for every routine permission, or waits for a human to answer a question the agent could decide itself, even when its own recommendation is clear. |
 
 ---
 
@@ -88,8 +89,9 @@ The reconciliation with US-7 is that **acceptance and endorsement are different
 **Story ID(s) for tests:** US-4
 **Acceptance criteria:**
 - [ ] Given a spawn fails with a rate-limit-shaped error, When the error is serialized and matched, Then the offending model is marked cooling and a cooldown file is written for it.
-- [ ] Given model A is cooling, When the next spawn is routed, Then the pick is a different model and the spawn is never refused outright.
-- [ ] Given every model is cooling, When a spawn is routed, Then the least-loaded slot is chosen anyway (degrade, never block).
+- [ ] Given model A is cooling and another slot is usable, When the next spawn is routed, Then the pick is a different usable model, never the cooling one.
+- [ ] Given a pooled task completes with an empty result, When the task hook returns, Then that model is benched for `empty response`, the result explains the bench, and the next spawn routes to another slot.
+- [ ] Given every model is cooling, When a spawn is routed, Then the spawn is refused explicitly with a message naming the cooling slots and their reasons, and no model is routed to.
 - [ ] Given a limit error names a reset time, When the cooldown is recorded, Then the stated reset is used instead of a guessed backoff.
 
 ### US-5: Slots fill in declaration order in one pass, with repeats
@@ -101,7 +103,7 @@ The reconciliation with US-7 is that **acceptance and endorsement are different
 - [ ] Given a model appears on more than one line, When the pool loads, Then each line is its own slot with its own weight, and the later line adds seats at its own position.
 - [ ] Given a slot is cooling or unavailable, When its position comes up, Then it is skipped and the pass continues to the next slot.
 - [ ] Given a claim is released, When the next spawn is routed, Then the slot that freed capacity is preferred again in declaration order; no stored position keeps it waiting.
-- [ ] Given every usable slot is at its weight, When another spawn is routed, Then it goes to the least-loaded usable slot as overflow, and the pool never refuses work.
+- [ ] Given every usable slot is at its weight, When another spawn is routed, Then it goes to the least-loaded usable slot as overflow, and the pool never refuses work while at least one slot is usable.
 - [ ] Given all slots carry equal weight, When spawns are routed, Then the same ordered one-pass fill applies.
 - [ ] Given per-slot load is read, When it is asserted, Then a slot's load never exceeds its weight except through overflow.
 
@@ -167,6 +169,20 @@ A limit does not always arrive as an error. Sometimes the provider accepts the r
 - [ ] 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.
 
+### US-39: The pool refresh completes, retries what failed, and never starves
+**As a** user relying on the scored pool, **I want** the refresh to finish even when the machine reboots, **so that** the pool is never stranded on stale scores and a transient provider failure does not erase a model I was using.
+
+A daily scan was killed by a reboot mid-run, and because systemd records a trigger when the service starts, `Persistent=true` did not retry it. The refresh now runs every 6 hours, gets a startup trigger, scans the core providers first under a wall-clock budget, keeps previous rows for providers it could not finish, and preserves the last measured score of a model that failed transiently. A PID lock keeps the 6-hour run and a retry timer from racing.
+
+**Story ID(s) for tests:** US-39
+**Acceptance criteria:**
+- [ ] Given the installed timer, When it is rendered, Then it has `OnCalendar=*-*-* 00/6:00:00`, `OnStartupSec=5min`, and `Persistent=true`, and the service has `TimeoutStartSec=infinity`.
+- [ ] Given a scan reaches its wall-clock budget, When the scores are written, Then unscanned and truncated providers keep their previous rows, so a partial run cannot shrink the pool.
+- [ ] Given a model failed transiently (timeout, rate limit, credit), When selection runs, Then its last measured score is retained and a retry is scheduled at the stated reset or 45 minutes later.
+- [ ] Given a permanent failure (401, 403 agreement, 404), When selection runs, Then the model is not retried and does not fall back to a previous score.
+- [ ] Given enough other providers to fill the pool, When selection runs, Then exactly one `opencode` slot is reserved last with weight 2.
+- [ ] Given two refreshes overlap, When the second starts, Then it skips while the lock is held, and a lock left by a dead PID is reclaimed.
+
 ---
 
 ## Epic C — Hang detection and auto-recovery
@@ -531,6 +547,37 @@ A failed summarization used to clear the pending flag and never reschedule, so o
 - [ ] 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.
 
+## Epic K — Autonomy modes (YOLO and YKB)
+
+### US-37: YOLO mode approves permissions without stopping
+**As a** user running a long autonomous task, **I want** permission prompts to be approved automatically while YOLO is on, **so that** the agent keeps working instead of waiting for routine approvals, while an explicit `deny` still protects me.
+
+Permission prompts are the main thing that breaks a long autonomous run: every `ask` blocks the session until a human answers. YOLO flips that decision to `allow` at the permission hook, keeps an explicit `deny` authoritative, and answers any request that still reaches the event bus. The state is a small file the TUI writes and the server reads on the next decision, so enabling it also clears what is already pending.
+
+**Story ID(s) for tests:** US-37
+**Acceptance criteria:**
+- [ ] Given YOLO is on, When the runtime's permission decision is `ask`, Then it becomes `allow` without a prompt, while an existing `deny` or `allow` is left unchanged.
+- [ ] Given YOLO is off, When the runtime's permission decision is `ask`, Then it stays `ask` and still reaches the user.
+- [ ] Given a `permission.asked` event still reaches the event bus while YOLO is on and carries a request id and a session id, When the handler runs, Then the plugin replies `once` for that request; an event missing either id is ignored.
+- [ ] Given YOLO is toggled in the TUI, When the mode file changes, Then the next permission decision sees the new value without a restart, and requests already pending are answered.
+- [ ] Given `yolo: true` in the plugin options and no live mode file, When the plugin starts, Then the file is seeded; after a TUI toggle, the live file wins.
+- [ ] Given the README and configuration reference, Then the `yolo` option and the `/yolo` command are documented alongside `/modes`.
+
+### US-38: YKB mode chooses the recommendation instead of asking
+**As a** user who wants the agent to keep moving, **I want** YKB (You Know Better) mode to suppress questions and pick the recommended option itself, **so that** it finishes or blocks on a real dependency rather than waiting for me to choose.
+
+A question costs a full turn and a human decision, even when the agent has a clear recommendation. YKB adds a system instruction that tells the agent to choose and continue, and auto-answers any question that still reaches the runtime with its `(Recommended)` option (or the first option when none is marked). A free-text question with no options is left for the user, because there is nothing to choose.
+
+**Story ID(s) for tests:** US-38
+**Acceptance criteria:**
+- [ ] Given YKB is on, When a request is built, Then the system prompt carries the YKB instruction exactly once; when YKB is off, the instruction is absent.
+- [ ] Given a question offers options and YKB is on, When the plugin answers it, Then each question selects the option marked `(Recommended)` (case-insensitive, in the label or description), or the first option when none is marked.
+- [ ] Given a question has no options, When YKB sees it, Then it leaves the question for the user and records a warning rather than inventing an answer.
+- [ ] Given YKB is off, When a question is asked, Then the plugin sends no answer.
+- [ ] Given YKB is toggled on in the TUI, When questions are already pending, Then they are answered with the same recommendation rule.
+- [ ] Given YOLO and YKB are both on, When permission and question events arrive, Then each mode acts only on its own event and the other mode's behavior is unchanged.
+- [ ] Given the README and configuration reference, Then the `ykb` option and the `/ykb` and `/modes` commands are documented.
+
 ---
 
 ## Coverage
@@ -555,6 +602,7 @@ table was filled in.
 | 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-39 | B | `tests/stories/l-pool-refresh.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` |
@@ -581,13 +629,13 @@ table was filled in.
 | US-36 | G | `tests/stories/j-timeline-reliability.test.mjs` |
 | US-32 | H | `tests/retire-old-sessions-test.mjs` |
 | US-33 | H | `tests/prune-old-events-test.mjs` |
+| US-37 | K | `tests/stories/k-autonomy-modes.test.mjs` |
+| US-38 | K | `tests/stories/k-autonomy-modes.test.mjs` |
 
-The nine suites under `tests/` are unit-style; the `tests/stories/` suites are
+The root-level 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.** The guard reports 36 stories, 348 test cases, and
-36/36 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
+39/39 stories covered by 370 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.2.0-beta.0",
+  "version": "2.3.0-beta.0",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",

package/scripts/pool-selection.mjs

@@ -14,21 +14,74 @@ export const DEFAULT_QUOTA_RETRY_MS = 15 * 60 * 1000
 export const CREDIT_RETRY_MS = 6 * 60 * 60 * 1000
 export const MAX_RETRY_DELAY_MS = 24 * 60 * 60 * 1000
 export const STATED_COOLDOWN_MAX_MS = 6 * 60 * 60 * 1000
+// A transient failure with no stated reset gets a bounded retry instead of
+// vanishing from the pool until the next full scan. 45 minutes is long enough
+// for a gateway hiccup or a short provider outage to clear, short enough that a
+// recovered model is back well before the 6-hour timer.
+export const SYNTHETIC_RETRY_MS = 45 * 60 * 1000
 
-export const isTransientFailure = (row) =>
-  row?.ok === false &&
-  /timeout|timed out|rate-limit|no answer|no response|unreachable|ECONN|ETIMEDOUT|fetch failed|socket hang up|credit|402/i.test(
-    String(row.reason ?? ""),
-  )
+// Scan order, not selection order: the pool's core providers are probed first so
+// a wall-clock budget can never starve them behind a slow paid catalogue. This is
+// ordering only -- never an exclusion.
+export const providerRank = (provider) => {
+  const name = String(provider ?? "")
+  if (name === "opencode-go" || name === "opencode") return 0
+  if (name === "console-openrouter" || name === "openrouter") return 2
+  return 1
+}
+
+// One classifier, shared by the scorer (live probe outcome) and the selector
+// (persisted row). The reason text is the fallback for rows written before the
+// classifier existed or by a provider that gives only prose.
+const FAILURE_KINDS = [
+  ["agreement", /model\s+agreement|terms\s+of\s+(?:service|use)|\btos\b/i],
+  ["credit", /out\s+of\s+credits|insufficient\s+credits|credit\s+balance|requires\s+more\s+credits|payment\s+required|billing|purchase|\b402\b/i],
+  ["rate-limited", /rate[\s_-]?limit|usage\s+limit|too\s+many\s+requests|overloaded|limits?[\s_-]?(?:reached|exceeded)|free[-\s]?tier|freelimiterror|quota|\b429\b/i],
+  ["credential", /\b401\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],
+  ["not-served", /\b404\b|no\s+such\s+model|model\s+not\s+found|does\s+not\s+exist|is\s+not\s+available|not\s+served|not\s+found/i],
+  ["timeout", /timeout|timed\s+out|ETIMEDOUT|no\s+answer|no\s+response/i],
+  ["network", /ECONNRESET|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|fetch\s+failed|socket\s+hang\s+up|unreachable/i],
+  ["server", /\b5\d\d\b|internal\s+server|bad\s+gateway|service\s+unavailable|gateway\s+timeout/i],
+]
+
+// A credit exhaustion is transient over hours, not permanent: the balance can be
+// topped up, and the retry schedule is what carries it. Agreement, credential
+// and not-served failures are permanent for this model until a human acts.
+const TRANSIENT_KINDS = new Set(["rate-limited", "credit", "timeout", "network", "server"])
+
+export const isTransientKind = (kind) => TRANSIENT_KINDS.has(String(kind ?? "").toLowerCase())
+
+export function classifyFailure({ status, reason, kind } = {}) {
+  if (kind) return String(kind).toLowerCase()
+  const text = String(reason ?? "")
+  const code = Number(status)
+  if (code === 402) return "credit"
+  if (code === 429) return "rate-limited"
+  if (code === 401) return "credential"
+  if (code === 403) {
+    const named = FAILURE_KINDS.find(([, re]) => re.test(text))?.[0]
+    return named === "agreement" || named === "credit" ? named : "credential"
+  }
+  if (code === 404) return "not-served"
+  if (code >= 500 && code <= 599) return "server"
+  for (const [name, re] of FAILURE_KINDS) if (re.test(text)) return name
+  return "unknown"
+}
+
+export const isTransientFailure = (row) => {
+  if (row?.ok !== false) return false
+  if (row.kind) return isTransientKind(row.kind)
+  return isTransientKind(classifyFailure({ status: row.status, reason: row.reason }))
+}
 
 const isLimitText = (text) =>
-  /rate[\s_-]?limit|usage limit|too many requests|quota|freelimiterror|overloaded|limits?[\s_-]?(?:reached|exceeded)|\b429\b/i.test(
+  /rate[\s_-]?limit|usage limit|too many requests|quota|freelimiterror|free[-\s]?tier|overloaded|limits?[\s_-]?(?:reached|exceeded)|\b429\b/i.test(
     String(text ?? ""),
   )
 
 const isDailyLimit = (text) => /per[\s-]?day|daily|free-models-per-day|requests?\s+per\s+day/i.test(String(text ?? ""))
 
-const isCreditText = /out of credits|insufficient credits|credit balance|requires more credits|\b402\b/i
+const isCreditText = /out of credits|insufficient credits|credit balance|requires more credits|payment required|billing|purchase|\b402\b/i
 
 const bounded = (ms) => (Number.isFinite(ms) && ms > 0 && ms <= STATED_COOLDOWN_MAX_MS ? ms : undefined)
 
@@ -81,6 +134,7 @@ export function selectPool({
   minScore = MIN_SCORE,
   poolSize = POOL_SIZE,
   maxZen = MAX_ZEN,
+  now = Date.now,
 } = {}) {
   const rankable = (row) =>
     row?.ok === true &&
@@ -89,23 +143,41 @@ export function selectPool({
     row.score >= minScore &&
     (row.context == null || row.context >= minContext)
   const byScore = (a, b) => b.score - a.score || String(a.model).localeCompare(String(b.model))
+  const nowMs = typeof now === "function" ? Number(now()) : Number(now)
+  const normalize = (row) => {
+    if (row?.ok !== false || !isTransientFailure(row)) return row
+    const at = Number(row.retryAfter)
+    if (Number.isFinite(at) && at > nowMs) return row
+    return { ...row, retryAfter: nowMs + SYNTHETIC_RETRY_MS }
+  }
 
-  const rows = rowsOf(providers)
+  const rows = rowsOf(providers).map(normalize)
   const previousRows = rowsOf(previousProviders)
   const currentByModel = new Map(rows.map((row) => [row.model, row]))
+  const scannedProviders = new Set(
+    (Array.isArray(providers) ? providers : []).map((entry) => String(entry?.provider ?? "")),
+  )
   const erroredProviders = new Set(
     (Array.isArray(providers) ? providers : [])
       .filter((entry) => entry?.error)
       .map((entry) => String(entry.provider ?? "")),
   )
+  const truncatedProviders = new Set(
+    (Array.isArray(providers) ? providers : [])
+      .filter((entry) => entry?.truncated)
+      .map((entry) => String(entry.provider ?? "")),
+  )
 
   // A model the previous run scored is kept when this run could not reach it
-  // for a transient reason. A model the provider says is gone is not kept.
+  // for a transient reason, when its provider was not scanned at all (a
+  // targeted scan), or when the scan budget cut that provider off. A model the
+  // provider says is gone is not kept.
   const fallback = previousRows.filter((row) => {
     if (!rankable(row)) return false
     const current = currentByModel.get(row.model)
     if (current) return isTransientFailure(current)
-    return erroredProviders.has(providerOf(row.model))
+    const provider = providerOf(row.model)
+    return !scannedProviders.has(provider) || truncatedProviders.has(provider) || erroredProviders.has(provider)
   })
 
   const merge = (pick) => {
@@ -146,7 +218,11 @@ export function selectPool({
   const cappedSmall = capPerProvider(small, MAX_PER_PROVIDER)
   const cappedLarge = capPerProvider(large, MAX_PER_PROVIDER_LARGE)
 
-  const remaining = Math.max(0, poolSize - go.length)
+  // Reserve the last slot for zen when a rankable one exists. Without the
+  // reservation a full field of other providers squeezes zen out entirely, which
+  // is the opposite of "exactly one zen slot at the end".
+  const zenReserve = zen.length > 0 ? Math.max(0, Math.min(maxZen, poolSize - go.length)) : 0
+  const remaining = Math.max(0, poolSize - go.length - zenReserve)
   const pickedLarge = cappedLarge.slice(0, Math.min(LARGE_RESERVE, remaining))
   const pickedSmall = cappedSmall.slice(0, Math.max(0, remaining - pickedLarge.length))
 
@@ -159,22 +235,40 @@ export function selectPool({
     pickedSmall.push(...cappedSmall.slice(pickedSmall.length, pickedSmall.length + need))
   }
 
-  const zenSlots = Math.max(0, Math.min(maxZen, poolSize - go.length - pickedSmall.length - pickedLarge.length))
-  const pickedZen = zen.slice(0, zenSlots)
+  const pickedZen = zen.slice(0, zenReserve)
 
   const selection = [
     ...go.map((row) => ({ model: row.model, weight: 4, context: row.context ?? null })),
     ...pickedSmall.map((row) => ({ model: row.model, weight: 2, context: row.context ?? null })),
     ...pickedLarge.map((row) => ({ model: row.model, weight: 1, context: row.context ?? null })),
-    ...pickedZen.map((row) => ({ model: row.model, weight: 1, bucket: "opencode", context: row.context ?? null })),
+    ...pickedZen.map((row) => ({ model: row.model, weight: 2, bucket: "opencode", context: row.context ?? null })),
   ]
 
   const warnings = []
+  for (const entry of Array.isArray(providers) ? providers : []) {
+    if (entry?.error) {
+      warnings.push(`${entry.provider}: ${entry.error}`)
+      continue
+    }
+    const entryRows = Array.isArray(entry?.rows) ? entry.rows : []
+    if (entryRows.length === 0 || entryRows.some(rankable)) continue
+    const kinds = new Map()
+    for (const row of entryRows) {
+      if (row?.ok !== false) continue
+      const kind = row.kind ?? classifyFailure({ status: row.status, reason: row.reason })
+      kinds.set(kind, (kinds.get(kind) ?? 0) + 1)
+    }
+    const [dominant, count] = [...kinds.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0] ?? [
+      "unknown",
+      0,
+    ]
+    warnings.push(`${entry.provider}: ${entryRows.length} probed, 0 rankable — dominant failure: ${dominant} (${count})`)
+  }
   const total = selection.length
   if (total === 0) warnings.push("no scorable model at or above the minimum score is available")
   else if (total < poolSize) warnings.push(`only ${total} scorable model(s) available, wanted ${poolSize}`)
 
-  const limited = rows.filter((row) => row?.ok === false && Number.isFinite(row.retryAfter))
+  const limited = rows.filter((row) => row?.ok === false && isTransientFailure(row) && Number.isFinite(row.retryAfter))
   const retry =
     limited.length > 0
       ? {

package/scripts/refresh-pool.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Daily-refreshable pool builder.
+// Refreshable pool builder; the installed systemd timer runs it every 6 hours.
 //
 // Reads the scorer's output (~/.config/lacode/model-scores.json) and proposes a
 // rewritten ~/.config/lacode/pool.txt. It never partially writes and never
@@ -11,13 +11,14 @@
 //      descending, weight 4
 //   2. the best (10 - n) models from every provider other than opencode,
 //      sorted by score descending, weight 2
-//   3. at most one opencode model as a last resort, weight 2, with b:opencode
+//   3. exactly one opencode model as the reserved last slot, weight 2, with
+//      b:opencode, when a rankable opencode model exists
 //
-// Total = n + min(10 - n, #others), where n = #1.
+// Total = n + (others up to 10 - n - zen) + zen, where n = #1.
 //
 // This file ships as source and must run with plain `node` (ESM, no TS).
 
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs"
 import { execFileSync } from "node:child_process"
 import { homedir, userInfo } from "node:os"
 import { dirname, join, resolve } from "node:path"
@@ -34,6 +35,51 @@ export const STABLE_SELECTION = (home = HOME) => join(STABLE_LIB_DIR(home), "poo
 export const REFRESH_SERVICE_NAME = "lacode-refresh-pool.service"
 export const REFRESH_TIMER_NAME = "lacode-refresh-pool.timer"
 
+const REFRESH_LOCK_DIR = join(HOME, ".config", "lacode", "refresh.lock")
+const REFRESH_LOCK_STALE_MS = 60 * 60 * 1000
+
+/**
+ * One refresh at a time. The 6-hourly service and a transient retry timer can
+ * otherwise overlap and race on model-scores.json. A killed run leaves the lock
+ * behind, so a live PID keeps it only for an hour; a dead PID or a stale lock is
+ * reclaimed by the next run.
+ */
+function acquireRefreshLock() {
+  const take = () => {
+    mkdirSync(REFRESH_LOCK_DIR)
+    writeFileSync(join(REFRESH_LOCK_DIR, "pid"), String(process.pid))
+    return true
+  }
+  try {
+    return take()
+  } catch {}
+  try {
+    const stat = statSync(REFRESH_LOCK_DIR)
+    let pid = 0
+    try {
+      pid = Number(readFileSync(join(REFRESH_LOCK_DIR, "pid"), "utf8"))
+    } catch {}
+    let alive = false
+    if (Number.isFinite(pid) && pid > 0) {
+      try {
+        process.kill(pid, 0)
+        alive = true
+      } catch {}
+    }
+    if (alive && Date.now() - stat.mtimeMs < REFRESH_LOCK_STALE_MS) return false
+    rmSync(REFRESH_LOCK_DIR, { recursive: true, force: true })
+    return take()
+  } catch {
+    return false
+  }
+}
+
+function releaseRefreshLock() {
+  try {
+    rmSync(REFRESH_LOCK_DIR, { recursive: true, force: true })
+  } catch {}
+}
+
 const isSlotLine = (line) => {
   const stripped = String(line).split("#")[0].trim()
   return stripped.length > 0 && stripped.includes("/")
@@ -191,15 +237,21 @@ Wants=network-online.target
 
 [Service]
 Type=oneshot
+TimeoutStartSec=infinity
 ExecStart=${nodePath} ${scriptPath}
 Environment=PATH=${home}/.opencode/bin:/usr/local/bin:/usr/bin:/bin
 Nice=10
 `
   const timer = `[Unit]
-Description=Daily LaCode model pool refresh
+Description=LaCode model pool refresh every 6 hours
 
 [Timer]
-OnCalendar=*-*-* 01:00:00
+OnCalendar=*-*-* 00/6:00:00
+# A reboot kills a run mid-scan. Persistent=true does NOT retry that, because
+# systemd records the trigger when the service starts, not when it succeeds, so
+# the 6-hour slot is already spent even though the run never finished. A startup
+# trigger gives the next boot a fresh run even if the previous one was killed.
+OnStartupSec=5min
 Persistent=true
 Unit=${REFRESH_SERVICE_NAME}
 
@@ -243,6 +295,7 @@ function installTimerUnits(stable = false) {
   console.log(`installed ${units.servicePath}`)
   console.log(`installed ${units.timerPath}`)
   console.log(`enabled ${REFRESH_TIMER_NAME}`)
+  console.log(`refresh now: systemctl --user start ${REFRESH_SERVICE_NAME}`)
   return true
 }
 
@@ -251,9 +304,11 @@ function usage() {
 
   --from-scores     skip scoring, use the existing ~/.config/lacode/model-scores.json
   --no-retry        do not schedule a transient retry after a rate-limited run
-  --install-timer   install and enable a user systemd oneshot service + daily timer
-                    (add --stable to copy the script to ~/.local/lib/lacode and
-                    point ExecStart there, so plugin-cache updates do not break it)
+  --install-timer   install and enable a user systemd oneshot service + 6-hourly
+                    timer (add --stable to copy the script to ~/.local/lib/lacode
+                    and point ExecStart there, so plugin-cache updates do not break
+                    it). Refresh on demand with:
+                    systemctl --user start lacode-refresh-pool.service
   --print           print the proposed pool.txt and make no changes (alias: --dry-run)
   --dry-run         same as --print
   --max N           models per provider passed to the scorer (default: 50)
@@ -281,6 +336,14 @@ async function main() {
   const scoresPath = value("--scores", DEFAULT_SCORES_PATH)
   const poolPath = value("--pool", DEFAULT_POOL_PATH)
 
+  if (!printOnly) {
+    if (!acquireRefreshLock()) {
+      console.log("another LaCode pool refresh is already running; skipping this run")
+      return
+    }
+    process.once("exit", releaseRefreshLock)
+  }
+
   if (!fromScores) {
     try {
       runScorer(max)