spinuptui 1.3.0-alpha.1 → 1.3.0-alpha.3

package/src/lib/schedulerRun.ts

@@ -0,0 +1,247 @@
+// Running one Scheduler job: the kinds, the agent adapters, the report and state
+// it leaves behind, and the Beacon message about it.
+//
+// The report/state layout and the agent rules (read-only by default, a fixed
+// always-deny list, a SUMMARY: paragraph as the digest, a lapsed login retried
+// rather than counted as a run) carry over from the git-backed job runner; see
+// docs/2026-10-20_scheduler-spec.md.
+
+import { existsSync, writeFileSync } from "node:fs"
+import { hostname, homedir } from "node:os"
+import { join } from "node:path"
+import { loadConfig } from "../config.ts"
+import { beaconFromConfig, beaconSend } from "./beacon.ts"
+import { spawn } from "./spawn.ts"
+import { prepareWorkDir } from "./home.ts"
+import { fmt } from "./schedule.ts"
+import { agentOf, DEFAULT_TIMEOUT_MIN, expandHome, loadState, runsDir, saveState, splitArgs, type Job, type Source } from "./schedulerJobs.ts"
+
+export const DEFAULT_ALLOW = "Read,Grep,Glob"
+// Never allowed in a claude job, whatever its allow: line says.
+export const ALWAYS_DENY = "Bash(git push *),Bash(git reset *),Bash(git clean *),Bash(rm -rf *),Bash(sudo *)"
+const AUTH_FAIL_RE =
+  /Failed to authenticate|OAuth (session|token)|could not be refreshed|Invalid API key|API key.*(expired|invalid)|Please run .?\/login|not (logged in|authenticated)/i
+const REPORT_CAP = 200_000
+// Tools a launchd PATH doesn't include by default.
+const EXTRA_PATH = [join(homedir(), ".local/bin"), join(homedir(), ".bun/bin"), "/opt/homebrew/bin", "/usr/local/bin"]
+
+export type RunStatus = "ok" | "failed" | "timeout" | "error" | "auth"
+
+function preamble(id: string, kind: string, createdBy: string, runs: string): string {
+  return `You are running unattended on ${hostname().split(".")[0]} as scheduled job \`${id}\` (kind: ${kind}), queued by: ${createdBy}.
+Nobody is watching this run and nobody can answer questions. Do the task below, then stop.
+Rules: report, don't act. Do not modify files outside ${runs}, do not push, deploy, post to clients or email anyone, unless the task explicitly says to.
+Your final message is the report. Start it with a line \`SUMMARY:\` followed by one short paragraph (under 600 characters, plain text) that stands on its own in a chat message. Then give the details in Markdown.
+
+--- TASK ---
+`
+}
+
+// How to start this same SpinupTUI: the Bun running now plus its entry point, or
+// just the executable when it's a compiled binary. Module jobs and `spinuptui`
+// jobs use it, so they always run the dispatcher's own version.
+export function selfCommand(): string[] {
+  const compiled = Bun.main.startsWith("/$bunfs") || !/\bbun(\.exe)?$/.test(process.execPath)
+  return compiled ? [process.execPath] : [process.execPath, Bun.main]
+}
+
+export function jobEnv(): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const [k, v] of Object.entries(process.env)) if (v !== undefined) env[k] = v
+  const parts = (env.PATH || "/usr/bin:/bin:/usr/sbin:/sbin").split(":")
+  env.PATH = [...EXTRA_PATH.filter((p) => !parts.includes(p)), ...parts].join(":")
+  // A job is not a dispatcher: a nested `scheduler tick` must refuse.
+  delete env.SPINUPTUI_SCHEDULER_DISPATCHER
+  return env
+}
+
+export interface ProcResult {
+  code: number | null
+  output: string
+  timedOut: boolean
+}
+
+// Runs a command with stdout and stderr interleaved into one stream, in its own
+// process group so a timeout can stop everything it started.
+export async function runProcess(cmd: string[], opts: { cwd: string; env: Record<string, string>; timeoutMs: number }): Promise<ProcResult> {
+  const proc = spawn(["/bin/sh", "-c", 'exec "$@" 2>&1', "sh", ...cmd], {
+    cwd: opts.cwd,
+    env: opts.env,
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "ignore",
+    detached: true,
+  } as Parameters<typeof spawn>[1])
+  let timedOut = false
+  const kill = (sig: NodeJS.Signals) => {
+    try {
+      process.kill(-proc.pid, sig)
+    } catch {
+      // Already gone.
+    }
+  }
+  const timer = setTimeout(() => {
+    timedOut = true
+    kill("SIGTERM")
+    setTimeout(() => kill("SIGKILL"), 20_000).unref?.()
+  }, opts.timeoutMs)
+  const output = await new Response(proc.stdout as ReadableStream).text()
+  const code = await proc.exited
+  clearTimeout(timer)
+  return { code: timedOut ? null : code, output, timedOut }
+}
+
+export function summaryOf(job: Job, output: string): string {
+  const text = output.trim()
+  if (agentOf(job.header)) {
+    const m = text.match(/SUMMARY:\s*([\s\S]+?)(\n\s*\n|$)/)
+    return (m ? m[1]! : text).trim().slice(0, 900)
+  }
+  if (job.header.kind === "spinuptui") {
+    // A failed JSON result says what went wrong better than its tail does.
+    const last = text.split("\n").reverse().find((l) => l.trim().startsWith("{"))
+    if (last) {
+      try {
+        const r = JSON.parse(last) as { ok?: boolean; message?: string }
+        if (r.ok === false && r.message) return r.message.slice(0, 900)
+      } catch {
+        // Not JSON; fall through to the tail.
+      }
+    }
+  }
+  return text.split("\n").slice(-15).join("\n").slice(-900)
+}
+
+function buildCommand(job: Job, workdir: string, env: Record<string, string>, runs: string): string[] | string {
+  const h = job.header
+  const kind = h.kind!
+  if (kind === "script") return ["/bin/bash", "-c", job.body]
+  if (kind === "spinuptui") return [...selfCommand(), ...splitArgs(job.body)]
+  const agent = agentOf(h)!
+  const prompt = preamble(h.id!, agent === "codex" ? "agent/codex" : "agent/claude", h.created_by!, runs) + job.body
+  const bin = Bun.which(agent, { PATH: env.PATH })
+  if (!bin) return `${agent} not found on PATH`
+  if (agent === "codex") return [bin, "exec", "-s", h.sandbox || "read-only", "-C", workdir, "--skip-git-repo-check", prompt]
+  const cmd = [bin, "-p", prompt, "--output-format", "text", "--permission-mode", "default", "--allowedTools", h.allow || DEFAULT_ALLOW, "--disallowedTools", ALWAYS_DENY]
+  for (const d of (h.add_dirs ?? "").split(",")) if (d.trim()) cmd.push("--add-dir", expandHome(d.trim()))
+  if (h.model) cmd.push("--model", h.model)
+  return cmd
+}
+
+export interface RunOutcome {
+  status: RunStatus
+  report?: string // source-relative
+  notified?: "sent" | "skipped" | string // string = why it failed
+}
+
+const pad2 = (n: number) => String(n).padStart(2, "0")
+const stamp = (d: Date) => fmt(d).replace(" ", "-").replace(":", "")
+const duration = (s: number) => `${Math.floor(s / 60)}m ${pad2(s % 60)}s`
+
+export async function runJob(source: Source, job: Job, occurrence: Date, now = new Date()): Promise<RunOutcome> {
+  const h = job.header
+  const id = h.id!
+  const env = jobEnv()
+  const workdir = expandHome(h.workdir || source.path)
+  const timeoutMs = Number(h.timeout || DEFAULT_TIMEOUT_MIN) * 60_000
+  const runs = join(runsDir(source), id)
+  prepareWorkDir(runs)
+  const reportRel = `runs/${id}/${stamp(now)}.md`
+
+  const started = new Date()
+  let status: RunStatus
+  let code: number | null = null
+  let output: string
+  const cmd = existsSync(workdir) ? buildCommand(job, workdir, env, runs) : `workdir does not exist on this machine: ${workdir}`
+  if (typeof cmd === "string") {
+    status = "error"
+    output = cmd
+  } else {
+    try {
+      const r = await runProcess(cmd, { cwd: workdir, env, timeoutMs })
+      code = r.code
+      output = r.output
+      status = r.timedOut ? "timeout" : r.code === 0 ? "ok" : "failed"
+      if (r.timedOut) output += `\n\n[scheduler] killed after ${timeoutMs / 60_000} minutes`
+    } catch (err) {
+      status = "error"
+      output = `could not start: ${(err as Error).message}`
+    }
+  }
+  if (agentOf(h) && status !== "ok" && AUTH_FAIL_RE.test(output)) status = "auth"
+  return finish(source, job, occurrence, started, new Date(), status, code, output, reportRel)
+}
+
+async function finish(
+  source: Source,
+  job: Job,
+  occurrence: Date,
+  started: Date,
+  finished: Date,
+  status: RunStatus,
+  code: number | null,
+  output: string,
+  reportRel: string,
+): Promise<RunOutcome> {
+  const h = job.header
+  const id = h.id!
+  const seconds = Math.round((finished.getTime() - started.getTime()) / 1000)
+  const state = loadState(source, id)
+
+  if (status === "auth") {
+    // The agent isn't logged in, so nothing ran: no report. Retry in 30 minutes,
+    // and page only once per scheduled slot.
+    const agent = agentOf(h)!
+    state.last_status = status
+    state.retry_after = fmt(new Date(Date.now() + 30 * 60_000))
+    const first = state.auth_alerted_for !== fmt(occurrence)
+    state.auth_alerted_for = fmt(occurrence)
+    saveState(source, id, state)
+    if (!first) return { status, notified: "skipped" }
+    const how = agent === "claude" ? "claude, then /login" : "codex login"
+    const notified = await notify(
+      `⚠️ Job ${id} did not run: the ${agent} login on ${hostname().split(".")[0]} has lapsed. Log in there (run \`${how}\`); it retries every 30 min until ${h.expires}.`,
+      h.to,
+    )
+    return { status, notified }
+  }
+
+  if (output.length > REPORT_CAP) output = output.slice(0, REPORT_CAP) + `\n\n[scheduler] output truncated at ${REPORT_CAP} characters`
+  const kindLabel = agentOf(h) ? `agent (${agentOf(h)})` : h.kind!
+  writeFileSync(
+    join(source.path, reportRel),
+    `# ${id} — ${status}\n\n` +
+      `- Scheduled: ${fmt(occurrence)}\n- Started: ${fmt(started)}:${pad2(started.getSeconds())}\n- Duration: ${duration(seconds)}\n` +
+      `- Exit code: ${code ?? "None"}\n- Kind: ${kindLabel}\n- Job file: jobs/${id}.md\n- Queued by: ${h.created_by}\n\n---\n\n` +
+      output.trimEnd() +
+      "\n",
+  )
+  state.last_status = status
+  state.last_report = reportRel
+  delete state.retry_after
+  delete state.auth_alerted_for
+  state.runs = (state.runs ?? 0) + 1
+  state.last_run = fmt(started)
+  state.last_scheduled = fmt(occurrence)
+  saveState(source, id, state)
+
+  let notified: RunOutcome["notified"] = "skipped"
+  if ((h.notify || "beacon") !== "none") {
+    const icon = { ok: "✅", failed: "❌", timeout: "⏱️", error: "❌" }[status as Exclude<RunStatus, "auth">] ?? "•"
+    notified = await notify(
+      `${icon} Job ${id} (${status}, ${duration(seconds)})\n\n${summaryOf(job, output) || "(no output)"}\n\nReport: ${source.name}/${reportRel}\nQueued by: ${h.created_by}`,
+      h.to,
+    )
+  }
+  return { status, report: reportRel, notified }
+}
+
+// In-process Beacon send. Never throws; returns "sent" or why it wasn't.
+export async function notify(text: string, to?: string): Promise<string> {
+  try {
+    const r = await beaconSend(beaconFromConfig(loadConfig()), text, { to: to || null, silent: false })
+    return r.ok ? "sent" : `${r.reason}: ${r.message}`
+  } catch (err) {
+    return `error: ${(err as Error).message}`
+  }
+}

