spinuptui 1.3.0-alpha.4 → 1.3.0-alpha.5

package/src/lib/scheduler.test.ts

@@ -7,7 +7,8 @@ import { agentOf, parseJobText, splitArgs, validateJob } from "./schedulerJobs.t
 import { quoteArg } from "./cliScheduler.ts"
 import { renderPlist, renderSystemd } from "./schedulerInstall.ts"
 import { runModuleJobs } from "./schedulerTick.ts"
-import { summaryOf } from "./schedulerRun.ts"
+import { agentCommand, BLOCKED_EXIT, outcomeOf, summaryOf } from "./schedulerRun.ts"
+import { stillRunningHeartbeat } from "./heartbeat.ts"
 import { tryLock } from "./flock.ts"
 
 const at = (s: string) => parseWhen(s)
@@ -452,3 +453,89 @@ describe("/jobs", () => {
     delete process.env.SPINUPTUI_HOME
   })
 })
+
+describe("blocked", () => {
+  test("an agent that exits 0 saying it's blocked did no work", () => {
+    expect(outcomeOf(true, 0, false, "SUMMARY: login lapsed.\nSTATUS: blocked\nNeeds a re-login.")).toBe("blocked")
+    expect(outcomeOf(true, 0, false, "SUMMARY: all fine.\n\nThe status: blocked queue is empty.")).toBe("ok")
+  })
+
+  test("a script says so with its exit code", () => {
+    expect(outcomeOf(false, BLOCKED_EXIT, false, "")).toBe("blocked")
+    expect(outcomeOf(false, 1, false, "")).toBe("failed")
+    expect(outcomeOf(false, 0, false, "STATUS: blocked")).toBe("ok")
+  })
+
+  test("a lapsed login and a timeout keep their own statuses", () => {
+    expect(outcomeOf(true, 1, false, "Please run /login")).toBe("auth")
+    expect(outcomeOf(true, null, true, "working")).toBe("timeout")
+    expect(outcomeOf(true, 1, false, "boom")).toBe("failed")
+  })
+
+  test("a blocked one-shot isn't done", () => {
+    const job = { when: "2026-10-20 08:00", expires: "2026-10-30" }
+    const now = at("2026-10-21 08:00")
+    expect(nextRunText(job, { last_scheduled: "2026-10-20 08:00", last_status: "blocked" }, now)).toBe("blocked")
+    expect(nextRunText(job, { last_scheduled: "2026-10-20 08:00", last_status: "ok" }, now)).toBe("done")
+    // It waits for the operator: a blocked run doesn't retry by itself.
+    expect(dueOccurrence(job, { last_scheduled: "2026-10-20 08:00", last_status: "blocked" }, now)).toBeNull()
+  })
+
+  test("a module job pages once when blocked, and again when it recovers", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "blocked-"))
+    const pages: string[] = []
+    const step = (result: { ok: boolean; output: string; blocked?: boolean }, minute: string) =>
+      runModuleJobs([{ id: "t", every: "5m", command: ["x"] }], { stateDir: dir, now: at(`2026-10-20 10:${minute}`), run: async () => result, page: async (t) => (pages.push(t), "sent") })
+    await step({ ok: false, output: "login", blocked: true }, "00")
+    await step({ ok: false, output: "login", blocked: true }, "05")
+    await step({ ok: true, output: "" }, "10")
+    expect(pages.length).toBe(2)
+    expect(pages[0]).toContain("blocked")
+    expect(pages[1]).toContain("working again")
+  })
+})
+
+describe("the agent adapter", () => {
+  test("carries the always-deny list and options, for any caller", () => {
+    const cmd = agentCommand({ agent: "claude", prompt: "p", workdir: "/w", allow: "Read", addDirs: "/a,/b", model: "m" }, { PATH: `/bin:${process.env.PATH}` })
+    if (typeof cmd === "string") return // no claude here; the string is the reason
+    expect(cmd).toContain("--disallowedTools")
+    expect(cmd.filter((a) => a === "--add-dir").length).toBe(2)
+  })
+
+  test("says why when the binary is missing", () => {
+    expect(agentCommand({ agent: "codex", prompt: "p", workdir: "/w" }, { PATH: "/nonexistent" })).toBe("codex not found on PATH")
+  })
+})
+
+describe("a dispatcher tick that finds the lock held", () => {
+  test("tells Kuma the station is alive, unless it can't page", () => {
+    expect(stillRunningHeartbeat(null)).toEqual({ status: "up", msg: "tick still running" })
+    expect(stillRunningHeartbeat("Beacon's last page failed").status).toBe("down")
+  })
+
+  test("pings and records itself; a manual one doesn't", async () => {
+    process.env.XDG_CONFIG_HOME = mkdtempSync(join(tmpdir(), "stilltick-"))
+    const { schedulerStateDir, readLastTick } = await import("./schedulerJobs.ts")
+    const { saveConfig } = await import("../config.ts")
+    const { tick } = await import("./schedulerTick.ts")
+    const pings: string[] = []
+    const server = Bun.serve({ port: 0, fetch: (r) => (pings.push(r.url), Response.json({ ok: true })) })
+    try {
+      await saveConfig({
+        scheduler: { heartbeat: { url: `http://localhost:${server.port}/api/push/x`, setAt: "now" } },
+        beacon: { channels: { pager: { type: "telegram", botToken: "1:a", chatId: "2" } } },
+      })
+      const lock = tryLock(join(schedulerStateDir(), "tick.lock"))!
+      expect(await tick({ via: "manual" })).toMatchObject({ skipped: "locked" })
+      expect(pings.length).toBe(0)
+      expect(await tick({ via: "dispatcher" })).toMatchObject({ skipped: "locked" })
+      lock.release()
+      expect(pings.length).toBe(1)
+      expect(pings[0]).toContain("still")
+      expect(readLastTick()).toMatchObject({ stillRunning: true, via: "dispatcher", heartbeat: { ok: true } })
+    } finally {
+      server.stop(true)
+    }
+  })
+})

