spinuptui 1.2.0 → 1.3.0-alpha.2

package/src/lib/schedulerRun.ts

@@ -0,0 +1,246 @@
+// 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, mkdirSync, 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 { 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)
+  mkdirSync(runs, { recursive: true })
+  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,307 @@
+// 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,
+  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"
+
+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)) 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.
+    if (opts.via === "dispatcher") {
+      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/modules/beacon.ts

@@ -0,0 +1,52 @@
+// Beacon's module declaration: the first implementation of the contract.
+
+import { loadConfig } from "../config.ts"
+import { beaconFromConfig, lastSendLogEntry, maskChatId, maskToken } from "../lib/beacon.ts"
+import { moduleStateDir, moduleWorkDir, type ModuleCheck, type ModuleDefinition, type ModuleStatus } from "./contract.ts"
+
+export const beaconModule: ModuleDefinition = {
+  id: "beacon",
+  name: "Beacon",
+  summary: "Tells you when something needs you: one pager for the fleet and every module.",
+  dependsOn: [],
+  configKey: "beacon",
+  stateDir: () => moduleStateDir("beacon"),
+  workDir: () => moduleWorkDir("beacon"),
+  jobs: [],
+  async status(): Promise<ModuleStatus> {
+    const beacon = beaconFromConfig(loadConfig())
+    if (beacon.channels.length === 0) {
+      return {
+        id: "beacon",
+        state: "not_configured",
+        summary: "No channels configured",
+        checks: [],
+        remedy: "spinuptui beacon add telegram <name> --env-file <path>",
+      }
+    }
+    const checks: ModuleCheck[] = beacon.channels.map((c) => ({
+      name: `channel ${c.name}`,
+      ok: true,
+      detail: `telegram bot ${maskToken(c.channel.botToken)} → chat ${maskChatId(c.channel.chatId)}${c.env ? " (from environment)" : ""}${c.name === beacon.defaultChannel ? ", default" : ""}`,
+    }))
+    checks.push({
+      name: "default channel",
+      ok: beacon.defaultChannel !== null,
+      detail: beacon.defaultChannel ?? "none — senders must pass --to",
+    })
+    const last = lastSendLogEntry()
+    checks.push({
+      name: "last send",
+      ok: last?.ok ?? true,
+      detail: last ? `${last.ok ? "delivered" : `failed (${last.error})`} via ${last.channel} at ${last.at}` : "nothing sent yet",
+    })
+    const failing = checks.find((c) => !c.ok)
+    return {
+      id: "beacon",
+      state: failing ? "degraded" : "ok",
+      summary: failing ? `${failing.name}: ${failing.detail}` : `${beacon.channels.length} channel${beacon.channels.length === 1 ? "" : "s"}, default ${beacon.defaultChannel}`,
+      checks,
+      ...(failing ? { remedy: "spinuptui beacon test" } : {}),
+    }
+  },
+}

package/src/modules/contract.ts

@@ -0,0 +1,82 @@
+// The module contract (docs/2026-10-16_beacon-and-module-contract-spec.md).
+//
+// A module is a feature that keeps working after the TUI is closed. Each one
+// describes itself with a ModuleDefinition so `spinuptui modules`, the future
+// Modules screen and `station setup` are views over the same data rather than
+// knowing every module by hand.
+//
+// Rules the shape encodes:
+// - Config is a machine-level top-level key in config.json named after the
+//   module, written only by deliberate setup commands.
+// - Anything a module writes while running goes in its state directory, never
+//   config.json (whose writes are neither atomic nor locked).
+// - The user's work (jobs, reports, write-ups — anything a person reads, keeps
+//   or shares) goes in its work directory, ~/SpinupTUI/<id>/, not next to the
+//   tokens in the hidden config directory.
+// - Recurring work is declared in `jobs` for Scheduler to run; a module never
+//   installs an OS scheduler unit of its own.
+// - status() is computed on demand, is cheap, and never sends anything.
+
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { configDir, loadConfig } from "../config.ts"
+
+export type ModuleId = "beacon" | "scheduler" | "sentinel" | "samurai"
+
+export interface ScheduledJobDecl {
+  id: string // e.g. "sentinel.tick"
+  every?: string // e.g. "5m"
+  at?: string // e.g. "08:00"
+  // A spinuptui subcommand's arguments, never a path into a checkout.
+  command: string[]
+}
+
+export interface ModuleCheck {
+  name: string
+  ok: boolean
+  detail: string
+}
+
+export interface ModuleStatus {
+  id: ModuleId
+  state: "not_configured" | "ok" | "degraded"
+  summary: string
+  checks: ModuleCheck[]
+  remedy?: string
+}
+
+export interface ModuleDefinition {
+  id: ModuleId
+  name: string
+  // Outcome copy, shared with the landing page's module card.
+  summary: string
+  dependsOn: ModuleId[]
+  configKey: string
+  // Machine state: locks, logs, high-water marks.
+  stateDir(): string
+  // The user's work. Created on first use, never at install.
+  workDir(): string
+  jobs: ScheduledJobDecl[]
+  status(): Promise<ModuleStatus>
+}
+
+export function moduleStateDir(id: ModuleId): string {
+  return join(configDir(), "modules", id)
+}
+
+const expandHome = (p: string) => (p === "~" ? homedir() : p.startsWith("~/") ? join(homedir(), p.slice(2)) : p)
+
+// ~/SpinupTUI by default: visible and easy to back up or turn into a git
+// repository. Deliberately not ~/Documents, which iCloud may sync (a second
+// syncer writing inside a .git corrupts it).
+export function spinuptuiHome(): string {
+  const p = process.env.SPINUPTUI_HOME?.trim() || loadConfig().homeDir || join(homedir(), "SpinupTUI")
+  return expandHome(p)
+}
+
+export function moduleWorkDir(id: ModuleId): string {
+  return join(spinuptuiHome(), id)
+}
+
+// A module that hasn't shipped yet: just enough to draw its card.
+export type UpcomingModule = Pick<ModuleDefinition, "id" | "name" | "summary" | "dependsOn">