spinuptui 1.2.0 → 1.3.0-alpha.2

package/src/lib/schedulerInstall.ts

@@ -0,0 +1,325 @@
+// Installing Scheduler's dispatcher: the one OS-level scheduled unit SpinupTUI
+// owns. macOS gets a LaunchAgent on twelve StartCalendarInterval entries (every
+// fifth minute; the calendar scheduler, because StartInterval agents have been
+// seen to wedge). Linux gets a systemd user timer, printed by --plan only until
+// a Linux station exists to test on. See docs/2026-10-20_scheduler-spec.md.
+
+import { existsSync, mkdirSync, openSync, readSync, closeSync, realpathSync, unlinkSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import { loadConfig, saveConfig } from "../config.ts"
+import { readLastTick, schedulerStateDir } from "./schedulerJobs.ts"
+import { moduleWorkDir } from "../modules/contract.ts"
+import { spawn } from "./spawn.ts"
+
+export const DEFAULT_LABEL = "com.spinuptui.scheduler"
+const SYSTEM_PATH = ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"]
+const TOOLS = ["git", "ssh", "claude", "codex"]
+
+export function schedulerLabel(): string {
+  return process.env.SPINUPTUI_SCHEDULER_LABEL?.trim() || DEFAULT_LABEL
+}
+
+export interface InstallPlan {
+  platform: "darwin" | "linux"
+  label: string
+  unitPath: string
+  bin: string
+  programArguments: string[]
+  env: Record<string, string>
+  unitText: string
+  extraUnits?: { path: string; text: string }[]
+  commands: string[]
+  notes: string[]
+}
+
+export type PlanResult = ({ ok: true } & InstallPlan) | { ok: false; reason: string; message: string; remedy?: string }
+
+// The checkout a path lives in, if any: a directory with .git above it. A
+// package install (node_modules) never counts.
+function checkoutOf(path: string): string | null {
+  if (path.includes("/node_modules/")) return null
+  let dir = dirname(path)
+  for (;;) {
+    if (existsSync(join(dir, ".git"))) return dir
+    const up = dirname(dir)
+    if (up === dir) return null
+    dir = up
+  }
+}
+
+function shebangOf(path: string): string | null {
+  try {
+    const fd = openSync(path, "r")
+    const buf = Buffer.alloc(128)
+    const n = readSync(fd, buf, 0, 128, 0)
+    closeSync(fd)
+    const head = buf.subarray(0, n).toString("utf8")
+    return head.startsWith("#!") ? head.split("\n")[0]! : null
+  } catch {
+    return null
+  }
+}
+
+const xml = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+
+export function renderPlist(p: { label: string; programArguments: string[]; env: Record<string, string>; logPath: string }): string {
+  const minutes = Array.from({ length: 12 }, (_, i) => `    <dict><key>Minute</key><integer>${i * 5}</integer></dict>`).join("\n")
+  const args = p.programArguments.map((a) => `    <string>${xml(a)}</string>`).join("\n")
+  const env = Object.entries(p.env)
+    .map(([k, v]) => `    <key>${xml(k)}</key><string>${xml(v)}</string>`)
+    .join("\n")
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  SpinupTUI Scheduler's dispatcher: \`spinuptui scheduler tick\` at login and at
+  every fifth minute. Written by \`spinuptui scheduler install --apply\`; remove it
+  with \`spinuptui scheduler uninstall --apply\` rather than by hand.
+-->
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${xml(p.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>StartCalendarInterval</key>
+  <array>
+${minutes}
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>StandardOutPath</key><string>${xml(p.logPath)}</string>
+  <key>StandardErrorPath</key><string>${xml(p.logPath)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${env}
+  </dict>
+</dict>
+</plist>
+`
+}
+
+export function renderSystemd(p: { label: string; programArguments: string[]; env: Record<string, string> }): { service: string; timer: string } {
+  const quote = (a: string) => (/^[\w@%+=:,./-]+$/.test(a) ? a : `"${a.replace(/(["\\])/g, "\\$1")}"`)
+  const env = Object.entries(p.env)
+    .map(([k, v]) => `Environment=${quote(`${k}=${v}`)}`)
+    .join("\n")
+  return {
+    service: `[Unit]\nDescription=SpinupTUI Scheduler tick\n\n[Service]\nType=oneshot\nExecStart=${p.programArguments.map(quote).join(" ")}\n${env}\n`,
+    timer: `[Unit]\nDescription=SpinupTUI Scheduler, every 5 minutes\n\n[Timer]\nOnCalendar=*:0/5\nPersistent=true\n\n[Install]\nWantedBy=timers.target\n`,
+  }
+}
+
+export function planInstall(opts: { bin?: string | null } = {}): PlanResult {
+  const platform = process.platform
+  if (platform !== "darwin" && platform !== "linux") {
+    return { ok: false, reason: "unsupported_platform", message: `Scheduler's dispatcher supports macOS and Linux, not ${platform}.` }
+  }
+  const searchPath = [process.env.PATH ?? "", join(homedir(), ".bun/bin")].join(":")
+  const bin = opts.bin ?? Bun.which("spinuptui", { PATH: searchPath })
+  if (!bin || !existsSync(bin)) {
+    return {
+      ok: false,
+      reason: "spinuptui_not_found",
+      message: opts.bin ? `--bin ${opts.bin} does not exist.` : "No global `spinuptui` on the PATH for the dispatcher to run.",
+      remedy: "Install it globally first: bun add -g spinuptui",
+    }
+  }
+  let real = bin
+  try {
+    real = realpathSync(bin)
+  } catch {
+    // Keep the given path.
+  }
+  const checkout = checkoutOf(real)
+  if (checkout && !opts.bin) {
+    return {
+      ok: false,
+      reason: "checkout_bin",
+      message: `The \`spinuptui\` on the PATH (${bin}) runs a development checkout (${checkout}). The dispatcher must run a release, so an unattended tick never runs whatever is checked out.`,
+      remedy: "Install a release globally (bun add -g spinuptui), or pass --bin <path> to override deliberately.",
+    }
+  }
+  const shebang = shebangOf(real)
+  const bun = /\bbun(\.exe)?$/.test(process.execPath) ? process.execPath : (Bun.which("bun", { PATH: searchPath }) ?? "bun")
+  const programArguments = shebang?.includes("bun") ? [bun, bin, "scheduler", "tick"] : [bin, "scheduler", "tick"]
+
+  const dirs: string[] = [dirname(bun), dirname(bin)]
+  for (const t of TOOLS) {
+    const p = Bun.which(t, { PATH: searchPath })
+    // System directories go last, whichever tool was found there first, so they
+    // never shadow a newer tool in Homebrew or ~/.local/bin.
+    if (p && !SYSTEM_PATH.includes(dirname(p))) dirs.push(dirname(p))
+  }
+  for (const d of SYSTEM_PATH) if (existsSync(d)) dirs.push(d)
+  const env: Record<string, string> = {
+    PATH: [...new Set(dirs)].join(":"),
+    SPINUPTUI_SCHEDULER_DISPATCHER: "1",
+  }
+  if (process.env.XDG_CONFIG_HOME) env.XDG_CONFIG_HOME = process.env.XDG_CONFIG_HOME
+  if (process.env.SPINUPTUI_HOME) env.SPINUPTUI_HOME = process.env.SPINUPTUI_HOME
+  const label = schedulerLabel()
+  // One clock per machine: a dispatcher installed under another label would
+  // tick the same jobs alongside this one.
+  const existing = loadConfig().scheduler?.dispatcher
+  if (existing && existing.label !== label && existsSync(existing.unitPath)) {
+    return {
+      ok: false,
+      reason: "other_dispatcher",
+      message: `A Scheduler dispatcher is already installed as ${existing.label}; installing ${label} too would run every job twice.`,
+      remedy: "Remove it first: spinuptui scheduler uninstall --apply",
+    }
+  }
+  const notes: string[] = [`Jobs and reports live in ${moduleWorkDir("scheduler")} (created on first use).`]
+  if (checkout) notes.push(`--bin points into a checkout (${checkout}); fine for testing, never for a station.`)
+  const missing = TOOLS.filter((t) => !Bun.which(t, { PATH: env.PATH }))
+  if (missing.length) notes.push(`Not found, so jobs that need them will fail: ${missing.join(", ")}.`)
+
+  if (platform === "darwin") {
+    const unitPath = join(homedir(), "Library/LaunchAgents", `${label}.plist`)
+    const domain = `gui/${process.getuid?.() ?? 501}`
+    notes.push("A LaunchAgent runs only while you're logged in: after a reboot, nothing ticks until someone logs in.")
+    return {
+      ok: true,
+      platform,
+      label,
+      unitPath,
+      bin,
+      programArguments,
+      env,
+      unitText: renderPlist({ label, programArguments, env, logPath: join(schedulerStateDir(), "launchd.log") }),
+      commands: [`launchctl bootout ${domain}/${label}  (if loaded)`, `launchctl bootstrap ${domain} ${unitPath}`, "wait for a tick from the dispatcher (up to 60 s)"],
+      notes,
+    }
+  }
+  const unitDir = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "systemd/user")
+  const units = renderSystemd({ label, programArguments, env })
+  notes.push("Linux --apply isn't supported yet; these are the units it will write.", "Run `loginctl enable-linger $USER` so the timer runs with nobody logged in.")
+  return {
+    ok: true,
+    platform,
+    label,
+    unitPath: join(unitDir, `${label}.service`),
+    bin,
+    programArguments,
+    env,
+    unitText: units.service,
+    extraUnits: [{ path: join(unitDir, `${label}.timer`), text: units.timer }],
+    commands: [`systemctl --user daemon-reload`, `systemctl --user enable --now ${label}.timer`],
+    notes,
+  }
+}
+
+// Does the binary the unit will run have Scheduler at all? Asked through
+// --help, a capability check rather than a version comparison: every release
+// answers --help without starting the dashboard, while one without Scheduler
+// treats `scheduler tick` as an unknown subcommand and would launch the TUI
+// under launchd every 5 minutes.
+export async function binHasScheduler(plan: Pick<InstallPlan, "programArguments" | "env">): Promise<boolean> {
+  try {
+    const p = spawn([...plan.programArguments.slice(0, -2), "--help"], {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "ignore",
+      env: { ...process.env, PATH: plan.env.PATH ?? "" },
+    })
+    const timer = setTimeout(() => p.kill(), 30_000)
+    const out = await new Response(p.stdout).text()
+    await p.exited
+    clearTimeout(timer)
+    return out.includes("spinuptui scheduler")
+  } catch {
+    return false
+  }
+}
+
+export const NO_SCHEDULER = {
+  ok: false as const,
+  reason: "spinuptui_too_old",
+  message: "The `spinuptui` the dispatcher would run doesn't have Scheduler yet, so it would open the dashboard every 5 minutes instead of ticking.",
+  remedy: "Install a release that has it first: bun add -g spinuptui@next --no-cache",
+}
+
+async function launchctl(...args: string[]): Promise<{ code: number; out: string }> {
+  const p = spawn(["launchctl", ...args], { stdin: "ignore", stdout: "pipe", stderr: "pipe" })
+  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 type ApplyResult =
+  | { ok: true; label: string; unitPath: string; tickAt: string; notes: string[] }
+  | { ok: false; reason: string; message: string; remedy?: string; unitPath?: string }
+
+export async function applyInstall(plan: InstallPlan, onStage: (s: string) => void = () => {}): Promise<ApplyResult> {
+  if (plan.platform !== "darwin") {
+    return { ok: false, reason: "unsupported_platform", message: "Installing on Linux isn't supported yet; `--plan` shows the units to write by hand." }
+  }
+  onStage("checking that this spinuptui has Scheduler")
+  if (!(await binHasScheduler(plan))) return NO_SCHEDULER
+  const domain = `gui/${process.getuid?.() ?? 501}`
+  mkdirSync(dirname(plan.unitPath), { recursive: true })
+  mkdirSync(schedulerStateDir(), { recursive: true })
+  onStage(`writing ${plan.unitPath}`)
+  writeFileSync(plan.unitPath, plan.unitText, { mode: 0o644 })
+  await launchctl("bootout", `${domain}/${plan.label}`)
+  const since = Date.now()
+  onStage("loading it with launchctl")
+  const boot = await launchctl("bootstrap", domain, plan.unitPath)
+  if (boot.code !== 0) return { ok: false, reason: "launchctl_failed", message: `launchctl bootstrap failed: ${boot.out}`, unitPath: plan.unitPath }
+  await saveConfig({
+    scheduler: { ...(loadConfig().scheduler ?? {}), dispatcher: { label: plan.label, unitPath: plan.unitPath, bin: plan.bin, installedAt: new Date().toISOString() } },
+  })
+
+  // Proof: a tick that ran under launchd itself, not from this shell.
+  onStage("waiting for the dispatcher's first tick")
+  let kicked = false
+  for (let waited = 0; waited < 60_000; waited += 1000) {
+    const last = readLastTick()
+    if (last && last.via === "dispatcher" && Date.parse(last.at) >= since) {
+      return { ok: true, label: plan.label, unitPath: plan.unitPath, tickAt: last.at, notes: plan.notes }
+    }
+    if (!kicked && waited >= 15_000) {
+      kicked = true
+      await launchctl("kickstart", `${domain}/${plan.label}`)
+    }
+    await Bun.sleep(1000)
+  }
+  return {
+    ok: false,
+    reason: "no_tick",
+    message: "The dispatcher is installed, but no tick arrived from it within 60 seconds.",
+    remedy: `Check ${join(schedulerStateDir(), "launchd.log")} and \`launchctl print ${domain}/${plan.label}\`.`,
+    unitPath: plan.unitPath,
+  }
+}
+
+export interface UninstallPlan {
+  label: string
+  unitPath: string
+  installed: boolean
+  commands: string[]
+}
+
+export function planUninstall(): UninstallPlan {
+  const d = loadConfig().scheduler?.dispatcher
+  const label = d?.label ?? schedulerLabel()
+  const unitPath = d?.unitPath ?? join(homedir(), "Library/LaunchAgents", `${label}.plist`)
+  const domain = `gui/${process.getuid?.() ?? 501}`
+  return {
+    label,
+    unitPath,
+    installed: !!d || existsSync(unitPath),
+    commands: [`launchctl bootout ${domain}/${label}`, `delete ${unitPath}`, "clear scheduler.dispatcher in config.json (sources, jobs and reports are kept)"],
+  }
+}
+
+export async function applyUninstall(plan: UninstallPlan): Promise<{ ok: true; removed: string }> {
+  if (process.platform === "darwin") await launchctl("bootout", `gui/${process.getuid?.() ?? 501}/${plan.label}`)
+  if (existsSync(plan.unitPath)) unlinkSync(plan.unitPath)
+  const s = loadConfig().scheduler
+  if (s?.dispatcher) {
+    const { dispatcher: _gone, ...rest } = s
+    await saveConfig({ scheduler: rest })
+  }
+  return { ok: true, removed: plan.unitPath }
+}

package/src/lib/schedulerJobs.ts

@@ -0,0 +1,288 @@
+// Scheduler's user follow-ups: job files, sources and per-job state.
+//
+// A source is a directory holding jobs/ and runs/. The built-in `local` source is
+// Scheduler's own state directory; named sources are directories the user adds
+// (git repositories are pulled and pushed by the tick). The job-file format and
+// the runs/ layout are the git-backed job runner's, unchanged, so a source can
+// move between dispatchers without conversion (docs/2026-10-20_scheduler-spec.md).
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import type { AppConfig } from "../config.ts"
+import { moduleStateDir, moduleWorkDir } from "../modules/contract.ts"
+import { parseDate, parseEvery, parseWhen, type ScheduleState } from "./schedule.ts"
+
+export const KINDS = ["spinuptui", "script", "agent", "codex"] as const
+export type JobKind = (typeof KINDS)[number]
+export const AGENTS = ["claude", "codex"] as const
+export const ID_RE = /^[a-z0-9][a-z0-9-]{1,79}$/
+const REQUIRED = ["id", "kind", "expires", "created_by"] as const
+export const DEFAULT_TIMEOUT_MIN = 30
+
+// ---- sources --------------------------------------------------------------------
+
+export interface Source {
+  name: string
+  path: string
+  // The git repository the source is in (its own .git or a parent's), if any.
+  // `~/SpinupTUI/` made into a repository turns `local` into a git source.
+  gitRoot: string | null
+  git: boolean
+  // This machine queues to it but never claims or runs it (`source release`).
+  queueOnly: boolean
+}
+
+export const LOCAL_SOURCE = "local"
+
+export function schedulerStateDir(): string {
+  return moduleStateDir("scheduler")
+}
+
+export function expandHome(p: string): string {
+  return p === "~" ? homedir() : p.startsWith("~/") ? join(homedir(), p.slice(2)) : p
+}
+
+// The nearest directory at or above `path` holding .git, stopping below the
+// home directory and the filesystem root (a dotfiles repo in ~ shouldn't turn
+// every folder into a git source).
+export function gitRootOf(path: string): string | null {
+  const home = homedir()
+  let dir = path
+  for (;;) {
+    if (existsSync(join(dir, ".git"))) return dir
+    const up = dirname(dir)
+    if (up === dir || up === home || dir === home) return null
+    dir = up
+  }
+}
+
+function makeSource(cfg: AppConfig, name: string, path: string): Source {
+  const gitRoot = gitRootOf(path)
+  return { name, path, gitRoot, git: gitRoot !== null, queueOnly: (cfg.scheduler?.queueOnly ?? []).includes(name) }
+}
+
+export function listSources(cfg: AppConfig): Source[] {
+  const out: Source[] = [makeSource(cfg, LOCAL_SOURCE, moduleWorkDir("scheduler"))]
+  for (const [name, s] of Object.entries(cfg.scheduler?.sources ?? {})) out.push(makeSource(cfg, name, expandHome(s.path)))
+  return out
+}
+
+export function defaultSourceName(cfg: AppConfig): string {
+  const d = cfg.scheduler?.defaultSource
+  return d && cfg.scheduler?.sources?.[d] ? d : LOCAL_SOURCE
+}
+
+export function findSource(cfg: AppConfig, name: string | null | undefined): Source | null {
+  const want = name || defaultSourceName(cfg)
+  return listSources(cfg).find((s) => s.name === want) ?? null
+}
+
+export const jobsDir = (s: Source) => join(s.path, "jobs")
+export const runsDir = (s: Source) => join(s.path, "runs")
+// A named source's lock is the existing job runner's own lock file, so the two
+// serialize during a cutover. The local source's lives with the machine state,
+// keeping ~/SpinupTUI/ to jobs and reports.
+export const sourceLockPath = (s: Source) =>
+  s.name === LOCAL_SOURCE ? join(schedulerStateDir(), "local-source.lock") : join(s.path, ".state", "dispatch.lock")
+// Which station runs this (git) source: one short hostname.
+export const claimPath = (s: Source) => join(s.path, ".scheduler", "station")
+
+// ---- job files ------------------------------------------------------------------
+
+export type JobHeader = Record<string, string>
+
+export interface Job {
+  name: string // file name
+  header: JobHeader
+  body: string
+  problems: string[]
+}
+
+export function parseJobText(text: string): { header: JobHeader; body: string } {
+  const lines = text.split("\n")
+  if (lines[0]?.trim() !== "---") throw new Error("must start with a '---' header line")
+  const header: JobHeader = {}
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i]!
+    if (line.trim() === "---") return { header, body: lines.slice(i + 1).join("\n").trim() }
+    if (!line.trim() || line.trimStart().startsWith("#")) continue
+    const colon = line.indexOf(":")
+    if (colon === -1) throw new Error(`header line without ':': "${line}"`)
+    // Trailing " # comment"s are allowed.
+    header[line.slice(0, colon).trim().toLowerCase()] = line.slice(colon + 1).split(" #")[0]!.trim()
+  }
+  throw new Error("header is not closed with '---'")
+}
+
+export function validateJob(header: JobHeader, body: string, filename?: string): string[] {
+  const problems: string[] = []
+  for (const key of REQUIRED) if (!header[key]) problems.push(`missing ${key}:`)
+  const id = header.id ?? ""
+  if (id && !ID_RE.test(id)) problems.push("id must be lowercase letters, digits and hyphens")
+  if (filename && id && filename !== `${id}.md`) problems.push(`file must be named ${id}.md`)
+  if (header.kind && !(KINDS as readonly string[]).includes(header.kind)) problems.push(`kind must be one of ${KINDS.join(", ")}`)
+  if (header.agent && !(AGENTS as readonly string[]).includes(header.agent)) problems.push(`agent must be one of ${AGENTS.join(", ")}`)
+  if (!!header.when === !!header.every) problems.push("give exactly one of when: or every:")
+  try {
+    if (header.when) parseWhen(header.when)
+    if (header.every) parseEvery(header.every)
+    if (header.expires) parseDate(header.expires)
+    if (header.created) parseWhen(header.created)
+  } catch (err) {
+    problems.push((err as Error).message)
+  }
+  if (header.timeout && !/^\d+$/.test(header.timeout)) problems.push("timeout: is whole minutes")
+  if (header.notify && !["beacon", "telegram", "none"].includes(header.notify)) problems.push("notify: is beacon or none")
+  if (header.late && lateGraceMs(header.late) === undefined) problems.push("late: is run, skip, or a grace window like 30m or 2h")
+  if (!body) problems.push("the body (command, prompt or script) is empty")
+  if (header.kind === "spinuptui" && body) {
+    try {
+      const args = splitArgs(body)
+      if (args[0] === "scheduler") problems.push("a spinuptui job can't run `scheduler` (a job may not start a tick)")
+    } catch (err) {
+      problems.push((err as Error).message)
+    }
+  }
+  return problems
+}
+
+export function loadJobs(source: Source): Job[] {
+  const dir = jobsDir(source)
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".md"))
+    .sort()
+    .map((name) => {
+      try {
+        const { header, body } = parseJobText(readFileSync(join(dir, name), "utf8"))
+        return { name, header, body, problems: validateJob(header, body, name) }
+      } catch (err) {
+        return { name, header: {}, body: "", problems: [(err as Error).message] }
+      }
+    })
+}
+
+export function renderJob(header: [string, string][], body: string): string {
+  return "---\n" + header.map(([k, v]) => `${k}: ${v}\n`).join("") + "---\n" + body.trim() + "\n"
+}
+
+// `late:` as a grace window in ms: null = run whenever reached (the default),
+// undefined = not a valid value.
+export const LATE_SKIP_GRACE_MS = 15 * 60_000
+export function lateGraceMs(value: string | undefined): number | null | undefined {
+  const v = (value ?? "run").trim().toLowerCase()
+  if (v === "run") return null
+  if (v === "skip") return LATE_SKIP_GRACE_MS
+  const m = v.match(/^(\d+)\s*([mh])$/)
+  if (!m || +m[1]! === 0) return undefined
+  return +m[1]! * (m[2] === "h" ? 3_600_000 : 60_000)
+}
+
+// The effective kind and agent: `kind: codex` is the older spelling of
+// `kind: agent` + `agent: codex`.
+export function agentOf(header: JobHeader): "claude" | "codex" | null {
+  if (header.kind === "codex") return "codex"
+  if (header.kind === "agent") return header.agent === "codex" ? "codex" : "claude"
+  return null
+}
+
+// ---- state ----------------------------------------------------------------------
+
+export interface JobState extends ScheduleState {
+  runs?: number
+  last_status?: string
+  last_report?: string
+  auth_alerted_for?: string
+  invalid?: string
+}
+
+export const statePath = (s: Source, id: string) => join(runsDir(s), id, "state.json")
+
+export function loadState(s: Source, id: string): JobState {
+  try {
+    return JSON.parse(readFileSync(statePath(s, id), "utf8")) as JobState
+  } catch {
+    return {}
+  }
+}
+
+// Sorted keys and a trailing newline, as the prior art writes it, so a cutover
+// doesn't produce a noisy diff in the source's history.
+export function saveState(s: Source, id: string, state: JobState): void {
+  mkdirSync(join(runsDir(s), id), { recursive: true })
+  const sorted = Object.fromEntries(Object.entries(state).sort(([a], [b]) => (a < b ? -1 : 1)))
+  const path = statePath(s, id)
+  writeFileSync(`${path}.tmp`, JSON.stringify(sorted, null, 2) + "\n")
+  renameSync(`${path}.tmp`, path)
+}
+
+// ---- the tick record ---------------------------------------------------------------
+
+export interface TickRun {
+  source: string
+  id: string
+  status: "ok" | "failed" | "timeout" | "error" | "auth" | "invalid" | "skipped"
+  report?: string
+  notified?: string
+}
+
+export interface TickRecord {
+  at: string // ISO
+  via: "dispatcher" | "manual"
+  durationMs: number
+  ran: TickRun[]
+  errors: string[]
+  // Git sources another station runs (or released here): expected, not errors.
+  notRunHere?: string[]
+}
+
+export const lastTickPath = () => join(schedulerStateDir(), "last-tick.json")
+export const tickLogPath = () => join(schedulerStateDir(), "tick.log")
+
+export function readLastTick(): TickRecord | null {
+  try {
+    return JSON.parse(readFileSync(lastTickPath(), "utf8")) as TickRecord
+  } catch {
+    return null
+  }
+}
+
+// ---- argument splitting -----------------------------------------------------------
+
+// Split a `spinuptui` job's body into argv the way a shell would — single and
+// double quotes, backslash escapes — without any expansion. Newlines are
+// whitespace, so a long command can wrap.
+export function splitArgs(text: string): string[] {
+  const out: string[] = []
+  let cur = ""
+  let has = false
+  let quote: "'" | '"' | null = null
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!
+    if (quote === "'") {
+      if (c === "'") quote = null
+      else cur += c
+    } else if (quote === '"') {
+      if (c === '"') quote = null
+      else if (c === "\\" && i + 1 < text.length && '"\\$`'.includes(text[i + 1]!)) cur += text[++i]
+      else cur += c
+    } else if (c === "'" || c === '"') {
+      quote = c
+      has = true
+    } else if (c === "\\" && i + 1 < text.length) {
+      cur += text[++i]
+      has = true
+    } else if (/\s/.test(c)) {
+      if (has || cur) out.push(cur)
+      cur = ""
+      has = false
+    } else {
+      cur += c
+      has = true
+    }
+  }
+  if (quote) throw new Error("unclosed quote in the command")
+  if (has || cur) out.push(cur)
+  return out
+}