package/src/lib/schedulerJobs.ts

@@ -191,7 +191,6 @@ export function agentOf(header: JobHeader): "claude" | "codex" | null {
 
 export interface JobState extends ScheduleState {
   runs?: number
-  last_status?: string
   last_report?: string
   auth_alerted_for?: string
   invalid?: string
@@ -222,7 +221,7 @@ export function saveState(s: Source, id: string, state: JobState): void {
 export interface TickRun {
   source: string
   id: string
-  status: "ok" | "failed" | "timeout" | "error" | "auth" | "invalid" | "skipped"
+  status: "ok" | "failed" | "blocked" | "timeout" | "error" | "auth" | "invalid" | "skipped"
   report?: string
   notified?: string
 }
@@ -235,6 +234,9 @@ export interface TickRecord {
   errors: string[]
   // Git sources another station runs (or released here): expected, not errors.
   notRunHere?: string[]
+  // This dispatcher tick found the previous one still running, so it did nothing
+  // but say the station is alive.
+  stillRunning?: boolean
   // The station heartbeat's ping at the end of this tick, when one is set.
   heartbeat?: { ok: boolean; status: "up" | "down"; error?: string }
 }

package/src/lib/schedulerRun.ts

@@ -6,11 +6,13 @@
 // 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 { 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 { pageMarkup } from "./beaconListenInstall.ts"
+import type { BeaconButton } from "../modules/contract.ts"
 import { spawn } from "./spawn.ts"
 import { prepareWorkDir } from "./home.ts"
 import { fmt } from "./schedule.ts"
@@ -19,19 +21,24 @@ import { agentOf, DEFAULT_TIMEOUT_MIN, expandHome, loadState, runsDir, saveState
 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 =
+// A script (or a `spinuptui` job) that exits with this ran but couldn't do its
+// work because of something outside it: EX_TEMPFAIL. An agent says so in text.
+export const BLOCKED_EXIT = 75
+export const BLOCKED_RE = /^\s*STATUS:\s*blocked\b/im
+export 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"
+export type RunStatus = "ok" | "failed" | "blocked" | "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.
+If you couldn't do the work because of something outside this job that a person has to fix (a lapsed login, a missing permission, a service refusing you), put a line \`STATUS: blocked\` straight after the summary and say what's needed. Don't use it for a finding, however bad.
 
 --- TASK ---
 `
@@ -55,6 +62,15 @@ export function jobEnv(): Record<string, string> {
   return env
 }
 
+// Starts a process that outlives this one: its own session (launchd reaps a
+// job's process group, not this), and no inherited pipes, since whoever reads
+// this process's stdout would otherwise wait for the child to finish too.
+export function spawnDetached(cmd: string[], opts: { cwd: string; env: Record<string, string> }): void {
+  mkdirSync(opts.cwd, { recursive: true })
+  const proc = spawn(cmd, { cwd: opts.cwd, env: opts.env, stdin: "ignore", stdout: "ignore", stderr: "ignore", detached: true } as Parameters<typeof spawn>[1])
+  proc.unref()
+}
+
 export interface ProcResult {
   code: number | null
   output: string
@@ -112,6 +128,28 @@ export function summaryOf(job: Job, output: string): string {
   return text.split("\n").slice(-15).join("\n").slice(-900)
 }
 
+export interface AgentRun {
+  agent: "claude" | "codex"
+  prompt: string
+  workdir: string
+  allow?: string
+  addDirs?: string
+  model?: string
+  sandbox?: string
+}
+
+// The adapters: a binary name and how to build its argv. Scheduler's agent jobs
+// and Sentinel's worker share them. Returns why it can't run, as a string.
+export function agentCommand(run: AgentRun, env: Record<string, string>): string[] | string {
+  const bin = Bun.which(run.agent, { PATH: env.PATH })
+  if (!bin) return `${run.agent} not found on PATH`
+  if (run.agent === "codex") return [bin, "exec", "-s", run.sandbox || "read-only", "-C", run.workdir, "--skip-git-repo-check", run.prompt]
+  const cmd = [bin, "-p", run.prompt, "--output-format", "text", "--permission-mode", "default", "--allowedTools", run.allow || DEFAULT_ALLOW, "--disallowedTools", ALWAYS_DENY]
+  for (const d of (run.addDirs ?? "").split(",")) if (d.trim()) cmd.push("--add-dir", expandHome(d.trim()))
+  if (run.model) cmd.push("--model", run.model)
+  return cmd
+}
+
 function buildCommand(job: Job, workdir: string, env: Record<string, string>, runs: string): string[] | string {
   const h = job.header
   const kind = h.kind!
@@ -119,13 +157,16 @@ function buildCommand(job: Job, workdir: string, env: Record<string, string>, ru
   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
+  return agentCommand({ agent, prompt, workdir, allow: h.allow, addDirs: h.add_dirs, model: h.model, sandbox: h.sandbox }, env)
+}
+
+// What a finished process means. An agent that exits 0 after saying it's blocked
+// did no work, whatever its exit code says.
+export function outcomeOf(agent: boolean, code: number | null, timedOut: boolean, output: string): RunStatus {
+  if (agent && code !== 0 && AUTH_FAIL_RE.test(output)) return "auth"
+  if (timedOut) return "timeout"
+  if (code === 0) return agent && BLOCKED_RE.test(output) ? "blocked" : "ok"
+  return !agent && code === BLOCKED_EXIT ? "blocked" : "failed"
 }
 
 export interface RunOutcome {
@@ -161,14 +202,13 @@ export async function runJob(source: Source, job: Job, occurrence: Date, now = n
       const r = await runProcess(cmd, { cwd: workdir, env, timeoutMs })
       code = r.code
       output = r.output
-      status = r.timedOut ? "timeout" : r.code === 0 ? "ok" : "failed"
+      status = outcomeOf(!!agentOf(h), r.code, r.timedOut, r.output)
       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)
 }
 
@@ -227,19 +267,25 @@ async function finish(
 
   let notified: RunOutcome["notified"] = "skipped"
   if ((h.notify || "beacon") !== "none") {
-    const icon = { ok: "✅", failed: "❌", timeout: "⏱️", error: "❌" }[status as Exclude<RunStatus, "auth">] ?? "•"
+    const icon = { ok: "✅", failed: "❌", blocked: "🚧", 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,
+      status === "ok" ? undefined : [[runAgainButton(source.name, id)]],
     )
   }
   return { status, report: reportRel, notified }
 }
 
+// A tap re-runs the job exactly as written: it can't add permissions.
+export function runAgainButton(source: string, id: string): BeaconButton {
+  return { text: `Run ${id} again`, action: "scheduler.run", payload: { source, id } }
+}
+
 // In-process Beacon send. Never throws; returns "sent" or why it wasn't.
-export async function notify(text: string, to?: string): Promise<string> {
+export async function notify(text: string, to?: string, buttons?: BeaconButton[][], silent = false): Promise<string> {
   try {
-    const r = await beaconSend(beaconFromConfig(loadConfig()), text, { to: to || null, silent: false })
+    const r = await beaconSend(beaconFromConfig(loadConfig()), text, { to: to || null, silent, ...(buttons ? { replyMarkup: pageMarkup(buttons) } : {}) })
     return r.ok ? "sent" : `${r.reason}: ${r.message}`
   } catch (err) {
     return `error: ${(err as Error).message}`

package/src/lib/schedulerTick.ts

@@ -34,9 +34,9 @@ import {
   type TickRecord,
   type TickRun,
 } from "./schedulerJobs.ts"
-import { jobEnv, notify, runJob, runProcess, selfCommand } from "./schedulerRun.ts"
+import { BLOCKED_EXIT, jobEnv, notify, runJob, runProcess, selfCommand } from "./schedulerRun.ts"
 import { commitAndPush, decideClaim, gitPull, readClaim, stationName } from "./schedulerGit.ts"
-import { pagerProblem, sendHeartbeat, tickHeartbeat } from "./heartbeat.ts"
+import { pagerProblem, sendHeartbeat, stillRunningHeartbeat, tickHeartbeat } from "./heartbeat.ts"
 
 const LOG_MAX_BYTES = 1_000_000
 const MODULE_JOB_TIMEOUT_MS = 10 * 60_000
@@ -48,7 +48,7 @@ export type TickResult = ({ ok: true } & TickRecord) | { ok: true; skipped: "loc
 export interface ModuleJobState {
   last_run?: string
   last_scheduled?: string
-  last_status?: "ok" | "failed"
+  last_status?: "ok" | "failed" | "blocked"
   failing_since?: string
   last_output?: string
 }
@@ -56,7 +56,7 @@ export interface ModuleJobState {
 export interface ModuleJobDeps {
   stateDir: string
   now: Date
-  run(decl: ScheduledJobDecl): Promise<{ ok: boolean; output: string }>
+  run(decl: ScheduledJobDecl): Promise<{ ok: boolean; output: string; blocked?: boolean }>
   page(text: string): Promise<string>
 }
 
@@ -91,13 +91,14 @@ export async function runModuleJobs(decls: ScheduledJobDecl[], deps: ModuleJobDe
     // 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 status = r.ok ? "ok" : r.blocked ? "blocked" : "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") {
+    const wasOk = !state.last_status || state.last_status === "ok"
+    if (status !== "ok" && status !== state.last_status) {
+      notified = await deps.page(`${status === "blocked" ? "🚧" : "⚠️"} ${decl.id} ${status} (spinuptui ${decl.command.join(" ")})\n\n${tail || "(no output)"}`)
+      if (wasOk) state.failing_since = fmt(started)
+    } else if (status === "ok" && !wasOk) {
       notified = await deps.page(`✅ ${decl.id} is working again (failing since ${state.failing_since ?? "?"})`)
       delete state.failing_since
     }
@@ -250,7 +251,12 @@ 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." }
+  if (!lock) {
+    // The heartbeat can't wait for a long job to finish: Kuma would call a busy
+    // station dead. The holder is alive, so this tick says so.
+    if (opts.via === "dispatcher") await recordStillRunning()
+    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[] = []
@@ -265,7 +271,7 @@ export async function tick(opts: TickOptions): Promise<TickResult> {
           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 }
+            return { ok: p.code === 0, output: p.output, blocked: p.code === BLOCKED_EXIT }
           },
           page: (text) => notify(text),
         })
@@ -300,8 +306,7 @@ export async function tick(opts: TickOptions): Promise<TickResult> {
         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())
+      writeLastTick(record)
     }
     if (ran.length || errors.length) appendTickLog(record)
     return { ok: true, ...record }
@@ -310,6 +315,23 @@ export async function tick(opts: TickOptions): Promise<TickResult> {
   }
 }
 
+function writeLastTick(record: TickRecord): void {
+  writeFileSync(`${lastTickPath()}.tmp`, JSON.stringify(record, null, 2) + "\n")
+  renameSync(`${lastTickPath()}.tmp`, lastTickPath())
+}
+
+async function recordStillRunning(): Promise<void> {
+  const record: TickRecord = { at: new Date().toISOString(), via: "dispatcher", durationMs: 0, ran: [], errors: [], stillRunning: true }
+  const hb = loadConfig().scheduler?.heartbeat
+  if (hb) {
+    const t = stillRunningHeartbeat(pagerProblem())
+    const r = await sendHeartbeat(hb.url, t.status, t.msg, 0)
+    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})`)
+  }
+  writeLastTick(record)
+}
+
 function appendTickLog(record: TickRecord): void {
   try {
     const path = tickLogPath()

package/src/lib/sentinelAttach.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test"
+import { applyAttach, planAttach } from "./sentinelAttach.ts"
+import type { KumaMonitor } from "./uptimeKuma.ts"
+
+const m = (id: number, name: string, over: Partial<KumaMonitor> = {}): KumaMonitor => ({ id, name, type: "http", ...over })
+const sites = ["a.example.com", "b.example.com", "c.example.com"]
+
+describe("planAttach", () => {
+  test("matches by the naming convention", () => {
+    const p = planAttach([m(1, "a.example.com"), m(2, "a.example.com load", { type: "push" }), m(3, "a.example.com php-fatal"), m(4, "a.example.com front page"), m(5, "a.example.com cache-bypass"), m(6, "a.example.com redis")], sites, {})
+    expect(p.exact.map((x) => x.field).sort()).toEqual(["bypassId", "fatalId", "fingerprintId", "healthId", "pushId", "redisId"])
+    expect(p.unmonitored).toEqual(["b.example.com", "c.example.com"])
+  })
+
+  test("a site with extra domains counts once", () => {
+    const p = planAttach([], ["a.example.com", "www.a.example.com"], {}, ["a.example.com"])
+    expect(p.unmonitored).toEqual(["a.example.com"])
+  })
+
+  test("a hand-made monitor on a fleet host is only likely", () => {
+    const p = planAttach([m(1, "Client homepage", { url: "https://www.b.example.com/" })], sites, {})
+    expect(p.exact).toEqual([])
+    expect(p.likely).toMatchObject([{ domain: "b.example.com", field: "healthId", monitorId: 1 }])
+  })
+
+  test("ignores strangers, and what's already attached", () => {
+    const p = planAttach([m(1, "a.example.com"), m(9, "My router", { url: "https://192.0.2.1" })], sites, { "a.example.com": { healthId: 1 } })
+    expect(p.already).toBe(1)
+    expect(p.exact).toEqual([])
+    expect(p.strangers).toEqual(["My router"])
+  })
+})
+
+describe("applyAttach", () => {
+  test("keeps the token Kuma already holds, and never overwrites", () => {
+    const monitors = [m(2, "a.example.com load", { type: "push", pushToken: "live-token" }), m(1, "a.example.com")]
+    const r = applyAttach({ "a.example.com": { healthId: 7 } }, [{ domain: "a.example.com", field: "pushId", monitorId: 2, name: "" }, { domain: "a.example.com", field: "healthId", monitorId: 1, name: "" }], monitors)
+    expect(r["a.example.com"]).toEqual({ healthId: 7, pushId: 2, pushToken: "live-token" })
+  })
+
+  test("rebuilds a fingerprint's keyword", () => {
+    const r = applyAttach({}, [{ domain: "a.example.com", field: "fingerprintId", monitorId: 4, name: "" }], [m(4, "x", { keyword: "home", interval: 600 })])
+    expect(r["a.example.com"]?.fingerprint).toMatchObject({ keyword: "home", kind: "attached", interval: 600 })
+  })
+})

package/src/lib/sentinelAttach.ts

@@ -0,0 +1,98 @@
+// `sentinel attach`: adopts an existing Kuma's monitors, because a fresh install
+// connected to a Kuma full of them still sees none (`incidents` reads the local
+// registry). The registry is rebuilt from what Kuma already knows.
+//
+// Read-only toward Kuma and the servers: it never creates, renames or edits a
+// monitor, and never generates a push token, because the server crons are already
+// pushing to the existing ones. Re-running only fills gaps.
+
+import type { KumaMonitorRef } from "../config.ts"
+import type { KumaMonitor } from "./uptimeKuma.ts"
+
+// SpinupTUI's own naming convention, longest suffix first.
+const SUFFIXES: [string, keyof KumaMonitorRef, (keyof KumaMonitorRef)?][] = [
+  [" php-fatal", "fatalId", "fatalToken"],
+  [" cache-bypass", "bypassId"],
+  [" front page", "fingerprintId"],
+  [" redis", "redisId", "redisToken"],
+  [" load", "pushId", "pushToken"],
+]
+
+export interface AttachMatch {
+  domain: string
+  field: keyof KumaMonitorRef
+  monitorId: number
+  name: string
+}
+
+export interface AttachPlan {
+  exact: AttachMatch[]
+  likely: AttachMatch[]
+  unmonitored: string[]
+  strangers: string[]
+  already: number
+}
+
+function nameMatch(m: KumaMonitor): { domain: string; field: keyof KumaMonitorRef; token?: keyof KumaMonitorRef } {
+  for (const [suffix, field, token] of SUFFIXES) if (m.name.endsWith(suffix)) return { domain: m.name.slice(0, -suffix.length), field, token }
+  return { domain: m.name, field: "healthId" }
+}
+
+function urlHost(url: string | undefined): string | null {
+  try {
+    return url ? new URL(url).hostname.toLowerCase() : null
+  } catch {
+    return null
+  }
+}
+
+// `domains` is every name a monitor might use; `primary` is one per site, so a
+// site with extra domains counts once when listing what has no monitor.
+export function planAttach(monitors: KumaMonitor[], domains: string[], registry: Record<string, KumaMonitorRef>, primary: string[] = domains): AttachPlan {
+  const sites = new Set(domains)
+  const has = (domain: string, field: keyof KumaMonitorRef) => typeof registry[domain]?.[field] === "number"
+  const taken = new Set(Object.values(registry).flatMap((r) => Object.entries(r).filter(([k, v]) => k.endsWith("Id") && typeof v === "number").map(([, v]) => v as number)))
+  const plan: AttachPlan = { exact: [], likely: [], unmonitored: [], strangers: [], already: 0 }
+  const covered = new Set(Object.keys(registry).filter((d) => registry[d]?.healthId))
+  const leftover: KumaMonitor[] = []
+  for (const m of monitors) {
+    if (taken.has(m.id)) {
+      plan.already++
+      continue
+    }
+    const { domain, field } = nameMatch(m)
+    if (sites.has(domain) && !has(domain, field)) {
+      plan.exact.push({ domain, field, monitorId: m.id, name: m.name })
+      if (field === "healthId") covered.add(domain)
+    } else leftover.push(m)
+  }
+  for (const m of leftover) {
+    const host = urlHost(m.url)
+    const domain = host && (sites.has(host) ? host : sites.has(host.replace(/^www\./, "")) ? host.replace(/^www\./, "") : null)
+    if (domain && m.type === "http" && !covered.has(domain)) {
+      plan.likely.push({ domain, field: "healthId", monitorId: m.id, name: m.name })
+      covered.add(domain)
+    } else plan.strangers.push(m.name)
+  }
+  plan.unmonitored = primary.filter((d) => !covered.has(d) && !registry[d]).sort()
+  return plan
+}
+
+// The registry after attaching: existing entries are never overwritten, and each
+// push monitor keeps the token Kuma already holds.
+export function applyAttach(registry: Record<string, KumaMonitorRef>, matches: AttachMatch[], monitors: KumaMonitor[]): Record<string, KumaMonitorRef> {
+  const byId = new Map(monitors.map((m) => [m.id, m]))
+  const out: Record<string, KumaMonitorRef> = structuredClone(registry)
+  for (const a of matches) {
+    const ref = (out[a.domain] ??= {}) as Record<string, unknown>
+    if (typeof ref[a.field] === "number") continue
+    ref[a.field] = a.monitorId
+    const m = byId.get(a.monitorId)
+    const token = SUFFIXES.find(([, field]) => field === a.field)?.[2]
+    if (token && m?.pushToken) ref[token] = m.pushToken
+    if (a.field === "fingerprintId" && typeof m?.keyword === "string") {
+      ref.fingerprint = { keyword: m.keyword, kind: "attached", detail: "", interval: Number(m.interval) || 300, derivedAt: new Date().toISOString() }
+    }
+  }
+  return out
+}

package/src/lib/sentinelDigest.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test"
+import { aptTargets, composeDigest, type DigestData } from "./sentinelDigest.ts"
+import type { ExpectResult } from "./sentinelExpect.ts"
+import type { Flags, Incident } from "./sentinelState.ts"
+
+const when = new Date("2026-10-30T12:00:00")
+const flag = (id: string, text = "LOW"): ExpectResult => ({ id, label: id, state: "flag", text })
+const data = (over: Partial<DigestData> = {}): DigestData => ({ when, health: [{ name: "Station", ok: true, detail: "ticking" }], ticks: [], incidents: [], results: [], aptTotal: 0, apt: [], notes: [], ...over })
+
+describe("the header reacts to what's new", () => {
+  test("all clear is green and silent", () => {
+    const d = composeDigest(data(), {})
+    expect(d.text.startsWith("✅ Fleet OK")).toBe(true)
+    expect(d.silent).toBe(true)
+  })
+
+  test("a new flag makes a sound, and records the day", () => {
+    const d = composeDigest(data({ results: [flag("a")] }), {})
+    expect(d.text.startsWith("⚠️ 1 new")).toBe(true)
+    expect(d.silent).toBe(false)
+    expect(d.text).toContain("New:")
+    expect(d.flags.a!.firstSeen).toBe("2026-10-30")
+  })
+
+  test("yesterday's flag is ongoing, with its age, and stays quiet", () => {
+    const flags: Flags = { a: { firstSeen: "2026-10-18", text: "a: LOW" } }
+    const d = composeDigest(data({ results: [flag("a")] }), flags)
+    expect(d.text.startsWith("✅ Fleet OK")).toBe(true)
+    expect(d.silent).toBe(true)
+    expect(d.text).toContain("Ongoing:")
+    expect(d.text).toContain("(12 days)")
+  })
+
+  test("an acknowledged flag becomes a count, and is never hidden", () => {
+    const d = composeDigest(data({ results: [flag("a")] }), { a: { firstSeen: "2026-10-18", text: "x", acked: true } })
+    expect(d.text).toContain("1 acknowledged flag still set")
+    expect(d.text).not.toContain("Ongoing:")
+  })
+
+  test("a flag that clears starts over if it comes back", () => {
+    const d = composeDigest(data({ results: [{ id: "a", label: "a", state: "ok", text: "fine" }] }), { a: { firstSeen: "2026-10-18", text: "x" } })
+    expect(d.flags).toEqual({})
+  })
+
+  test("a check that couldn't run keeps its flag's age", () => {
+    const d = composeDigest(data({ results: [{ id: "a", label: "a", state: "unverified", text: "no count" }] }), { a: { firstSeen: "2026-10-18", text: "x" } })
+    expect(d.flags.a!.firstSeen).toBe("2026-10-18")
+  })
+
+  test("a failing health check makes a sound", () => {
+    const d = composeDigest(data({ health: [{ name: "Agent", ok: false, detail: "login lapsed" }] }), {})
+    expect(d.text.startsWith("⚠️ Needs attention")).toBe(true)
+    expect(d.silent).toBe(false)
+    expect(d.text).toContain("Agent: ⚠️ login lapsed")
+  })
+})
+
+test("a stuck incident is named", () => {
+  const i: Incident = { id: "old", key: "k", server: null, state: "waiting_agent", createdAt: new Date(when.getTime() - 2 * 86_400_000).toISOString(), events: [{ domain: "a.example.com", kind: "health", time: "t", message: "", monitorId: 1 }], down: [], lastDownAt: "", attempts: 0 }
+  const d = composeDigest(data({ incidents: [i] }), {})
+  expect(d.silent).toBe(false)
+  expect(d.text).toContain("old: waiting_agent")
+})
+
+test("activity counts, and recurrences by site", () => {
+  const base: Incident = { id: "x", key: "k", server: null, state: "reported", createdAt: when.toISOString(), events: [{ domain: "a.example.com", kind: "health", time: "t", message: "", monitorId: 1 }], down: [], lastDownAt: "", attempts: 1 }
+  const d = composeDigest(data({ incidents: [base, { ...base, id: "y", state: "recurrence" }, { ...base, id: "z", state: "recurrence" }], ticks: [{ at: "", ok: true, events: 0, incidents: 0, retries: 1 }, { at: "", ok: false, events: 0, incidents: 0, retries: 2 }] }), {})
+  expect(d.text).toContain("2 checks · 1 incident · 1 report · 2 recurrences · 1 blind · 1 cold start")
+  expect(d.text).toContain("a.example.com ×2")
+})
+
+test("server updates collapse to a count, naming only the exceptions", () => {
+  const apt: ExpectResult[] = [{ id: "apt-a", label: "a", state: "ok", text: "" }, { id: "apt-b", label: "b", state: "unverified", text: "" }, flag("apt-c", "STALE")]
+  const d = composeDigest(data({ apt, aptTotal: 3 }), {})
+  expect(d.text).toContain("Server updates: 1 of 3 normal, unverified: b")
+  expect(d.text).toContain("apt-c: STALE")
+})
+
+test("the update check tries one site per server, the one that worked last", () => {
+  const fleet = { domains: { "a.example.com": { server: "w1", site: "a.example.com" }, "b.example.com": { server: "w1", site: "b.example.com" }, "www.b.example.com": { server: "w1", site: "b.example.com" }, "w2.example.com": { server: "w2", site: "w2.example.com", vanity: true }, "c.example.com": { server: "w2", site: "c.example.com" } } }
+  expect(aptTargets(fleet, { w1: "b.example.com" }, new Set(["c.example.com"]))).toEqual([{ server: "w1", domain: "b.example.com" }, { server: "w2", domain: "c.example.com" }])
+})