@dirwin517/bot-farm 0.1.0

package/src/cli.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process"
+import { readFile, mkdir } from "node:fs/promises"
+import { homedir } from "node:os"
+import { join, resolve } from "node:path"
+import { Supervisor } from "./supervisor.mjs"
+import { startServer } from "./server.mjs"
+import { OpencodeClient } from "./api.mjs"
+import * as git from "./git.mjs"
+
+const HOME = join(homedir(), ".botfarm")
+const CONFIG = join(HOME, "config.json")
+const STATE = join(HOME, "metrics.json")
+
+const args = process.argv.slice(2)
+const cmd = args[0] ?? "up"
+const flags = parseFlags(args.slice(1))
+const positional = flags._
+
+const config = await loadConfig()
+const serverUrl = flags.server ?? config.server ?? "http://127.0.0.1:4096"
+
+switch (cmd) {
+  case "up":
+  case "dash":
+    await up()
+    break
+  case "ls":
+  case "list":
+    await ls()
+    break
+  case "new":
+  case "start":
+    await start()
+    break
+  case "send":
+    await send()
+    break
+  case "stop":
+  case "abort":
+    await stop()
+    break
+  case "rm":
+  case "delete":
+    await remove()
+    break
+  case "attach":
+    await attach()
+    break
+  default:
+    usage()
+}
+
+// ---------------------------------------------------------------------------
+
+async function up() {
+  await ensureServer(serverUrl, flags.serve !== false)
+  const port = Number(flags.port ?? config.port ?? 4777)
+  const repos = (flags.repo ? [].concat(flags.repo) : config.repos ?? []).map((p) => git.expandPath(p))
+
+  const supervisor = new Supervisor({
+    url: serverUrl,
+    statePath: STATE,
+    mcpBase: `http://127.0.0.1:${port}`,
+    pricing: config.pricing ?? {},
+    // The folder you open first. Change it with "defaultWorkspace" in
+    // ~/.botfarm/config.json, or add more folders from the app.
+    defaultWorkspace: git.expandPath(flags.workspace ?? config.defaultWorkspace ?? process.cwd()),
+  })
+  const dialect = await supervisor.start()
+  const { url } = startServer({ supervisor, port, repos })
+
+  console.log(`botfarm  dashboard  ${url}`)
+  console.log(`      opencode   ${serverUrl} (api ${dialect})`)
+  console.log(`      watching   ${supervisor.store.sessions.size} session(s), ${repos.length} repo(s)`)
+  if (flags.open !== false) openBrowser(url)
+
+  const bye = async () => { await supervisor.stop(); process.exit(0) }
+  process.on("SIGINT", bye)
+  process.on("SIGTERM", bye)
+}
+
+async function ls() {
+  const client = await connect()
+  const sessions = await client.listSessions({ limit: 100 })
+  const active = (await client.activeSessionIds()) ?? new Set()
+  const rows = sessions.map((s) => ({
+    id: s.id,
+    status: active.has(s.id) ? "busy" : "idle",
+    title: (s.title ?? "").slice(0, 34),
+    dir: (s.directory ?? s.location?.directory ?? "").replace(homedir(), "~"),
+  }))
+  if (rows.length === 0) return console.log("no sessions")
+  const w = (k, min) => Math.max(min, ...rows.map((r) => String(r[k]).length))
+  const cols = { id: w("id", 2), status: 6, title: w("title", 5) }
+  console.log(pad("id", cols.id), pad("status", cols.status), pad("title", cols.title), "directory")
+  for (const r of rows) console.log(pad(r.id, cols.id), pad(r.status, cols.status), pad(r.title, cols.title), r.dir)
+}
+
+async function start() {
+  const repo = git.expandPath(positional[0] ?? process.cwd())
+  const branch = flags.branch ?? flags.b ?? null
+  const supervisor = new Supervisor({ url: serverUrl, statePath: STATE })
+  await supervisor.client.connect()
+  const root = (await git.repoRoot(repo)) ?? repo
+  let directory = root
+  if (branch) {
+    const wt = await git.addWorktree(root, branch, { path: flags.path })
+    directory = wt.path
+    console.log(`${wt.reused ? "reusing" : "created"} worktree ${wt.path} (${wt.branch})`)
+  }
+  const info = await supervisor.client.createSession({
+    title: flags.name ?? branch ?? "botfarm session",
+    directory,
+    agent: flags.agent,
+    model: flags.model,
+  })
+  const task = flags.task ?? positional[1]
+  if (task) await supervisor.client.prompt(info.id, task)
+  console.log(`${info.id}  ${directory}${task ? `  <- "${task.slice(0, 50)}"` : ""}`)
+}
+
+async function send() {
+  const client = await connect()
+  const id = positional[0]
+  const text = positional.slice(1).join(" ") || flags.text
+  if (!id || !text) return usage()
+  await client.prompt(id, text)
+  console.log(`queued -> ${id}`)
+}
+
+async function stop() {
+  const client = await connect()
+  const ids = positional.length ? positional : [...(await client.activeSessionIds() ?? [])]
+  for (const id of ids) {
+    await client.interrupt(id)
+    console.log(`aborted ${id}`)
+  }
+}
+
+async function remove() {
+  const client = await connect()
+  const id = positional[0]
+  if (!id) return usage()
+  const info = await client.getSession(id).catch(() => null)
+  await client.deleteSession(id)
+  if (flags.worktree && info?.directory) {
+    const root = await git.commonDir(info.directory)
+    if (root && root !== info.directory) await git.removeWorktree(root, info.directory, { force: !!flags.force })
+    console.log(`removed worktree ${info.directory}`)
+  }
+  console.log(`removed ${id}`)
+}
+
+async function attach() {
+  const client = await connect()
+  const id = positional[0]
+  if (!id) return usage()
+  const info = await client.getSession(id)
+  const dir = info.directory ?? info.location?.directory ?? process.cwd()
+  console.log(`attaching to ${id} in ${dir}`)
+  spawn("opencode", ["--session", id], { cwd: dir, stdio: "inherit" }).on("exit", (c) => process.exit(c ?? 0))
+}
+
+// ---------------------------------------------------------------------------
+
+async function connect() {
+  const client = new OpencodeClient(serverUrl)
+  await client.connect()
+  return client
+}
+
+async function ensureServer(url, allowSpawn) {
+  const probe = new OpencodeClient(url)
+  try {
+    await probe.connect()
+    return
+  } catch {}
+  if (!allowSpawn) throw new Error(`no opencode server at ${url}`)
+  const { port, hostname } = new URL(url)
+  console.log(`starting opencode serve on ${hostname}:${port}`)
+  const child = spawn("opencode", ["serve", "--port", port, "--hostname", hostname], {
+    stdio: "ignore",
+    detached: true,
+  })
+  child.unref()
+  for (let i = 0; i < 40; i++) {
+    await new Promise((r) => setTimeout(r, 500))
+    try {
+      await new OpencodeClient(url).connect()
+      return
+    } catch {}
+  }
+  throw new Error("opencode serve did not come up in 20s")
+}
+
+async function loadConfig() {
+  await mkdir(HOME, { recursive: true })
+  try {
+    return JSON.parse(await readFile(CONFIG, "utf8"))
+  } catch {
+    return {}
+  }
+}
+
+function parseFlags(argv) {
+  const out = { _: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith("--no-")) out[a.slice(5)] = false
+    else if (a.startsWith("--")) {
+      const [k, v] = a.slice(2).split("=")
+      const value = v ?? (argv[i + 1]?.startsWith("--") ? true : argv[++i] ?? true)
+      if (out[k] === undefined) out[k] = value
+      else out[k] = [].concat(out[k], value)
+    } else if (a.startsWith("-") && a.length === 2) out[a[1]] = argv[++i]
+    else out._.push(a)
+  }
+  return out
+}
+
+const pad = (s, n) => String(s).padEnd(n)
+
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open"
+  spawn(cmd, [url], { stdio: "ignore", detached: true }).on("error", () => {}).unref()
+}
+
+function usage() {
+  console.log(`botfarm — process manager for opencode sessions
+
+  botfarm up [--port 4777] [--server URL] [--repo PATH]...   dashboard (default)
+  botfarm ls                                                 list sessions
+  botfarm new <repo> [task] --branch NAME [--agent A]        new session in a worktree
+  botfarm send <id> <text...>                                queue a prompt
+  botfarm stop [id...]                                       interrupt (all busy if omitted)
+  botfarm rm <id> [--worktree] [--force]                     delete session, optionally its worktree
+  botfarm attach <id>                                        open the session in the opencode TUI
+
+config: ~/.botfarm/config.json  { "server": "http://127.0.0.1:4096", "port": 4777, "repos": ["~/code/app"] }`)
+}

