@tonoid/agent-loop 1.0.0

package/src/check.ts

@@ -0,0 +1,126 @@
+import { existsSync } from "node:fs"
+import { dirname } from "node:path"
+import { parseConfig } from "./config"
+import { discover, loadWorkspace } from "./discover"
+import { TESTED_PROTOCOL } from "./adapters/herdr"
+import type { Kind } from "./kinds"
+import type { AccountConfig } from "./types"
+
+// Injected so the suite can check every branch without a real gh or herdr.
+export interface CheckDeps {
+  which(bin: string): string | null
+  ghAuth(): Promise<boolean>
+  protocol(): Promise<number>
+  herdrWorkspaces(): Promise<string[]>
+  readConfig(path: string): Promise<string | null>
+}
+
+// A worker started in a path its agent has never seen opens on a trust prompt,
+// reports itself idle behind it, and swallows the brief it is then sent, which
+// looks from the log like an agent that simply did not start. Claude records
+// trust per project directory and inherits it downwards, so one trusted
+// ancestor of worktreeBase covers every worktree ever made under it, and a
+// missing one costs every spawn on that account until somebody opens a session
+// by hand. A warning rather than a failure: the file belongs to another tool
+// and may yet record this differently.
+async function trusts(deps: CheckDeps, account: AccountConfig, base: string): Promise<boolean> {
+  if (account.provider !== "claude") return true
+  const text = await deps.readConfig(`${account.configDir}/.claude.json`)
+  if (text === null) return false
+  let projects: Record<string, { hasTrustDialogAccepted?: boolean }>
+  try {
+    projects = JSON.parse(text).projects ?? {}
+  } catch {
+    return true
+  }
+  for (let dir = base; ; dir = dirname(dir)) {
+    if (projects[dir]?.hasTrustDialogAccepted) return true
+    if (dirname(dir) === dir) return false
+  }
+}
+
+export async function runCheck(o: {
+  configPath: string
+  workspaceDir?: string
+  kinds: Record<string, Kind>
+  deps: CheckDeps
+}): Promise<{ lines: string[]; ok: boolean }> {
+  const lines: string[] = []
+  let ok = true
+  const fail = (line: string) => { ok = false; lines.push(line) }
+
+  // Cron's environment is nearly empty, and a setup that works in a login
+  // shell failing at 2am on PATH is the classic way this breaks.
+  for (const bin of ["gh", "git", "herdr"]) {
+    if (o.deps.which(bin)) lines.push(`${bin}: ok`)
+    else fail(`${bin}: not on PATH`)
+  }
+  if (await o.deps.ghAuth()) lines.push("gh: authenticated")
+  else fail("gh: not authenticated")
+
+  const protocol = await o.deps.protocol().catch(() => -1)
+  if (protocol !== TESTED_PROTOCOL) {
+    lines.push(`WARN herdr protocol ${protocol}, tested ${TESTED_PROTOCOL}`)
+  } else {
+    lines.push(`herdr protocol ${protocol}: ok`)
+  }
+
+  if (o.workspaceDir) {
+    // The one-folder form runs in a service repository's own CI, where there
+    // is no machine config and no accounts to check selectors against.
+    const { ws, errors } = loadWorkspace(o.workspaceDir, {
+      kinds: o.kinds,
+      accounts: [],
+      checkSelectors: false,
+    })
+    for (const e of errors) fail(e)
+    if (ws) lines.push(`${ws.name}: ${ws.jobs.length} job${ws.jobs.length === 1 ? "" : "s"} (${ws.jobs.map((j) => j.name).join(", ")})`)
+    lines.push("skipped: account selectors (no config.yml in this form)")
+    return { lines, ok }
+  }
+
+  const text = await o.deps.readConfig(o.configPath)
+  if (text === null) {
+    fail(`no config at ${o.configPath}`)
+    return { lines, ok }
+  }
+  const { config, errors: configErrors } = parseConfig(text)
+  for (const e of configErrors) fail(e)
+  if (configErrors.length) return { lines, ok }
+
+  // Every spawn resolves the herdr workspace by label, so a label that names
+  // nothing throws once per due item forever and never once at configure time.
+  // Unreadable is not the same as absent: a herdr that is not running fails
+  // every job below anyway, and guessing here would report the wrong one.
+  const labels = await o.deps.herdrWorkspaces().then((l) => l, () => null)
+  if (labels === null) lines.push("WARN could not ask herdr for its workspaces")
+
+  lines.push(`${config.accounts.length} account${config.accounts.length === 1 ? "" : "s"}: ${config.accounts.map((a) => a.id).join(", ")}`)
+  const { workspaces, errors } = discover(config, {
+    kinds: o.kinds,
+    accounts: config.accounts,
+    checkSelectors: true,
+  })
+  for (const e of errors) fail(e)
+  for (const ws of workspaces) {
+    lines.push(`${ws.name}: ${ws.jobs.length} job${ws.jobs.length === 1 ? "" : "s"} (${ws.jobs.map((j) => j.name).join(", ")})`)
+    // Spec 3.5: check resolves every path. A repos: entry pointing at a folder
+    // that was never cloned otherwise passes with exit 0 and then produces an
+    // ERROR ... sweep line every two minutes. Only in this form: the one-folder
+    // form runs in a service repository's CI, where the sibling trees may
+    // legitimately not be checked out.
+    for (const [key, path] of Object.entries(ws.repos)) {
+      if (!existsSync(path)) fail(`${ws.name}: repo "${key}" at ${path} does not exist`)
+      else if (!existsSync(`${path}/.git`)) fail(`${ws.name}: repo "${key}" at ${path} is not a git repository`)
+    }
+    if (labels !== null && !labels.includes(ws.herdrWorkspace)) {
+      fail(`${ws.name}: no herdr workspace labelled "${ws.herdrWorkspace}"${labels.length ? `; herdr has: ${labels.join(", ")}` : "; herdr has none"}`)
+    }
+    for (const account of config.accounts) {
+      if (!(await trusts(o.deps, account, ws.worktreeBase))) {
+        lines.push(`WARN ${ws.name}: account ${account.id} has not trusted ${ws.worktreeBase}; a worker there waits on the trust prompt and never reads its brief`)
+      }
+    }
+  }
+  return { lines, ok }
+}