package/src/lib/schedulerTick.ts

@@ -0,0 +1,322 @@
+// One Scheduler tick: what the dispatcher runs every 5 minutes.
+//
+//   1. Take the tick lock (a tick still running from last time wins).
+//   2. Run due module jobs (ScheduledJobDecl), paging only when one starts or
+//      stops failing.
+//   3. For each source: take its lock, pull it if it's a git repository, run
+//      each due follow-up in turn, commit and push runs/.
+//   4. Record the tick in last-tick.json (every dispatcher tick; status() reads
+//      it) and in tick.log (any tick where something ran or failed).
+//
+// See docs/2026-10-20_scheduler-spec.md.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { loadConfig } from "../config.ts"
+import { MODULES } from "../modules/index.ts"
+import type { ScheduledJobDecl } from "../modules/contract.ts"
+import { tryLock } from "./flock.ts"
+import { declSchedule, dueOccurrence, fmt, parseEvery, parseWhen } from "./schedule.ts"
+import {
+  ID_RE,
+  lastTickPath,
+  lateGraceMs,
+  listSources,
+  loadJobs,
+  LOCAL_SOURCE,
+  loadState,
+  saveState,
+  schedulerStateDir,
+  sourceLockPath,
+  tickLogPath,
+  type JobHeader,
+  type Source,
+  type TickRecord,
+  type TickRun,
+} from "./schedulerJobs.ts"
+import { jobEnv, notify, runJob, runProcess, selfCommand } from "./schedulerRun.ts"
+import { commitAndPush, decideClaim, gitPull, readClaim, stationName } from "./schedulerGit.ts"
+import { pagerProblem, sendHeartbeat, tickHeartbeat } from "./heartbeat.ts"
+
+const LOG_MAX_BYTES = 1_000_000
+const MODULE_JOB_TIMEOUT_MS = 10 * 60_000
+
+export type TickResult = ({ ok: true } & TickRecord) | { ok: true; skipped: "locked"; message: string }
+
+// ---- module jobs -----------------------------------------------------------------
+
+export interface ModuleJobState {
+  last_run?: string
+  last_scheduled?: string
+  last_status?: "ok" | "failed"
+  failing_since?: string
+  last_output?: string
+}
+
+export interface ModuleJobDeps {
+  stateDir: string
+  now: Date
+  run(decl: ScheduledJobDecl): Promise<{ ok: boolean; output: string }>
+  page(text: string): Promise<string>
+}
+
+function moduleJobStatePath(dir: string, id: string) {
+  return join(dir, "module-jobs", `${id}.json`)
+}
+
+// Runs whichever declarations are due. Pages when a job starts failing and when
+// it recovers — never on every failed run, so a broken heartbeat can't train
+// anyone to ignore the pager.
+export async function runModuleJobs(decls: ScheduledJobDecl[], deps: ModuleJobDeps): Promise<{ ran: TickRun[]; errors: string[] }> {
+  const ran: TickRun[] = []
+  const errors: string[] = []
+  for (const decl of decls) {
+    const path = moduleJobStatePath(deps.stateDir, decl.id)
+    let state: ModuleJobState = {}
+    try {
+      state = JSON.parse(readFileSync(path, "utf8")) as ModuleJobState
+    } catch {
+      // First run.
+    }
+    let occ: Date | null
+    try {
+      if (decl.command[0] === "scheduler") throw new Error("a module job can't run `scheduler`")
+      occ = dueOccurrence({ schedule: declSchedule(decl) }, state, deps.now)
+    } catch (err) {
+      errors.push(`module job ${decl.id}: ${(err as Error).message}`)
+      continue
+    }
+    if (!occ) continue
+    // The tick's time, not the wall clock after earlier jobs: intervals stay
+    // aligned to ticks instead of drifting by each run's duration.
+    const started = deps.now
+    const r = await deps.run(decl)
+    const status = r.ok ? "ok" : "failed"
+    const tail = r.output.trim().split("\n").slice(-10).join("\n").slice(-600)
+    let notified: string | undefined
+    if (status === "failed" && state.last_status !== "failed") {
+      notified = await deps.page(`⚠️ ${decl.id} failed (spinuptui ${decl.command.join(" ")})\n\n${tail || "(no output)"}`)
+      state.failing_since = fmt(started)
+    } else if (status === "ok" && state.last_status === "failed") {
+      notified = await deps.page(`✅ ${decl.id} is working again (failing since ${state.failing_since ?? "?"})`)
+      delete state.failing_since
+    }
+    state.last_status = status
+    state.last_run = fmt(started)
+    state.last_scheduled = fmt(occ)
+    state.last_output = tail
+    mkdirSync(join(deps.stateDir, "module-jobs"), { recursive: true })
+    writeFileSync(path, JSON.stringify(state, null, 2) + "\n")
+    ran.push({ source: "module", id: decl.id, status, ...(notified ? { notified } : {}) })
+  }
+  return { ran, errors }
+}
+
+async function configuredModuleJobs(): Promise<ScheduledJobDecl[]> {
+  const out: ScheduledJobDecl[] = []
+  for (const m of MODULES) {
+    if (m.jobs.length === 0) continue
+    const s = await m.status().catch(() => null)
+    if (s && s.state !== "not_configured") out.push(...m.jobs)
+  }
+  return out
+}
+
+// ---- sources ---------------------------------------------------------------------
+
+// `late:`: is this slot too old to run? Only fixed-time slots can be late; an
+// interval job's slot is always "now".
+export function isTooLate(header: JobHeader, occ: Date, now: Date): boolean {
+  const grace = lateGraceMs(header.late)
+  if (grace === null || grace === undefined) return false
+  if (header.every && parseEvery(header.every).type === "interval") return false
+  return now.getTime() - occ.getTime() > grace
+}
+
+const hm = (d: Date) => fmt(d).slice(11)
+
+async function tickSource(
+  source: Source,
+  now: Date,
+  only: string | null,
+  force: boolean,
+  via: "dispatcher" | "manual",
+): Promise<{ ran: TickRun[]; errors: string[]; notRunHere?: string }> {
+  const ran: TickRun[] = []
+  const errors: string[] = []
+  if (!existsSync(source.path)) {
+    // ~/SpinupTUI/scheduler appears on first use, so a missing local folder
+    // just means nothing has been queued there yet.
+    if (source.name === LOCAL_SOURCE) return { ran, errors }
+    return { ran, errors: [`source ${source.name}: ${source.path} does not exist`] }
+  }
+  const lock = tryLock(sourceLockPath(source))
+  if (!lock) return { ran, errors: [`source ${source.name}: busy (another dispatcher holds its lock); skipped this tick`] }
+  try {
+    if (source.git) {
+      const e = await gitPull(source.path)
+      if (e) errors.push(`source ${source.name}: ${e}`)
+      // One station per git source. Only the dispatcher claims; a manual `run`
+      // on a machine that doesn't hold the claim is deliberate, so it proceeds.
+      if (via === "dispatcher") {
+        const d = await decideClaim(source)
+        if (!d.run) {
+          if (d.holder === null && d.why.startsWith("couldn't")) errors.push(`source ${d.why}`)
+          return { ran, errors, notRunHere: d.why }
+        }
+      } else {
+        const holder = readClaim(source)
+        if (holder && holder !== stationName()) process.stderr.write(`Warning: ${source.name} is run by ${holder}; running it here anyway, because you asked.\n`)
+      }
+    }
+    for (const job of loadJobs(source)) {
+      const id = job.header.id
+      if (only && id !== only) continue
+      if (job.problems.length) {
+        if (!id || !ID_RE.test(id)) continue
+        const sig = job.problems.join("; ")
+        const state = loadState(source, id)
+        if (state.invalid !== sig) {
+          state.invalid = sig
+          saveState(source, id, state)
+          const notified = await notify(`⚠️ Job file ${source.name}/jobs/${job.name} is invalid and was skipped: ${sig}`)
+          ran.push({ source: source.name, id, status: "invalid", notified })
+        }
+        continue
+      }
+      const state = loadState(source, id!)
+      if (state.invalid !== undefined) {
+        delete state.invalid
+        saveState(source, id!, state)
+      }
+      let occ: Date | null
+      try {
+        occ = force ? forcedOccurrence(job.header.when, now) : dueOccurrence(job.header, state, now)
+      } catch (err) {
+        errors.push(`job ${source.name}/${id}: ${(err as Error).message}`)
+        continue
+      }
+      if (!occ) continue
+      if (!force && isTooLate(job.header, occ, now)) {
+        state.last_scheduled = fmt(occ)
+        state.last_status = "skipped"
+        delete state.retry_after
+        saveState(source, id!, state)
+        const notified =
+          (job.header.notify || "beacon") === "none"
+            ? "skipped"
+            : await notify(
+                `⏭ Skipped job ${id}: it was due at ${fmt(occ)}, and this station only got to it at ${hm(now)}. Its late: ${job.header.late} policy says not to run it late.\n\nQueued by: ${job.header.created_by}`,
+                job.header.to,
+              )
+        ran.push({ source: source.name, id: id!, status: "skipped", notified })
+        continue
+      }
+      process.stderr.write(`→ running ${source.name}/${id} (scheduled ${fmt(occ)})\n`)
+      const outcome = await runJob(source, job, occ, now)
+      ran.push({ source: source.name, id: id!, ...outcome })
+    }
+    if (source.git) {
+      const mine = ran.filter((r) => r.source === source.name)
+      const e = await commitAndPush(source.path, ["runs"], "runs: " + (mine.length ? mine.map((r) => `${r.id} (${r.status})`).join(", ") : "state"))
+      if (e) errors.push(`source ${source.name}: ${e}`)
+    }
+  } finally {
+    lock.release()
+  }
+  return { ran, errors }
+}
+
+// `scheduler run`: a one-shot whose time has passed is recorded as its own slot,
+// so the next tick doesn't run it again; anything else runs as "now".
+function forcedOccurrence(when: string | undefined, now: Date): Date {
+  if (when) {
+    const w = parseWhen(when)
+    if (w <= now) return w
+  }
+  return new Date(new Date(now).setSeconds(0, 0))
+}
+
+// ---- tick ------------------------------------------------------------------------
+
+export interface TickOptions {
+  via: "dispatcher" | "manual"
+  // `scheduler run <id>`: one job, now, whether due or not.
+  only?: { source: string; id: string }
+  now?: Date
+}
+
+export async function tick(opts: TickOptions): Promise<TickResult> {
+  const dir = schedulerStateDir()
+  mkdirSync(dir, { recursive: true })
+  const lock = tryLock(join(dir, "tick.lock"))
+  if (!lock) return { ok: true, skipped: "locked", message: "A previous tick is still running." }
+  const startedAt = Date.now()
+  const now = opts.now ?? new Date()
+  const ran: TickRun[] = []
+  const errors: string[] = []
+  const notRunHere: string[] = []
+  try {
+    if (!opts.only) {
+      const decls = await configuredModuleJobs()
+      if (decls.length) {
+        const r = await runModuleJobs(decls, {
+          stateDir: dir,
+          now,
+          run: async (decl) => {
+            const p = await runProcess([...selfCommand(), ...decl.command], { cwd: dir, env: jobEnv(), timeoutMs: MODULE_JOB_TIMEOUT_MS })
+            return { ok: p.code === 0, output: p.output }
+          },
+          page: (text) => notify(text),
+        })
+        ran.push(...r.ran)
+        errors.push(...r.errors)
+      }
+    }
+    for (const source of listSources(loadConfig())) {
+      if (opts.only && source.name !== opts.only.source) continue
+      const r = await tickSource(source, now, opts.only?.id ?? null, !!opts.only, opts.via)
+      ran.push(...r.ran)
+      errors.push(...r.errors)
+      if (r.notRunHere) notRunHere.push(r.notRunHere)
+    }
+    for (const r of ran) if (r.notified && r.notified !== "sent" && r.notified !== "skipped") errors.push(`${r.source}/${r.id}: not paged (${r.notified})`)
+    const record: TickRecord = {
+      at: new Date().toISOString(),
+      via: opts.via,
+      durationMs: Date.now() - startedAt,
+      ran,
+      errors,
+      ...(notRunHere.length ? { notRunHere } : {}),
+    }
+    // Only the dispatcher's ticks count as "the station is alive": a manual
+    // `run` or `tick --here` must not mask a dispatcher that has stopped. The
+    // same goes for the heartbeat, which tells Kuma the clock is running.
+    if (opts.via === "dispatcher") {
+      const hb = loadConfig().scheduler?.heartbeat
+      if (hb) {
+        const t = tickHeartbeat(ran.length, errors, pagerProblem())
+        const r = await sendHeartbeat(hb.url, t.status, t.msg, record.durationMs)
+        record.heartbeat = { ok: r.ok, status: r.status, ...(r.error ? { error: r.error } : {}) }
+        if (!r.ok) record.errors.push(`heartbeat: Kuma didn't take the ping (${r.error})`)
+      }
+      writeFileSync(`${lastTickPath()}.tmp`, JSON.stringify(record, null, 2) + "\n")
+      renameSync(`${lastTickPath()}.tmp`, lastTickPath())
+    }
+    if (ran.length || errors.length) appendTickLog(record)
+    return { ok: true, ...record }
+  } finally {
+    lock.release()
+  }
+}
+
+function appendTickLog(record: TickRecord): void {
+  try {
+    const path = tickLogPath()
+    const size = existsSync(path) ? statSync(path).size : 0
+    if (size > LOG_MAX_BYTES) renameSync(path, `${path}.1`)
+    appendFileSync(path, JSON.stringify(record) + "\n")
+  } catch {
+    // The log is history; losing a line must not fail the tick.
+  }
+}