package/src/craft.mjs

@@ -0,0 +1,172 @@
+// Small, model-free helpers that keep bots cheap and on track:
+//
+//   difficulty()   how hard a card looks, from its text — for model routing
+//   trimHandoff()  a handoff squeezed to what the next bot needs (rules, or a
+//                  local model when one is configured)
+//   stuckReason()  a bot going round in circles, from its recent tool calls
+//
+// None of these call a paid model. They run on every dispatch / tick, so they
+// have to be fast and they must never throw.
+
+// --- difficulty -------------------------------------------------------------
+
+const HARD = /\b(architect|architecture|redesign|refactor|migrat|concurren|race condition|deadlock|security|auth[nz]?|encrypt|performance|optimi[sz]|distributed|transaction|schema change|breaking change|rewrite|multi-?tenant|cache invalidation|design)\w*/gi
+const EASY = /\b(typo|rename|docs?|documentation|readme|comment|log(ging)? line|bump|version|lint|format|copy change|label|text change|config value|flag|toggle|small|trivial|one-?line)\b/gi
+
+/**
+ * easy | normal | hard for a card. Explicit wins: a split item or a stage can
+ * say `difficulty:`. Otherwise a score from the words in it, its length and
+ * how many criteria it has to satisfy.
+ */
+export function difficulty({ explicit = null, title = "", detail = "", story = "", criteria = [], files = [] } = {}) {
+  if (["easy", "normal", "hard"].includes(explicit)) return { level: explicit, why: "set explicitly" }
+  const text = `${title}\n${detail || story}`.slice(0, 20000)
+  const hard = new Set((text.match(HARD) ?? []).map((w) => w.toLowerCase().slice(0, 10)))
+  const easy = new Set((text.match(EASY) ?? []).map((w) => w.toLowerCase()))
+  let score = 0
+  const why = []
+  if (hard.size) { score += Math.min(2, hard.size); why.push(`mentions ${[...hard].slice(0, 3).join(", ")}`) }
+  if (easy.size && !hard.size) { score -= 1; why.push(`looks small (${[...easy].slice(0, 3).join(", ")})`) }
+  if (text.length > 2500) { score += 1; why.push("long description") }
+  else if (text.length < 120 && !hard.size) { score -= 1; why.push("short description") }
+  if (criteria.length > 8) { score += 1; why.push(`${criteria.length} criteria`) }
+  if (files.length > 12) { score += 1; why.push(`${files.length} files`) }
+  const level = score >= 2 ? "hard" : score <= -1 ? "easy" : "normal"
+  return { level, why: why.join("; ") || "nothing stands out" }
+}
+
+/**
+ * The model and reasoning level for a card of this difficulty, from the
+ * agent's `tiers:` or the workspace routing file. null when routing is off
+ * or has nothing for this level.
+ */
+export function routeFor(level, { agentTiers = null, routing = null } = {}) {
+  // Per level: the agent's own rule when it has one for this size, otherwise the
+  // workspace's (when workspace routing is on). An agent can override just "hard".
+  const set = (t) => t && typeof t === "object" && (t.model || t.variant)
+  const own = agentTiers?.[level]
+  const t = set(own) ? own : routing?.enabled ? routing.tiers?.[level] : null
+  if (!set(t)) return null
+  const out = { source: set(own) ? "agent" : "workspace" }
+  if (t.model) out.model = String(t.model)
+  if (t.variant) out.variant = String(t.variant)
+  // A quota on the tier's model, and where to go when it is used up.
+  if (t.model && t.quota && typeof t.quota === "object") {
+    out.quota = { ...t.quota, per: ["day", "week", "month", "workstream"].includes(t.quota.per) ? t.quota.per : "day" }
+    out.fallback = t.fallback && typeof t.fallback === "object" ? { ...(t.fallback.model ? { model: String(t.fallback.model) } : {}), ...(t.fallback.variant ? { variant: String(t.fallback.variant) } : {}) } : {}
+  }
+  return Object.keys(out).length ? out : null
+}
+
+// --- trimming handoffs -------------------------------------------------------
+
+/**
+ * Squeeze text by rules alone: long code blocks become a one-line pointer,
+ * blank runs and repeated lines go, and it is cut at a sentence near `max`.
+ * Roughly 4 characters per token, so the default is ~450 tokens.
+ */
+export function trimText(text, max = 1800) {
+  let s = String(text ?? "").replace(/\r/g, "")
+  s = s.replace(/```[^\n]*\n([\s\S]*?)```/g, (m, body) => {
+    const n = body.split("\n").length
+    return n > 12 ? `[code block, ${n} lines — in the full handoff (botfarm_handoff)]` : m
+  })
+  const seen = new Set()
+  s = s.split("\n").map((l) => l.replace(/\s+$/, "")).filter((l) => {
+    const k = l.trim().toLowerCase()
+    if (k.length > 30 && seen.has(k)) return false
+    if (k.length > 30) seen.add(k)
+    return true
+  }).join("\n").replace(/\n{3,}/g, "\n\n").trim()
+  if (s.length <= max) return s
+  const cut = s.slice(0, max)
+  const end = Math.max(cut.lastIndexOf(". "), cut.lastIndexOf(".\n"), cut.lastIndexOf("\n- "), cut.lastIndexOf("\n\n"))
+  return (end > max * 0.6 ? cut.slice(0, end + 1) : cut).trimEnd() + ` … [${s.length - (end > max * 0.6 ? end + 1 : max)} more characters in the full handoff — botfarm_handoff]`
+}
+
+/**
+ * A handoff as the next bot will read it: the summary trimmed, long lists
+ * capped. The full handoff stays on the card and behind botfarm_handoff.
+ */
+export function trimHandoff(h, { maxChars = 1800, partChars = 500 } = {}) {
+  if (!h) return h
+  const cap = (list, n, label) => (list?.length > n ? [...list.slice(0, n), `… and ${list.length - n} more ${label}`] : list ?? [])
+  const summary = h.parts?.length
+    ? h.parts.map((p, i) => `[${i + 1}/${h.parts.length}] ${p.title}: ${trimText(p.summary, partChars)}`).join("\n\n")
+    : h.brief ?? trimText(h.summary, maxChars)
+  return {
+    ...h,
+    summary,
+    acceptance_criteria: (h.acceptance_criteria ?? []).map((a) => trimText(a, 300)),
+    artifacts: cap(h.artifacts, 40, "files"),
+    open_questions: cap(h.open_questions, 12, "questions"),
+  }
+}
+
+/**
+ * Optional: have a local model (Ollama-compatible /api/generate) write the
+ * brief. Falls back to the rules on any error or after `timeoutMs`.
+ */
+export async function localBrief(text, { url, model, maxChars = 1800, timeoutMs = 20_000 } = {}) {
+  if (!url || !model || String(text ?? "").length <= maxChars) return trimText(text, maxChars)
+  const ctl = new AbortController()
+  const timer = setTimeout(() => ctl.abort(), timeoutMs)
+  try {
+    const res = await fetch(new URL("/api/generate", url), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      signal: ctl.signal,
+      body: JSON.stringify({
+        model,
+        stream: false,
+        options: { temperature: 0.1, num_predict: Math.ceil(maxChars / 3) },
+        prompt: `Rewrite this developer handoff for the next engineer in at most ${Math.round(maxChars / 5)} words. Keep every file path, identifier, decision, open problem and number exactly. Drop pleasantries and narration. Plain text, no preamble.\n\n---\n${String(text).slice(0, 24000)}`,
+      }),
+    })
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const out = String((await res.json()).response ?? "").trim()
+    return out ? trimText(out, maxChars) : trimText(text, maxChars)
+  } catch {
+    return trimText(text, maxChars)
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+// --- loops -------------------------------------------------------------------
+
+// Only used to tell a legitimate repeated call (editing the same file twice) from a loop.
+// Whether files actually changed is asked of git, not guessed from tool names.
+const EDITS = /edit|write|patch|replace/i
+
+/**
+ * Why a bot looks stuck on its card, or null. Only its calls since the card
+ * started count. Three signals, all cheap:
+ *   - the same call (tool + input) three times in the last six
+ *   - its last five calls all failed
+ *   - a lot of tokens with no file changed, for a bot that is meant to edit
+ */
+export function stuckReason(calls, { tokens = 0, canEdit = true, tokenCeiling = 250_000, edited = undefined } = {}) {
+  const recent = calls.slice(-6)
+  const counts = new Map()
+  for (const c of recent) {
+    // The same call means the same tool with exactly the same arguments: a
+    // grep for three different things is work, not a loop. A file changing in
+    // between (build, edit, build) starts the count again.
+    if (EDITS.test(c.name)) { counts.clear(); continue }
+    const args = c.sig ?? (c.summary ? `s:${c.summary}` : null)
+    if (args === null) continue // arguments unknown: cannot tell, so do not guess
+    const k = `${c.name}\u0000${args}`
+    counts.set(k, (counts.get(k) ?? 0) + 1)
+    if (counts.get(k) >= 3 && !EDITS.test(c.name)) return { kind: "loop", why: `repeated ${c.name}${c.summary ? ` "${String(c.summary).slice(0, 60)}"` : ""} ${counts.get(k)} times` }
+  }
+  const last5 = calls.slice(-5)
+  if (last5.length === 5 && last5.every((c) => c.status === "error")) return { kind: "loop", why: `its last 5 tool calls failed (${[...new Set(last5.map((c) => c.name))].join(", ")})` }
+  // "edited" comes from git (did any file change since the card started, by any
+  // tool or MCP server); without it, fall back to the tool names.
+  const changedFiles = edited ?? calls.some((c) => EDITS.test(c.name))
+  if (canEdit && tokens > tokenCeiling && calls.length >= 15 && !changedFiles) {
+    return { kind: "loop", why: `${Math.round(tokens / 1000)}k tokens and ${calls.length} tool calls without changing a file` }
+  }
+  return null
+}

package/src/db.mjs

@@ -0,0 +1,93 @@
+// A very small document store: tables of JSON rows keyed by id.
+//
+// Runtime state (pipeline runs, tasks, handoffs) lives here. Definitions
+// (personas, pipelines) stay in YAML files, because config that people edit
+// and share in git should not live inside a binary. Two sources of truth is a
+// bug factory, so the split is by *kind*: YAML in, YAML out, database only in
+// the middle.
+//
+// node:sqlite is used when the runtime has it (Node 22.5+) and a JSON file
+// otherwise — the interface is identical, so nothing above here cares.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs"
+import { dirname } from "node:path"
+
+export async function openDb(path) {
+  try {
+    const { DatabaseSync } = await import("node:sqlite")
+    mkdirSync(dirname(path), { recursive: true })
+    return new SqliteStore(new DatabaseSync(path))
+  } catch {
+    return new JsonStore(path.replace(/\.db$/, ".json"))
+  }
+}
+
+class SqliteStore {
+  constructor(db) {
+    this.db = db
+    this.kind = "sqlite"
+    this.tables = new Set()
+  }
+  table(name) {
+    if (!this.tables.has(name)) {
+      this.db.exec(`CREATE TABLE IF NOT EXISTS ${safe(name)} (id TEXT PRIMARY KEY, data TEXT NOT NULL)`)
+      this.tables.add(name)
+    }
+    return safe(name)
+  }
+  put(name, row) {
+    const t = this.table(name)
+    this.db.prepare(`INSERT INTO ${t} (id, data) VALUES (?, ?) ON CONFLICT(id) DO UPDATE SET data = excluded.data`)
+      .run(row.id, JSON.stringify(row))
+    return row
+  }
+  get(name, id) {
+    const r = this.db.prepare(`SELECT data FROM ${this.table(name)} WHERE id = ?`).get(id)
+    return r ? JSON.parse(r.data) : null
+  }
+  all(name) {
+    return this.db.prepare(`SELECT data FROM ${this.table(name)}`).all().map((r) => JSON.parse(r.data))
+  }
+  delete(name, id) {
+    this.db.prepare(`DELETE FROM ${this.table(name)} WHERE id = ?`).run(id)
+  }
+  close() {
+    try { this.db.close() } catch {}
+  }
+}
+
+class JsonStore {
+  constructor(path) {
+    this.path = path
+    this.kind = "json"
+    this.data = {}
+    if (existsSync(path)) {
+      try { this.data = JSON.parse(readFileSync(path, "utf8")) } catch {}
+    }
+  }
+  flush() {
+    mkdirSync(dirname(this.path), { recursive: true })
+    writeFileSync(this.path, JSON.stringify(this.data))
+  }
+  put(name, row) {
+    ;(this.data[name] ??= {})[row.id] = row
+    this.flush()
+    return row
+  }
+  get(name, id) {
+    return this.data[name]?.[id] ?? null
+  }
+  all(name) {
+    return Object.values(this.data[name] ?? {})
+  }
+  delete(name, id) {
+    delete this.data[name]?.[id]
+    this.flush()
+  }
+  close() {}
+}
+
+function safe(name) {
+  if (!/^[a-z_][a-z0-9_]*$/i.test(name)) throw new Error(`bad table name: ${name}`)
+  return name
+}

package/src/farmhands.mjs

@@ -0,0 +1,111 @@
+// Levels, hats and harvests. Light on purpose: XP comes from work that landed
+// cleanly and cheaply — a handoff, no pause for a limit or a loop, well under
+// budget — never from tokens spent or tools called, so levelling up and saving
+// money point the same way.
+//
+// XP belongs to a kind of bot in a workspace ("dev" in one workspace),
+// not to one session: sessions come and go, the Dev Bot keeps its hat.
+
+export const LEVELS = [0, 30, 80, 160, 280, 450, 700, 1000, 1400, 1900]
+export const HATS = [null, "🧢", "🎩", "👒", "⛑️", "🎓", "👑", "🪖", "🎀", "🌟"]
+export const TITLES = ["Seedling", "Sprout", "Farmhand", "Grower", "Harvester", "Foreman", "Rancher", "Steward", "Legend", "Mythic"]
+
+/** What each level unlocks. Functional perks are small and only ever make a bot a little more trusted. */
+export const PERKS = [
+  { level: 2, id: "hat", label: "A cap on the farm", kind: "cosmetic" },
+  { level: 3, id: "seasoned", label: "Seasoned: card limits +10%", kind: "budget", bonus: 0.1 },
+  { level: 4, id: "hat2", label: "A sun hat", kind: "cosmetic" },
+  { level: 5, id: "trusted", label: "Trusted: the first limit hit on a card extends itself once (+25%) instead of stopping", kind: "autoextend" },
+  { level: 6, id: "crown", label: "The crown, and a gold name on the farm", kind: "cosmetic" },
+  { level: 8, id: "veteran", label: "Veteran: card limits +20%", kind: "budget", bonus: 0.2 },
+]
+
+export function levelOf(xp) {
+  let level = 1
+  for (let i = 0; i < LEVELS.length; i++) if (xp >= LEVELS[i]) level = i + 1
+  const next = LEVELS[level] ?? null
+  const prev = LEVELS[level - 1] ?? 0
+  return { level, xp, next, progress: next ? (xp - prev) / (next - prev) : 1, hat: HATS[level - 1] ?? "🌟", title: TITLES[level - 1] ?? "Mythic" }
+}
+
+export function perksAt(level) {
+  return PERKS.filter((p) => p.level <= level)
+}
+
+/** How much a card's limits grow for this level (Seasoned, Veteran). */
+export function budgetBonus(level) {
+  return perksAt(level).filter((p) => p.kind === "budget").reduce((a, p) => Math.max(a, p.bonus), 0)
+}
+
+/**
+ * XP for one finished card, with the reasons. `usage` and `limits` are the
+ * card's; `paused` says whether it ever stopped for a limit or a loop.
+ */
+export function xpForCard({ task, usage = null, paused = false, openQuestions = 0 }) {
+  const parts = [["handed off", 10]]
+  if (!paused) parts.push(["no pauses", 5])
+  const lim = task.limits
+  if (lim && usage) {
+    const frac = Math.max(0, ...Object.entries(lim).map(([k, v]) => (usage[k] ?? 0) / v))
+    if (frac <= 0.5) parts.push(["under half its limit", 5])
+  }
+  if (!openQuestions) parts.push(["nothing left open", 3])
+  if (task.item) parts.push(["one piece of a split", 2])
+  return { xp: parts.reduce((a, [, n]) => a + n, 0), reasons: parts }
+}
+
+export class Farmhands {
+  constructor({ db }) {
+    this.db = db
+  }
+
+  key(wsId, persona) { return `${wsId ?? "none"}:${persona}` }
+
+  get(wsId, persona) {
+    const row = this.db.get("xp", this.key(wsId, persona)) ?? { id: this.key(wsId, persona), ws: wsId ?? null, persona, xp: 0, cards: 0, clean: 0, history: [] }
+    return { ...row, ...levelOf(row.xp) }
+  }
+
+  all(wsId) {
+    return this.db.all("xp").filter((r) => !wsId || r.ws === wsId).map((r) => ({ ...r, ...levelOf(r.xp), perks: perksAt(levelOf(r.xp).level) }))
+  }
+
+  /** Add XP; returns { before, after, gained, levelUp }. */
+  award(wsId, persona, gained, { reasons = [], card = null } = {}) {
+    const row = this.db.get("xp", this.key(wsId, persona)) ?? { id: this.key(wsId, persona), ws: wsId ?? null, persona, xp: 0, cards: 0, clean: 0, history: [] }
+    const before = levelOf(row.xp)
+    row.xp += gained
+    row.cards += 1
+    if (reasons.some(([r]) => r === "no pauses")) row.clean += 1
+    row.history = [...(row.history ?? []), { at: Date.now(), xp: gained, card, reasons: reasons.map(([r, n]) => `${r} +${n}`) }].slice(-40)
+    this.db.put("xp", row)
+    const after = levelOf(row.xp)
+    return { before, after, gained, levelUp: after.level > before.level ? after : null }
+  }
+
+  // --- harvests -------------------------------------------------------------
+
+  saveHarvest(h) {
+    this.db.put("harvests", h)
+    return h
+  }
+
+  harvests(wsId, sinceMs = 0) {
+    return this.db.all("harvests").filter((h) => (!wsId || h.ws === wsId) && h.at >= sinceMs).sort((a, b) => b.at - a.at)
+  }
+
+  /** This week and all time, for the harvest log. */
+  totals(wsId) {
+    const week = Date.now() - 7 * 86400_000
+    const sum = (list) => list.reduce((a, h) => ({
+      stories: a.stories + 1,
+      cards: a.cards + (h.cards ?? 0),
+      usd: a.usd + (h.usd ?? 0),
+      saved: a.saved + Math.max(0, h.saved ?? 0),
+      botMinutes: a.botMinutes + (h.botMinutes ?? 0),
+      xp: a.xp + (h.xp ?? 0),
+    }), { stories: 0, cards: 0, usd: 0, saved: 0, botMinutes: 0, xp: 0 })
+    const all = this.harvests(wsId)
+    return { week: sum(all.filter((h) => h.at >= week)), all: sum(all), recent: all.slice(0, 12) }
+  }
+}