package/src/cli-pause.ts

@@ -0,0 +1,16 @@
+import { existsSync } from "node:fs"
+
+// Pause blocks spawn only. Sweep and monitor always run: the monitor is what
+// removes a claim label from a merged PR, so a pause that froze it would
+// manufacture lying claims.
+export function pausedJobs(stateDir: string, jobs: string[]): string[] {
+  // Only `pause`, which is what pauseMarker writes for the workspace-wide
+  // form. A `pause-all` alias would make a job named "all", a legal job name,
+  // pause the whole workspace.
+  if (existsSync(`${stateDir}/pause`)) return [...jobs]
+  return jobs.filter((name) => existsSync(`${stateDir}/pause-${name}`))
+}
+
+export function pauseMarker(stateDir: string, job?: string): string {
+  return job ? `${stateDir}/pause-${job}` : `${stateDir}/pause`
+}

package/src/cli.ts

@@ -0,0 +1,290 @@
+#!/usr/bin/env bun
+import { loadConfig } from "./config"
+import { discover } from "./discover"
+import { KINDS, describeKind, kindSchema } from "./kinds"
+import { runCheck } from "./check"
+import { TESTED_PROTOCOL } from "./adapters/herdr"
+import { agentLoopHome } from "./paths"
+import { pausedJobs, pauseMarker } from "./cli-pause"
+import { openState } from "./state"
+import { makeCtx } from "./ctx"
+import { fileLock } from "./lock"
+import { makeGh } from "./adapters/gh"
+import { makeGit } from "./adapters/git"
+import { makeHerdr } from "./adapters/herdr"
+import { makeRunners } from "./adapters/run"
+import { runTick } from "./engine/tick"
+import { renderDecision } from "./render"
+import { existsSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs"
+import { openGlobalState } from "./globalstate"
+import { makeClaudeReader, liveClaudeDeps } from "./router/providers/claude"
+import { makeCodexReader, liveCodexDeps } from "./router/providers/codex"
+import { grokReader } from "./router/providers/grok"
+import type { Provider, UsageReader, WorkspaceConfig } from "./types"
+import { dirname } from "node:path"
+import { renderStatus } from "./status"
+import { adopt, renderMarks } from "./adopt"
+
+function arg(name: string): string | undefined {
+  const i = process.argv.indexOf(`--${name}`)
+  return i === -1 ? undefined : process.argv[i + 1]
+}
+
+// The one positional argument (a job name), which can appear anywhere
+// after the command, not just right after it: skip every flag and, for the
+// flags that take one, its value too.
+const FLAGS_WITH_VALUE = ["--workspace", "--config", "--state-dir", "--global-state"]
+function positionals(): string[] {
+  const out: string[] = []
+  const rest = process.argv.slice(3)
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i]!
+    if (FLAGS_WITH_VALUE.includes(a)) { i++; continue }
+    if (a.startsWith("--")) continue
+    out.push(a)
+  }
+  return out
+}
+const jobArg = (): string | undefined => positionals()[0]
+
+const cmd = process.argv[2]
+const live = process.argv.includes("--live")
+
+if (!["tick", "check", "kinds", "pause", "resume", "status", "adopt"].includes(cmd ?? "")) {
+  console.error(
+    "usage: agent-loop <tick|check|kinds|status|pause|resume|adopt> [--workspace <name>]\n" +
+    "                  [--config <path>] [--state-dir <path>] [--global-state <path>]\n" +
+    "                  [--live] [<job>] [<key>]\n" +
+    "       agent-loop adopt <job> [<key>] --workspace <name>   record a spawned mark\n" +
+    "       agent-loop adopt --list --workspace <name>          print this workspace's marks",
+  )
+  process.exit(2)
+}
+
+const stamp = () => new Date().toISOString().replace(/\.\d+Z$/, "Z")
+// The whole process, config load and discovery included. One cron line covers
+// every workspace on the box, so the interval has to cover the sum: 4.2's
+// cadence rule read against one workspace's share under-sizes it in
+// proportion to how many workspaces are on the box.
+const processStarted = Date.now()
+
+if (cmd === "kinds") {
+  const names = Object.keys(KINDS)
+  const want = jobArg()
+  const chosen = want ? [KINDS[want]].filter(Boolean) : names.map((n) => KINDS[n]!)
+  if (want && !chosen.length) {
+    console.error(`unknown kind "${want}"; known: ${names.join(", ")}`)
+    process.exit(2)
+  }
+  if (process.argv.includes("--json")) {
+    console.log(JSON.stringify(Object.fromEntries(chosen.map((k) => [k!.name, kindSchema(k!)])), null, 2))
+  } else {
+    for (const k of chosen) for (const line of describeKind(k!)) console.log(line)
+  }
+  process.exit(0)
+}
+
+if (cmd === "check") {
+  const positional = jobArg()
+  const { lines, ok } = await runCheck({
+    configPath: arg("config") ?? `${agentLoopHome()}/config.yml`,
+    workspaceDir: positional,
+    kinds: KINDS,
+    deps: {
+      which: (b) => Bun.which(b),
+      ghAuth: async () => makeRunners(false).runText(["gh", "auth", "status"]).then(() => true, () => false),
+      protocol: () => makeHerdr(makeRunners(false).runJson).protocol(),
+      herdrWorkspaces: async () =>
+        (await makeHerdr(makeRunners(false).runJson).workspaces()).map((w) => w.label),
+      readConfig: async (p) => (await Bun.file(p).exists()) ? Bun.file(p).text() : null,
+    },
+  })
+  for (const line of lines) console.log(line)
+  process.exit(ok ? 0 : 1)
+}
+
+// Below the read-only commands on purpose. `kinds` and `check` perform no
+// writes (spec 3.5), and the README sells `agent-loop check .` as a service
+// repository's CI check, where a writable home is not a given: opening the
+// store above would create ~/.agent-loop/state.db for a command that only
+// reads, and die with a raw EACCES stack trace before validating anything.
+const globalPath = arg("global-state") ?? `${agentLoopHome()}/state.db`
+mkdirSync(dirname(globalPath), { recursive: true })
+const global = openGlobalState(globalPath)
+
+const configPath = arg("config") ?? `${agentLoopHome()}/config.yml`
+const config = await loadConfig(configPath)
+
+const { workspaces: found, errors } = discover(config, {
+  kinds: KINDS,
+  accounts: config.accounts,
+  checkSelectors: true,
+})
+// Reported every tick, never once: a workspace that stops ticking silently is
+// the failure nobody notices.
+for (const reason of errors) console.log(`${stamp()} ${renderDecision({ pass: "error", where: "workspace", workspace: "-", reason })}`)
+
+const wsName = arg("workspace")
+if (wsName && !found.some((w) => w.name === wsName)) {
+  console.error(`unknown workspace "${wsName}"`)
+  process.exit(2)
+}
+const selected = wsName ? found.filter((w) => w.name === wsName) : found
+
+if (arg("state-dir") && selected.length !== 1) {
+  console.error("--state-dir applies to one workspace; pass --workspace too")
+  process.exit(2)
+}
+
+const stateDirFor = (name: string) => arg("state-dir") ?? `${agentLoopHome()}/${name}`
+
+if (cmd === "pause" || cmd === "resume") {
+  if (selected.length !== 1) {
+    console.error("pause and resume apply to one workspace; pass --workspace")
+    process.exit(2)
+  }
+  const ws = selected[0]!
+  const job = jobArg()
+  // Pause is the cutover and maintenance control: a typo'd job name must
+  // not report success while leaving the loop free to keep spawning it.
+  if (job && !ws.jobs.some((j) => j.name === job)) {
+    console.error(`unknown job "${job}" in workspace "${ws.name}"`)
+    process.exit(2)
+  }
+  const dir = stateDirFor(ws.name)
+  mkdirSync(dir, { recursive: true })
+  const marker = pauseMarker(dir, job)
+  if (cmd === "pause") writeFileSync(marker, "")
+  else if (existsSync(marker)) unlinkSync(marker)
+  console.log(`${cmd}d ${job ?? "the whole workspace"}`)
+  process.exit(0)
+}
+
+// status is inspection-only regardless of --live: only a tick's own spawn may
+// cause a token write-back.
+const readers: Record<Provider, UsageReader> = {
+  claude: makeClaudeReader(liveClaudeDeps(cmd === "tick" && live)),
+  codex: makeCodexReader(liveCodexDeps()),
+  grok: grokReader,
+}
+
+const { runText: rt, runJson: rj } = makeRunners(live)
+
+// Shared by the tick loop and by adopt, which needs a context only to ask a
+// routine which occurrence is due right now.
+const ctxFor = (ws: WorkspaceConfig, marks: ReturnType<typeof openState>) =>
+  makeCtx({
+    workspace: ws,
+    // The full discovered list, not `selected`: concurrency is an
+    // account-scoped fact across the whole box (spec 6.3 and 7), so a
+    // `--workspace` run ticking one workspace must still see live workers
+    // under every other one, or it over-admits against the account's ceiling.
+    workspaces: found,
+    config,
+    now: new Date(),
+    live,
+    sleep: (ms) => Bun.sleep(ms),
+    lock: fileLock(),
+    gh: makeGh(rj, rt),
+    gitFor: (repo) => makeGit(rt, repo),
+    herdr: makeHerdr(rj),
+    marks,
+    global,
+    usageFor: (a, at) => readers[a.provider](a, at),
+    memAvailableMb,
+    sink: (d) => console.log(`${stamp()} ${renderDecision(d, live)}`),
+  })
+
+if (cmd === "status") {
+  // One instant for the whole render: "resets in Xm" must be relative to the
+  // same now as the usage read that produced it.
+  const now = new Date()
+  const lines = await renderStatus({
+    now,
+    accounts: config.accounts,
+    usageFor: (a) => readers[a.provider](a, now),
+    refreshExpiryFor: async (a) => {
+      if (a.provider !== "claude") return null
+      const creds = await liveClaudeDeps(false).readCreds(a.configDir)
+      return creds?.refreshTokenExpiresAt ? new Date(creds.refreshTokenExpiresAt) : null
+    },
+    spawnsToday: global.spawnsSince(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate())),
+    workspaces: selected.map((ws) => ({
+      name: ws.name,
+      paused: pausedJobs(stateDirFor(ws.name), ws.jobs.map((j) => j.name)),
+    })),
+  })
+  for (const line of lines) console.log(line)
+  global.close()
+  process.exit(0)
+}
+
+// Below status and above the tick: adopt is the cutover's import path
+// (docs/cutover.md phase 2), so it writes the marks database on purpose and without
+// --live. It touches nothing else, and no process at all.
+if (cmd === "adopt") {
+  if (selected.length !== 1) {
+    console.error("adopt applies to one workspace; pass --workspace")
+    process.exit(2)
+  }
+  const ws = selected[0]!
+  const dir = stateDirFor(ws.name)
+  mkdirSync(dir, { recursive: true })
+  const marks = openState(`${dir}/state.db`)
+  try {
+    if (process.argv.includes("--list")) {
+      for (const line of renderMarks(marks.all(), new Date())) console.log(line)
+    } else {
+      const [name, wanted] = positionals()
+      const job = ws.jobs.find((j) => j.name === name)
+      if (!job) throw new Error(`unknown job "${name ?? ""}" in workspace "${ws.name}"`)
+      const { key, already } = await adopt(ctxFor(ws, marks), marks, job, wanted)
+      console.log(already ? `${job.name} ${key} was already recorded` : `adopted ${job.name} ${key}`)
+    }
+  } catch (e) {
+    console.error(String(e).replace(/^Error: /, ""))
+    marks.close()
+    global.close()
+    process.exit(2)
+  }
+  marks.close()
+  global.close()
+  process.exit(0)
+}
+
+// MemAvailable is the kernel's own estimate of what a new process can get
+// without swapping, which is the question being asked. Treat an unreadable
+// /proc as unlimited rather than blocking the loop on a parse failure.
+async function memAvailableMb(): Promise<number> {
+  try {
+    const m = (await Bun.file("/proc/meminfo").text()).match(/^MemAvailable:\s+(\d+) kB/m)
+    return m ? Math.round(Number(m[1]) / 1024) : Number.POSITIVE_INFINITY
+  } catch {
+    return Number.POSITIVE_INFINITY
+  }
+}
+
+const protocol = await makeHerdr(rj).protocol().catch(() => -1)
+if (protocol !== TESTED_PROTOCOL) {
+  console.log(`${stamp()} WARN herdr protocol ${protocol}, tested ${TESTED_PROTOCOL}`)
+}
+
+for (const ws of selected) {
+  const stateDir = stateDirFor(ws.name)
+  mkdirSync(stateDir, { recursive: true })
+  const marks = openState(`${stateDir}/state.db`)
+  try {
+    const ctx = ctxFor(ws, marks)
+    const names = ws.jobs.map((j) => j.name)
+    const paused = pausedJobs(stateDir, names)
+    await runTick(ctx, ws.jobs, { paused: paused.length === names.length, pausedJobs: paused })
+  } catch (e) {
+    // One service mid-edit or one unreachable remote must not stop the rest of
+    // the box for the next two minutes.
+    console.log(`${stamp()} ${renderDecision({ pass: "error", where: "workspace", workspace: ws.name, reason: String(e) })}`)
+  } finally {
+    marks.close()
+  }
+}
+console.log(`${stamp()} ${renderDecision({ pass: "tick", workspace: "total", ms: Date.now() - processStarted })}`)
+global.close()