package/src/lib/spinupweb.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test"
+import { parseAccountSlug, siteWebUrl } from "./spinupweb.ts"
+
+describe("parseAccountSlug", () => {
+  test("a bare slug", () => {
+    expect(parseAccountSlug("  acme-agency ")).toBe("acme-agency")
+  })
+  test("a whole dashboard URL", () => {
+    expect(parseAccountSlug("https://spinupwp.app/acme-agency/sites/123#git")).toBe("acme-agency")
+    expect(parseAccountSlug("spinupwp.app/acme-agency")).toBe("acme-agency")
+    expect(parseAccountSlug("https://SpinupWP.app/acme-agency/?tab=servers")).toBe("acme-agency")
+  })
+  test("anything that isn't a slug", () => {
+    expect(parseAccountSlug("")).toBeNull()
+    expect(parseAccountSlug("https://spinupwp.app/")).toBeNull()
+    expect(parseAccountSlug("acme agency")).toBeNull()
+    expect(parseAccountSlug("../etc")).toBeNull()
+  })
+  test("feeds the deep link", () => {
+    expect(siteWebUrl(42, parseAccountSlug("https://spinupwp.app/acme-agency/sites"))).toBe("https://spinupwp.app/acme-agency/sites/42")
+  })
+})

package/src/lib/spinupweb.ts

