spinuptui 1.3.0-alpha.1 → 1.3.0-alpha.2

package/src/lib/schedule.ts

@@ -0,0 +1,156 @@
+// Scheduler's clock rules: parsing `when:` / `every:` / `expires:` and deciding
+// which slot (if any) is due. A straight port of the git-backed job runner's
+// rules, deliberately identical — both dispatchers read the same state.json
+// during a cutover, so they must reach the same decision from it (see
+// docs/2026-10-20_scheduler-spec.md, "Cutover").
+//
+// All times are the station's local time, written "YYYY-MM-DD HH:MM".
+
+export const DAYS = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"] as const
+
+export type Schedule = { type: "interval"; minutes: number } | { type: "calendar"; days: Set<number>; hour: number; minute: number }
+
+// Monday = 0, matching the prior art (Python's weekday()).
+export function weekday(d: Date): number {
+  return (d.getDay() + 6) % 7
+}
+
+const pad = (n: number) => String(n).padStart(2, "0")
+
+export function fmt(d: Date | null | undefined): string {
+  if (!d) return ""
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`
+}
+
+export function fmtDate(d: Date): string {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
+}
+
+export function parseWhen(value: string): Date {
+  const m = value.trim().match(/^(\d{4})-(\d{2})-(\d{2}) (\d{1,2}):(\d{2})$/)
+  const d = m ? new Date(+m[1]!, +m[2]! - 1, +m[3]!, +m[4]!, +m[5]!) : null
+  if (!d || d.getMonth() !== +m![2]! - 1 || d.getDate() !== +m![3]! || +m![4]! > 23 || +m![5]! > 59) {
+    throw new Error(`when:/created: must look like 2026-10-16 08:00 (station local time), got "${value}"`)
+  }
+  return d
+}
+
+// A date-only value (expires:), as that day's local midnight.
+export function parseDate(value: string): Date {
+  const m = value.trim().match(/^(\d{4})-(\d{2})-(\d{2})$/)
+  const d = m ? new Date(+m[1]!, +m[2]! - 1, +m[3]!) : null
+  if (!d || d.getMonth() !== +m![2]! - 1 || d.getDate() !== +m![3]!) {
+    throw new Error(`expires: must look like 2026-10-20, got "${value}"`)
+  }
+  return d
+}
+
+export function parseEvery(value: string): Schedule {
+  const v = value.trim().toLowerCase()
+  let m = v.match(/^(\d+)\s*([mh])$/)
+  if (m) {
+    const minutes = +m[1]! * (m[2] === "h" ? 60 : 1)
+    if (minutes < 5) throw new Error("every: intervals are 5m or longer")
+    return { type: "interval", minutes }
+  }
+  m = v.match(/^([a-z,]+)\s+(\d{1,2}):(\d{2})$/)
+  if (!m) throw new Error(`every: is like '30m', '6h', 'daily 08:00', 'weekdays 08:00' or 'mon,thu 08:00', got "${value}"`)
+  const hour = +m[2]!
+  const minute = +m[3]!
+  if (hour > 23 || minute > 59) throw new Error(`every: time out of range in "${value}"`)
+  let days: Set<number>
+  if (m[1] === "daily") days = new Set([0, 1, 2, 3, 4, 5, 6])
+  else if (m[1] === "weekdays") days = new Set([0, 1, 2, 3, 4])
+  else {
+    days = new Set()
+    for (const d of m[1]!.split(",")) {
+      const i = (DAYS as readonly string[]).indexOf(d)
+      if (i === -1) throw new Error(`every: unknown day "${d}" (use ${DAYS.join(",")})`)
+      days.add(i)
+    }
+  }
+  return { type: "calendar", days, hour, minute }
+}
+
+// A module job's `every: "10m"` / `at: "08:00"` as a Schedule.
+export function declSchedule(decl: { every?: string; at?: string }): Schedule {
+  if (decl.every) return parseEvery(decl.every)
+  if (decl.at) return parseEvery(`daily ${decl.at}`)
+  throw new Error("a scheduled job needs every: or at:")
+}
+
+export interface ScheduleState {
+  last_run?: string
+  last_scheduled?: string
+  retry_after?: string
+}
+
+export interface DueInput {
+  when?: string
+  every?: string
+  schedule?: Schedule
+  expires?: string
+  created?: string
+}
+
+function minuteOf(d: Date): Date {
+  const out = new Date(d)
+  out.setSeconds(0, 0)
+  return out
+}
+
+function dayStart(d: Date): number {
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime()
+}
+
+// The scheduled time this run is for, or null when nothing is due.
+export function dueOccurrence(job: DueInput, state: ScheduleState, now: Date): Date | null {
+  if (job.expires && dayStart(now) > parseDate(job.expires).getTime()) return null
+  if (state.retry_after && now < parseWhen(state.retry_after)) return null
+  const lastSched = state.last_scheduled ? parseWhen(state.last_scheduled) : null
+
+  if (job.when) {
+    const when = parseWhen(job.when)
+    if (now >= when && lastSched?.getTime() !== when.getTime()) return when
+    return null
+  }
+
+  const sched = job.schedule ?? parseEvery(job.every!)
+  const created = job.created ? parseWhen(job.created) : null
+  if (sched.type === "interval") {
+    const lastRun = state.last_run ? parseWhen(state.last_run) : null
+    const start = lastRun ?? created
+    if (!start || now.getTime() >= start.getTime() + sched.minutes * 60_000) return minuteOf(now)
+    return null
+  }
+
+  // Calendar: the latest occurrence at or before now. Missed ones collapse into
+  // a single catch-up run instead of a backlog.
+  for (let back = 0; back < 8; back++) {
+    const day = new Date(now.getFullYear(), now.getMonth(), now.getDate() - back)
+    const occ = new Date(day.getFullYear(), day.getMonth(), day.getDate(), sched.hour, sched.minute)
+    if (sched.days.has(weekday(day)) && occ <= now) {
+      if (created && occ < created) return null
+      if (!lastSched || occ > lastSched) return occ
+      return null
+    }
+  }
+  return null
+}
+
+// What `list` shows in its NEXT column.
+export function nextRunText(job: DueInput, state: ScheduleState, now: Date): string {
+  if (job.expires && dayStart(now) > parseDate(job.expires).getTime()) return "expired"
+  if (job.when) {
+    const when = parseWhen(job.when)
+    return state.last_scheduled === fmt(when) ? "done" : fmt(when)
+  }
+  const sched = job.schedule ?? parseEvery(job.every!)
+  if (sched.type === "interval") return `every ${sched.minutes} min`
+  for (let ahead = 0; ahead < 8; ahead++) {
+    const day = new Date(now.getFullYear(), now.getMonth(), now.getDate() + ahead)
+    const occ = new Date(day.getFullYear(), day.getMonth(), day.getDate(), sched.hour, sched.minute)
+    if (sched.days.has(weekday(day)) && occ > now) return fmt(occ)
+  }
+  return "?"
+}

package/src/lib/scheduler.test.ts

@@ -0,0 +1,353 @@
+import { describe, expect, test } from "bun:test"
+import { mkdtempSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { dueOccurrence, fmt, nextRunText, parseEvery, parseWhen } from "./schedule.ts"
+import { agentOf, parseJobText, splitArgs, validateJob } from "./schedulerJobs.ts"
+import { quoteArg } from "./cliScheduler.ts"
+import { renderPlist, renderSystemd } from "./schedulerInstall.ts"
+import { runModuleJobs } from "./schedulerTick.ts"
+import { summaryOf } from "./schedulerRun.ts"
+import { tryLock } from "./flock.ts"
+
+const at = (s: string) => parseWhen(s)
+
+describe("parseEvery", () => {
+  test("intervals", () => {
+    expect(parseEvery("30m")).toEqual({ type: "interval", minutes: 30 })
+    expect(parseEvery("6h")).toEqual({ type: "interval", minutes: 360 })
+    expect(() => parseEvery("2m")).toThrow(/5m or longer/)
+  })
+
+  test("calendar forms", () => {
+    const daily = parseEvery("daily 08:00")
+    expect(daily.type === "calendar" && [...daily.days].length).toBe(7)
+    const wk = parseEvery("weekdays 8:30")
+    expect(wk.type === "calendar" && [...wk.days].sort()).toEqual([0, 1, 2, 3, 4])
+    const some = parseEvery("mon,thu 08:00")
+    expect(some.type === "calendar" && [...some.days].sort()).toEqual([0, 3])
+    expect(() => parseEvery("funday 08:00")).toThrow(/unknown day/)
+    expect(() => parseEvery("daily 25:00")).toThrow(/out of range/)
+  })
+})
+
+describe("dueOccurrence", () => {
+  const oneShot = { when: "2026-10-21 08:00", expires: "2026-10-28" }
+
+  test("a one-shot runs once, at or after its time", () => {
+    expect(dueOccurrence(oneShot, {}, at("2026-10-21 07:55"))).toBeNull()
+    expect(fmt(dueOccurrence(oneShot, {}, at("2026-10-21 08:05")))).toBe("2026-10-21 08:00")
+    expect(dueOccurrence(oneShot, { last_scheduled: "2026-10-21 08:00" }, at("2026-10-21 08:10"))).toBeNull()
+  })
+
+  test("nothing runs after expires", () => {
+    expect(dueOccurrence(oneShot, {}, at("2026-10-28 23:55"))).not.toBeNull()
+    expect(dueOccurrence(oneShot, {}, at("2026-10-29 00:00"))).toBeNull()
+  })
+
+  test("retry_after holds a job back", () => {
+    expect(dueOccurrence(oneShot, { retry_after: "2026-10-21 08:30" }, at("2026-10-21 08:10"))).toBeNull()
+    expect(dueOccurrence(oneShot, { retry_after: "2026-10-21 08:30" }, at("2026-10-21 08:30"))).not.toBeNull()
+  })
+
+  test("calendar: missed slots collapse into one catch-up run", () => {
+    // 2026-10-19 is a Monday.
+    const job = { every: "daily 08:00", expires: "2026-12-31", created: "2026-10-01 00:00" }
+    const state = { last_scheduled: "2026-10-17 08:00" }
+    expect(fmt(dueOccurrence(job, state, at("2026-10-20 09:00")))).toBe("2026-10-20 08:00")
+    expect(dueOccurrence(job, { last_scheduled: "2026-10-20 08:00" }, at("2026-10-20 09:00"))).toBeNull()
+  })
+
+  test("calendar: never a slot before created", () => {
+    const job = { every: "daily 08:00", expires: "2026-12-31", created: "2026-10-20 10:00" }
+    expect(dueOccurrence(job, {}, at("2026-10-20 11:00"))).toBeNull()
+    expect(fmt(dueOccurrence(job, {}, at("2026-10-21 08:01")))).toBe("2026-10-21 08:00")
+  })
+
+  test("calendar: weekdays skip the weekend", () => {
+    const job = { every: "weekdays 08:00", expires: "2026-12-31", created: "2026-10-01 00:00" }
+    // Sunday 2026-10-25: the latest weekday slot is Friday's.
+    expect(fmt(dueOccurrence(job, {}, at("2026-10-25 12:00")))).toBe("2026-10-23 08:00")
+    expect(dueOccurrence(job, { last_scheduled: "2026-10-23 08:00" }, at("2026-10-25 12:00"))).toBeNull()
+  })
+
+  test("interval: from the last run, else from created", () => {
+    const job = { every: "30m", expires: "2026-12-31", created: "2026-10-20 10:00" }
+    expect(dueOccurrence(job, {}, at("2026-10-20 10:20"))).toBeNull()
+    expect(fmt(dueOccurrence(job, {}, at("2026-10-20 10:30")))).toBe("2026-10-20 10:30")
+    expect(dueOccurrence(job, { last_run: "2026-10-20 10:30" }, at("2026-10-20 10:55"))).toBeNull()
+  })
+})
+
+describe("nextRunText", () => {
+  test("one-shot, done, expired, calendar", () => {
+    const now = at("2026-10-20 12:00")
+    expect(nextRunText({ when: "2026-10-21 08:00", expires: "2026-10-28" }, {}, now)).toBe("2026-10-21 08:00")
+    expect(nextRunText({ when: "2026-10-20 08:00", expires: "2026-10-28" }, { last_scheduled: "2026-10-20 08:00" }, now)).toBe("done")
+    expect(nextRunText({ when: "2026-10-01 08:00", expires: "2026-10-02" }, {}, now)).toBe("expired")
+    expect(nextRunText({ every: "mon,thu 08:00", expires: "2026-12-31" }, {}, now)).toBe("2026-10-22 08:00")
+  })
+})
+
+const VALID = `---
+id: verify-410s
+kind: spinuptui
+when: 2026-10-21 08:00   # station local time
+expires: 2026-10-28
+created_by: test
+---
+incidents example.com --hours 48
+`
+
+describe("job files", () => {
+  test("parse and validate a good file", () => {
+    const { header, body } = parseJobText(VALID)
+    expect(header.when).toBe("2026-10-21 08:00")
+    expect(body).toBe("incidents example.com --hours 48")
+    expect(validateJob(header, body, "verify-410s.md")).toEqual([])
+  })
+
+  test("problems are listed, not thrown", () => {
+    const { header, body } = parseJobText(VALID.replace("kind: spinuptui", "kind: robot").replace("expires: 2026-10-28\n", ""))
+    const problems = validateJob(header, body, "other.md")
+    expect(problems).toContain("missing expires:")
+    expect(problems.some((p) => p.startsWith("kind must be"))).toBe(true)
+    expect(problems).toContain("file must be named verify-410s.md")
+  })
+
+  test("a spinuptui job can't start a tick", () => {
+    const { header } = parseJobText(VALID)
+    expect(validateJob(header, "scheduler tick --here")[0]).toMatch(/may not start a tick/)
+  })
+
+  test("both when and every, or neither, is invalid", () => {
+    const { header, body } = parseJobText(VALID)
+    expect(validateJob({ ...header, every: "30m" }, body)).toContain("give exactly one of when: or every:")
+  })
+
+  test("kind: codex is agent + codex", () => {
+    expect(agentOf({ kind: "codex" })).toBe("codex")
+    expect(agentOf({ kind: "agent" })).toBe("claude")
+    expect(agentOf({ kind: "agent", agent: "codex" })).toBe("codex")
+    expect(agentOf({ kind: "script" })).toBeNull()
+  })
+
+  test("an unclosed header is an error", () => {
+    expect(() => parseJobText("---\nid: x\n")).toThrow(/not closed/)
+  })
+})
+
+describe("splitArgs / quoteArg", () => {
+  test("shell-like splitting without expansion", () => {
+    expect(splitArgs(`ssh-exec example.com -- 'curl -sI https://example.com/$x'`)).toEqual(["ssh-exec", "example.com", "--", "curl -sI https://example.com/$x"])
+    expect(splitArgs(`a "b \\"c\\"" d\\ e ''`)).toEqual(["a", 'b "c"', "d e", ""])
+    expect(splitArgs("incidents --all\n  --hours 24")).toEqual(["incidents", "--all", "--hours", "24"])
+    expect(() => splitArgs("a 'b")).toThrow(/unclosed/)
+  })
+
+  test("quoteArg round-trips through splitArgs", () => {
+    const argv = ["ssh-exec", "example.com", "--", "grep -c ' 410 ' /var/log/x.log", "it's"]
+    expect(splitArgs(argv.map(quoteArg).join(" "))).toEqual(argv)
+  })
+})
+
+describe("units", () => {
+  const p = { label: "com.spinuptui.scheduler", programArguments: ["/b/bun", "/b/spinuptui", "scheduler", "tick"], env: { PATH: "/b:/usr/bin", X: "a&b" } }
+
+  test("the plist ticks on twelve calendar entries and at load", () => {
+    const xml = renderPlist({ ...p, logPath: "/s/launchd.log" })
+    expect(xml.match(/<key>Minute<\/key>/g)?.length).toBe(12)
+    expect(xml).toContain("<integer>55</integer>")
+    expect(xml).not.toContain("StartInterval</key>")
+    expect(xml).toContain("<key>RunAtLoad</key><true/>")
+    expect(xml).toContain("<string>a&amp;b</string>")
+  })
+
+  test("systemd units", () => {
+    const u = renderSystemd(p)
+    expect(u.service).toContain("ExecStart=/b/bun /b/spinuptui scheduler tick")
+    expect(u.timer).toContain("OnCalendar=*:0/5")
+    expect(u.timer).toContain("Persistent=true")
+  })
+})
+
+describe("module jobs", () => {
+  test("page when a job starts failing and when it recovers, not every run", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "sched-"))
+    const pages: string[] = []
+    const results = [false, false, true, true]
+    const decl = { id: "sentinel.tick", every: "10m", command: ["incidents", "--all"] }
+    let now = at("2026-10-20 10:00")
+    for (const _ of results) {
+      const ok = results.shift()!
+      results.push(ok) // keep the loop length; order is what matters
+      await runModuleJobs([decl], {
+        stateDir: dir,
+        now,
+        run: async () => ({ ok, output: ok ? "{}" : "boom" }),
+        page: async (t) => (pages.push(t), "sent"),
+      })
+      now = new Date(now.getTime() + 10 * 60_000)
+    }
+    expect(pages.length).toBe(2)
+    expect(pages[0]).toMatch(/failed/)
+    expect(pages[1]).toMatch(/working again/)
+  })
+
+  test("not due yet means not run", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "sched-"))
+    let runs = 0
+    const deps = { stateDir: dir, run: async () => (runs++, { ok: true, output: "" }), page: async () => "sent" }
+    const decl = { id: "x.tick", every: "10m", command: ["modules"] }
+    await runModuleJobs([decl], { ...deps, now: at("2026-10-20 10:00") })
+    await runModuleJobs([decl], { ...deps, now: at("2026-10-20 10:05") })
+    await runModuleJobs([decl], { ...deps, now: at("2026-10-20 10:10") })
+    expect(runs).toBe(2)
+  })
+
+  test("a module job may not run scheduler", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "sched-"))
+    const r = await runModuleJobs([{ id: "bad", every: "10m", command: ["scheduler", "tick"] }], {
+      stateDir: dir,
+      now: new Date(),
+      run: async () => ({ ok: true, output: "" }),
+      page: async () => "sent",
+    })
+    expect(r.ran).toEqual([])
+    expect(r.errors[0]).toMatch(/can't run `scheduler`/)
+  })
+})
+
+describe("summaryOf", () => {
+  const job = (kind: string) => ({ name: "x.md", header: { kind }, body: "", problems: [] })
+  test("agent: the SUMMARY paragraph", () => {
+    expect(summaryOf(job("agent"), "noise\nSUMMARY: All good.\nStill summary.\n\n## Details")).toBe("All good.\nStill summary.")
+  })
+  test("spinuptui: a failed JSON result's message", () => {
+    expect(summaryOf(job("spinuptui"), '→ progress\n{"ok":false,"reason":"x","message":"Kuma unreachable"}')).toBe("Kuma unreachable")
+  })
+  test("script: the tail", () => {
+    expect(summaryOf(job("script"), Array.from({ length: 30 }, (_, i) => `l${i}`).join("\n")).split("\n")[0]).toBe("l15")
+  })
+})
+
+describe("flock", () => {
+  test("a held lock can't be taken twice", () => {
+    const path = join(mkdtempSync(join(tmpdir(), "sched-")), "x.lock")
+    const a = tryLock(path)
+    expect(a).not.toBeNull()
+    // Same process, different open file description: flock still excludes it.
+    expect(tryLock(path)).toBeNull()
+    a!.release()
+    const b = tryLock(path)
+    expect(b).not.toBeNull()
+    b!.release()
+  })
+})
+
+// ---- late: ------------------------------------------------------------------------
+
+import { lateGraceMs } from "./schedulerJobs.ts"
+import { isTooLate } from "./schedulerTick.ts"
+
+describe("late:", () => {
+  test("values", () => {
+    expect(lateGraceMs(undefined)).toBeNull()
+    expect(lateGraceMs("run")).toBeNull()
+    expect(lateGraceMs("skip")).toBe(15 * 60_000)
+    expect(lateGraceMs("2h")).toBe(2 * 3_600_000)
+    expect(lateGraceMs("45m")).toBe(45 * 60_000)
+    expect(lateGraceMs("0m")).toBeUndefined()
+    expect(lateGraceMs("later")).toBeUndefined()
+  })
+
+  test("validation names a bad value", () => {
+    const { header, body } = parseJobText(VALID)
+    expect(validateJob({ ...header, late: "sometime" }, body)[0]).toMatch(/late: is run, skip/)
+    expect(validateJob({ ...header, late: "skip" }, body)).toEqual([])
+  })
+
+  test("skip only past the grace window; run never; intervals never", () => {
+    const occ = at("2026-10-21 08:00")
+    expect(isTooLate({ late: "skip" }, occ, at("2026-10-21 08:10"))).toBe(false)
+    expect(isTooLate({ late: "skip" }, occ, at("2026-10-21 08:20"))).toBe(true)
+    expect(isTooLate({ late: "2h" }, occ, at("2026-10-21 09:55"))).toBe(false)
+    expect(isTooLate({ late: "2h" }, occ, at("2026-10-21 10:05"))).toBe(true)
+    expect(isTooLate({}, occ, at("2026-10-22 08:00"))).toBe(false)
+    expect(isTooLate({ late: "skip", every: "30m" }, occ, at("2026-10-21 12:00"))).toBe(false)
+    expect(isTooLate({ late: "skip", every: "daily 08:00" }, occ, at("2026-10-21 12:00"))).toBe(true)
+  })
+})
+
+// ---- the station claim, against real git ------------------------------------------
+
+import { readFileSync as readFile, existsSync as exists, writeFileSync as writeFile } from "node:fs"
+import { spawn } from "./spawn.ts"
+import { decideClaim, removeClaim, writeClaim, readClaim } from "./schedulerGit.ts"
+import type { Source } from "./schedulerJobs.ts"
+
+async function sh(cwd: string, ...cmd: string[]) {
+  const p = spawn(cmd, { cwd, stdout: "pipe", stderr: "pipe" })
+  const out = await new Response(p.stdout).text()
+  if ((await p.exited) !== 0) throw new Error(`${cmd.join(" ")}: ${await new Response(p.stderr).text()}`)
+  return out.trim()
+}
+
+async function twoStations() {
+  for (const [k, v] of Object.entries({ GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@example.com", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@example.com" })) process.env[k] = v
+  const root = mkdtempSync(join(tmpdir(), "claim-"))
+  await sh(root, "git", "init", "-q", "--bare", "-b", "main", "remote.git")
+  await sh(root, "git", "clone", "-q", "remote.git", "a")
+  await sh(join(root, "a"), "git", "commit", "-q", "--allow-empty", "-m", "init")
+  await sh(join(root, "a"), "git", "push", "-q", "-u", "origin", "main")
+  await sh(root, "git", "clone", "-q", "remote.git", "b")
+  const src = (dir: string, queueOnly = false): Source => ({ name: "followups", path: join(root, dir), gitRoot: join(root, dir), git: true, queueOnly })
+  return { root, a: src("a"), b: src("b"), src }
+}
+
+describe("station claim", () => {
+  test("first tick claims; a rival backs off, even when it hadn't pulled the claim yet", async () => {
+    const { a, b } = await twoStations()
+    expect(await decideClaim(a, "mini")).toEqual({ run: true, claimed: true })
+    expect(await decideClaim(a, "mini")).toEqual({ run: true })
+    // b never pulled: its own claim's push is rejected, rolled back, and it
+    // finds mini's claim on the pull.
+    const d = await decideClaim(b, "nas")
+    expect(d.run).toBe(false)
+    expect(d.run === false && d.holder).toBe("mini")
+    expect(readClaim(b)).toBe("mini")
+  })
+
+  test("a failed takeover restores the holder's claim and keeps the user's own work", async () => {
+    const { a, b } = await twoStations()
+    await decideClaim(a, "mini")
+    await sh(b.path, "git", "pull", "-q")
+    // mini moves on, so b is behind when it tries to take over.
+    writeFile(join(a.path, "notes.md"), "x\n")
+    await sh(a.path, "git", "add", "notes.md")
+    await sh(a.path, "git", "commit", "-q", "-m", "notes")
+    await sh(a.path, "git", "push", "-q")
+    writeFile(join(b.path, "mine.txt"), "uncommitted work\n")
+    const r = await writeClaim(b, "nas", "station: nas runs followups")
+    expect(r).toMatch(/push rejected/)
+    expect(readClaim(b)).toBe("mini")
+    expect(readFile(join(b.path, "mine.txt"), "utf8")).toBe("uncommitted work\n")
+    // After the rollback and pull, a deliberate claim succeeds.
+    expect(await writeClaim(b, "nas", "station: nas runs followups")).toBeNull()
+    await sh(a.path, "git", "pull", "-q")
+    const d = await decideClaim(a, "mini")
+    expect(d.run === false && d.holder).toBe("nas")
+  })
+
+  test("release hands the source to the next station; a queue-only machine never claims", async () => {
+    const { a, b, src } = await twoStations()
+    await decideClaim(a, "mini")
+    expect(await removeClaim(a, "station: mini releases followups")).toBeNull()
+    expect(exists(join(a.path, ".scheduler", "station"))).toBe(false)
+    // mini marked itself queue-only on release, so its next tick doesn't re-claim.
+    const again = await decideClaim(src("a", true), "mini")
+    expect(again.run).toBe(false)
+    await sh(b.path, "git", "pull", "-q")
+    expect(await decideClaim(b, "nas")).toEqual({ run: true, claimed: true })
+  })
+})

package/src/lib/schedulerGit.ts

@@ -0,0 +1,119 @@
+// Git plumbing for Scheduler's git sources: pull before a tick, commit and push
+// runs/ after, and the station claim (docs/2026-10-20_scheduler-spec.md, "One
+// station per source").
+//
+// Commits name their paths (`commit -- <paths>`), never the whole index: once
+// ~/SpinupTUI/ is the user's own repository, something they staged by hand must
+// not ride along in a "runs:" commit.
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs"
+import { hostname } from "node:os"
+import { dirname, relative } from "node:path"
+import { spawn } from "./spawn.ts"
+import { jobEnv } from "./schedulerRun.ts"
+import { claimPath, type Source } from "./schedulerJobs.ts"
+
+export async function git(dir: string, ...args: string[]): Promise<{ code: number; out: string }> {
+  const p = spawn(["git", "-C", dir, ...args], { stdin: "ignore", stdout: "pipe", stderr: "pipe", env: jobEnv() })
+  const [out, err] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text()])
+  return { code: await p.exited, out: (out + err).trim() }
+}
+
+export async function gitPull(dir: string): Promise<string | null> {
+  const r = await git(dir, "pull", "--rebase", "--autostash", "--quiet")
+  return r.code === 0 ? null : `git pull failed: ${r.out}`
+}
+
+// Commits `paths` (relative to dir) when they changed, then pushes whenever the
+// branch is ahead, so a push that failed on an earlier tick is retried.
+export async function commitAndPush(dir: string, paths: string[], message: string): Promise<string | null> {
+  await git(dir, "add", "-A", "--", ...paths)
+  if ((await git(dir, "diff", "--cached", "--quiet", "--", ...paths)).code !== 0) {
+    await git(dir, "commit", "--quiet", "-m", message, "--", ...paths)
+  }
+  const ahead = await git(dir, "rev-list", "--count", "@{u}..HEAD")
+  if (ahead.code === 0 && ahead.out !== "" && ahead.out !== "0") {
+    await gitPull(dir)
+    const r = await git(dir, "push", "--quiet")
+    if (r.code !== 0) return `git push failed (retried next tick): ${r.out}`
+  }
+  return null
+}
+
+// ---- the station claim ---------------------------------------------------------------
+
+export function stationName(): string {
+  return hostname().split(".")[0]!.toLowerCase()
+}
+
+export function readClaim(source: Source): string | null {
+  try {
+    return readFileSync(claimPath(source), "utf8").trim() || null
+  } catch {
+    return null
+  }
+}
+
+const claimRel = (s: Source) => relative(s.path, claimPath(s))
+
+export type ClaimDecision =
+  | { run: true; claimed?: boolean } // ours, or just claimed
+  | { run: false; holder: string | null; why: string }
+
+// Called by a dispatcher tick on a git source, after its pull: decides whether
+// this station runs the source, claiming it when nobody does. Two stations
+// claiming at once are settled by git: the push that loses is undone, and the
+// winner's claim arrives with the next pull.
+export async function decideClaim(source: Source, host = stationName()): Promise<ClaimDecision> {
+  const holder = readClaim(source)
+  if (holder === host) return { run: true }
+  if (holder) return { run: false, holder, why: `${source.name} is run by ${holder}; this machine only queues` }
+  if (source.queueOnly) return { run: false, holder: null, why: `${source.name} was released here; this machine only queues` }
+
+  const r = await writeClaim(source, host, `station: ${host} runs ${source.name}`)
+  if (r === null) return { run: true, claimed: true }
+  const now = readClaim(source)
+  if (now && now !== host) return { run: false, holder: now, why: `${source.name} is run by ${now}; this machine only queues` }
+  // Couldn't push and nobody else holds it (offline, say): don't run on an
+  // unpublished claim. The next tick tries again.
+  return { run: false, holder: null, why: `couldn't publish this station's claim on ${source.name} (${r}); will retry` }
+}
+
+// Writes, commits and pushes the claim. On a rejected push, undoes the local
+// commit and pulls, so the caller can read whoever won. null = published.
+export async function writeClaim(source: Source, host: string, message: string): Promise<string | null> {
+  const path = claimPath(source)
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, host + "\n")
+  await git(source.path, "add", "--", claimRel(source))
+  const c = await git(source.path, "commit", "--quiet", "-m", message, "--", claimRel(source))
+  if (c.code !== 0 && !/nothing to commit|no changes added/.test(c.out)) return `git commit failed: ${c.out}`
+  const p = await git(source.path, "push", "--quiet")
+  if (p.code === 0) return null
+  // Undo only what we did: the claim commit, and the claim file back to what
+  // HEAD has (or gone, if HEAD has none). Never `reset --hard`, which would also
+  // discard the user's own uncommitted work in their repository.
+  if (c.code === 0) await git(source.path, "reset", "--quiet", "--soft", "HEAD~1")
+  const restored = await git(source.path, "restore", "--source=HEAD", "--staged", "--worktree", "--", claimRel(source))
+  if (restored.code !== 0) {
+    await git(source.path, "restore", "--staged", "--", claimRel(source))
+    try {
+      unlinkSync(path)
+    } catch {
+      // Already gone.
+    }
+  }
+  await gitPull(source.path)
+  return `git push rejected: ${p.out.split("\n")[0]}`
+}
+
+// Removes this station's claim and publishes the removal. null = done.
+export async function removeClaim(source: Source, message: string): Promise<string | null> {
+  if (!existsSync(claimPath(source))) return null
+  const rm = await git(source.path, "rm", "--quiet", "--", claimRel(source))
+  if (rm.code !== 0) return `git rm failed: ${rm.out}`
+  const c = await git(source.path, "commit", "--quiet", "-m", message, "--", claimRel(source))
+  if (c.code !== 0) return `git commit failed: ${c.out}`
+  const p = await git(source.path, "push", "--quiet")
+  return p.code === 0 ? null : `committed, but the push failed (push it by hand): ${p.out.split("\n")[0]}`
+}