package/src/config.ts

@@ -0,0 +1,211 @@
+import type { AccountConfig, Config, Provider } from "./types"
+import { expandHome } from "./paths"
+import { unknownKey } from "./kinds"
+import { isAbsolute } from "node:path"
+
+const KNOWN_PROVIDERS: Provider[] = ["claude", "codex", "grok"]
+
+// An unknown key is a typo, and a typo here is silent: `reserved: 40` leaves
+// the reserve at 0, so the one mechanism keeping the loop out of a human's
+// quota disappears with nothing said, and `maxSpawnsPerday: 5` leaves the
+// runaway circuit breaker at 200. Rejecting it is what makes `check` catch
+// this at the commit that broke it (spec 3.5).
+const CONFIG_KEYS = [
+  "accounts", "workspaces", "maxConcurrentPerAccount", "minFreeMb", "usageMax",
+  "releaseBefore", "maxSpawnsPerDay", "blockedTimeoutMin", "workerRateSeed",
+]
+const ACCOUNT_KEYS = [
+  "id", "provider", "configDir", "reserve", "reservePerWeekday", "weekendWeight", "soleConsumer", "maxConcurrent", "allowWhenUnreadable",
+  "agentKind", "startArgs", "model", "oauthClientId", "configEnv",
+]
+
+// Clamps have defaults so a working config.yml is accounts plus workspaces.
+// Every value here is the one the spec's example carries.
+export const DEFAULTS = {
+  maxConcurrentPerAccount: 4,
+  minFreeMb: 3000,
+  usageMax: 90,
+  releaseBefore: 120,
+  maxSpawnsPerDay: 200,
+  blockedTimeoutMin: 180,
+  workerRateSeed: 0.35,
+} as const
+
+// A selector names an account directly or names every account of a provider.
+export function selects(a: AccountConfig, selector: string): boolean {
+  return selector === a.id || selector === a.provider
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v)
+}
+
+function num(v: unknown, name: string, dflt: number, errs: string[]): number {
+  if (v === undefined || v === null) return dflt
+  if (typeof v !== "number" || !Number.isFinite(v)) {
+    errs.push(`${name} must be a number`)
+    return dflt
+  }
+  return v
+}
+
+function account(raw: unknown, i: number, errs: string[]): AccountConfig | null {
+  if (!isRecord(raw)) {
+    errs.push(`accounts[${i}] must be a mapping`)
+    return null
+  }
+  const id = typeof raw.id === "string" ? raw.id : ""
+  if (!id) {
+    errs.push(`accounts[${i}]: id is required`)
+    return null
+  }
+  for (const key of Object.keys(raw)) {
+    if (!ACCOUNT_KEYS.includes(key)) errs.push(`account "${id}": ${unknownKey(key, ACCOUNT_KEYS)}`)
+  }
+
+  const provider = raw.provider as Provider
+  if (!KNOWN_PROVIDERS.includes(provider)) {
+    errs.push(
+      `account "${id}": unknown provider "${String(raw.provider)}"; known: ${KNOWN_PROVIDERS.join(", ")}`,
+    )
+  }
+  if (typeof raw.configDir !== "string" || !raw.configDir) {
+    errs.push(`account "${id}": configDir is required`)
+  }
+  const reserve = num(raw.reserve, `account "${id}": reserve`, 0, errs)
+  if (reserve < 0 || reserve > 100) {
+    errs.push(`account "${id}": reserve must be between 0 and 100`)
+  }
+  const reservePerWeekday = num(raw.reservePerWeekday, `account "${id}": reservePerWeekday`, 0, errs)
+  if (reservePerWeekday < 0 || reservePerWeekday > 100) {
+    errs.push(`account "${id}": reservePerWeekday must be between 0 and 100`)
+  }
+  const weekendWeight = num(raw.weekendWeight, `account "${id}": weekendWeight`, 0.25, errs)
+  if (weekendWeight < 0 || weekendWeight > 1) {
+    errs.push(`account "${id}": weekendWeight must be between 0 and 1`)
+  }
+
+  const str = (v: unknown, field: string): string | undefined => {
+    if (v === undefined || v === null) return undefined
+    if (typeof v !== "string") { errs.push(`account "${id}": ${field} must be a string`); return undefined }
+    return v
+  }
+
+  let allowWhenUnreadable: boolean | undefined
+  if (raw.allowWhenUnreadable !== undefined && raw.allowWhenUnreadable !== null) {
+    if (typeof raw.allowWhenUnreadable !== "boolean") {
+      errs.push(`account "${id}": allowWhenUnreadable must be true or false`)
+    } else {
+      allowWhenUnreadable = raw.allowWhenUnreadable
+    }
+  }
+
+  let startArgs: string[] | undefined
+  if (raw.startArgs !== undefined && raw.startArgs !== null) {
+    if (!Array.isArray(raw.startArgs) || !raw.startArgs.every((s) => typeof s === "string")) {
+      errs.push(`account "${id}": startArgs must be a list of strings`)
+    } else {
+      startArgs = raw.startArgs
+    }
+  }
+
+  // maxConcurrent stays undefined rather than defaulted: the code downstream
+  // distinguishes "unset" from an explicit value, including an invalid one.
+  const maxConcurrentNum = num(raw.maxConcurrent, `account "${id}": maxConcurrent`, Number.NaN, errs)
+  const maxConcurrent = Number.isNaN(maxConcurrentNum) ? undefined : maxConcurrentNum
+
+  return {
+    id,
+    provider,
+    configDir: expandHome(typeof raw.configDir === "string" ? raw.configDir : ""),
+    reserve,
+    reservePerWeekday,
+    weekendWeight,
+    soleConsumer: raw.soleConsumer === true ? true : undefined,
+    maxConcurrent,
+    allowWhenUnreadable,
+    agentKind: str(raw.agentKind, "agentKind"),
+    startArgs,
+    model: str(raw.model, "model"),
+    oauthClientId: str(raw.oauthClientId, "oauthClientId"),
+    configEnv: str(raw.configEnv, "configEnv"),
+  }
+}
+
+// Returns every error rather than throwing at the first, because `check` prints
+// them all and an operator fixing one at a time is the slowest possible loop.
+export function parseConfig(text: string): { config: Config; errors: string[] } {
+  const errs: string[] = []
+  let raw: unknown
+  try {
+    raw = Bun.YAML.parse(text)
+  } catch (e) {
+    return { config: empty(), errors: [`config is not valid YAML: ${String(e)}`] }
+  }
+  if (!isRecord(raw)) return { config: empty(), errors: ["config must be a mapping of settings"] }
+
+  for (const key of Object.keys(raw)) {
+    if (!CONFIG_KEYS.includes(key)) errs.push(unknownKey(key, CONFIG_KEYS))
+  }
+
+  const accounts: AccountConfig[] = []
+  if (!Array.isArray(raw.accounts) || raw.accounts.length === 0) {
+    errs.push("accounts must be a non-empty list")
+  } else {
+    const seen = new Set<string>()
+    raw.accounts.forEach((a, i) => {
+      const parsed = account(a, i, errs)
+      if (!parsed) return
+      if (seen.has(parsed.id)) errs.push(`duplicate account id "${parsed.id}"`)
+      seen.add(parsed.id)
+      accounts.push(parsed)
+    })
+  }
+
+  const workspaces: string[] = []
+  if (!Array.isArray(raw.workspaces) || raw.workspaces.length === 0) {
+    errs.push("workspaces must be a non-empty list of paths")
+  } else {
+    raw.workspaces.forEach((p, i) => {
+      if (typeof p !== "string") errs.push(`workspaces[${i}] must be a path`)
+      else {
+        const expanded = expandHome(p)
+        // The path is used as given, from whatever directory cron started the
+        // tick in, so a relative one is silently a different folder depending
+        // on how the binary was invoked.
+        if (!isAbsolute(expanded)) errs.push(`workspaces[${i}] "${p}" must be an absolute path or start with ~`)
+        else workspaces.push(expanded)
+      }
+    })
+  }
+
+  const workerRateSeed = num(raw.workerRateSeed, "workerRateSeed", DEFAULTS.workerRateSeed, errs)
+  if (!(workerRateSeed > 0)) errs.push("workerRateSeed must be greater than 0")
+
+  return {
+    config: {
+      accounts,
+      workspaces,
+      maxConcurrentPerAccount: num(raw.maxConcurrentPerAccount, "maxConcurrentPerAccount", DEFAULTS.maxConcurrentPerAccount, errs),
+      minFreeMb: num(raw.minFreeMb, "minFreeMb", DEFAULTS.minFreeMb, errs),
+      usageMax: num(raw.usageMax, "usageMax", DEFAULTS.usageMax, errs),
+      releaseBefore: num(raw.releaseBefore, "releaseBefore", DEFAULTS.releaseBefore, errs),
+      maxSpawnsPerDay: num(raw.maxSpawnsPerDay, "maxSpawnsPerDay", DEFAULTS.maxSpawnsPerDay, errs),
+      blockedTimeoutMin: num(raw.blockedTimeoutMin, "blockedTimeoutMin", DEFAULTS.blockedTimeoutMin, errs),
+      workerRateSeed,
+    },
+    errors: errs,
+  }
+}
+
+function empty(): Config {
+  return { accounts: [], workspaces: [], ...DEFAULTS }
+}
+
+export async function loadConfig(path: string): Promise<Config> {
+  const file = Bun.file(path)
+  if (!(await file.exists())) throw new Error(`no config at ${path}`)
+  const { config, errors } = parseConfig(await file.text())
+  if (errors.length) throw new Error(`invalid config at ${path}:\n  ${errors.join("\n  ")}`)
+  return config
+}