@@ -12,6 +12,17 @@
 
 const WEB_BASE = "https://spinupwp.app"
 
+// Read an account slug from what a user types: the slug itself, or any dashboard
+// URL pasted whole ("https://spinupwp.app/acme-agency/sites/123" → "acme-agency").
+// Null when it doesn't look like a slug.
+export function parseAccountSlug(input: string): string | null {
+  let s = input.trim()
+  const at = s.toLowerCase().indexOf("spinupwp.app/")
+  if (at >= 0) s = s.slice(at + "spinupwp.app/".length)
+  s = s.replace(/^\/+/, "").split(/[/?#]/)[0] ?? ""
+  return /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(s) ? s : null
+}
+
 export function serverWebUrl(id: number, accountSlug: string | null): string {
   return accountSlug ? `${WEB_BASE}/${accountSlug}/servers/${id}` : WEB_BASE
 }

package/src/lib/stackCache.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test"
+import { isRecheckDue, isVersionOld, VERSION_MAX_AGE_MS, type CachedProbe } from "./stackCache.ts"
+
+const NOW = 1_800_000_000_000
+
+function entry(version: string | null, ageMs: number): CachedProbe {
+  return {
+    result: { kind: version ? "wordpress" : "whmcs", app: "x", version, label: "x" },
+    detectedAt: NOW - ageMs,
+    signature: "true:",
+  }
+}
+
+describe("isVersionOld", () => {
+  test("a fresh version reading isn't old", () => {
+    expect(isVersionOld(entry("7.1.3", 60_000), NOW)).toBe(false)
+  })
+  test("a version reading past the max age is old", () => {
+    expect(isVersionOld(entry("7.0", VERSION_MAX_AGE_MS + 1), NOW)).toBe(true)
+  })
+  test("an identity without a version never goes old", () => {
+    expect(isVersionOld(entry(null, 365 * VERSION_MAX_AGE_MS), NOW)).toBe(false)
+  })
+  test("no entry isn't old", () => {
+    expect(isVersionOld(undefined, NOW)).toBe(false)
+  })
+})
+
+describe("isRecheckDue", () => {
+  const old = entry("7.0", 3 * VERSION_MAX_AGE_MS)
+  test("an old version with no attempt yet is due", () => {
+    expect(isRecheckDue(old, NOW)).toBe(true)
+  })
+  test("an attempt inside the window (even a failed one) holds it off", () => {
+    expect(isRecheckDue({ ...old, recheckedAt: NOW - 60_000 }, NOW)).toBe(false)
+  })
+  test("an attempt from a previous window doesn't", () => {
+    expect(isRecheckDue({ ...old, recheckedAt: NOW - VERSION_MAX_AGE_MS - 1 }, NOW)).toBe(true)
+  })
+  test("a fresh reading is never due", () => {
+    expect(isRecheckDue(entry("7.1.3", 60_000), NOW)).toBe(false)
+  })
+})