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

package/CHANGELOG.md

@@ -11,6 +11,24 @@ version; such changes are called out here.
 
 ## [Unreleased]
 
+## [1.3.0-alpha.5] - 2026-10-30
+
+A pre-release, published on npm's `next` tag (`bun add -g spinuptui@next --no-cache`). `@latest` and Homebrew are on 1.2.1.
+
+### Added
+- **Sentinel: know why, not just that it's down.** The third module checks Uptime Kuma every 5 minutes, groups what went down by server, pages you, and writes it up: the evidence on its own, or a full diagnosis if you bring an agent CLI. The agent reads servers only through `ssh-exec` and can't post anything; Sentinel saves its report and does the posting. A repeat within 6 hours skips the diagnosis and offers **Diagnose anyway**. A lapsed agent login delays work instead of losing it. Set it up from the Modules tab, or `spinuptui sentinel setup`. See [docs/sentinel.md](docs/sentinel.md).
+- **A morning digest that only speaks up about what's new.** Sentinel's 08:00 message covers station health, the last 24 hours, server updates and your expectation checks: a crawler that stopped arriving, a cache that stopped hitting, a box that latches under load. A flag is New on the day it trips, then Ongoing with its age, and the digest is silent unless something needs you.
+- **`spinuptui sentinel attach`** adopts an existing Kuma's monitors on a fresh install, without changing anything in Kuma.
+- **Jobs can say they're blocked.** A job that ran but couldn't do its work now reports `blocked` instead of `ok`: an agent with `STATUS: blocked`, a script by exiting 75. Failed and blocked pages, and `/jobs`, get a **Run again** button. It re-runs the job exactly as written and never adds permissions.
+- **Team boards.** `spinuptui beacon add basecamp <name> --project <id>` connects a Basecamp message board for your own team's record. It can't be paged, and it's where Sentinel posts reports.
+
+### Changed
+- **`spinuptui incidents` output** gains `monitorId` on each event and a `failedMonitors` list, so a caller can tell "no events" from "couldn't read that monitor".
+
+### Fixed
+- **A long job no longer makes Kuma report a healthy station as dead.** The heartbeat was only sent when a tick finished, so a job past the 15-minute window looked like an outage. A tick that finds another still running now pings too.
+- **Beacon's listener no longer reads as down right after it starts.** Its first poll takes up to 50 seconds, so `beacon listener status` showed ✗ after an install, and a Scheduler tick in that window could have paged about a listener that was fine.
+
 ## [1.3.0-alpha.4] - 2026-10-30
 
 A pre-release, published on npm's `next` tag (`bun add -g spinuptui@next --no-cache`). `@latest` and Homebrew are on 1.2.1.
@@ -1545,7 +1563,8 @@ Initial tagged release.
 ### Notes
 - Read-only release: works with a SpinupWP **Read Only** API token.
 
-[Unreleased]: https://github.com/mwender/spinupwp-tui/compare/v1.3.0-alpha.4...HEAD
+[Unreleased]: https://github.com/mwender/spinupwp-tui/compare/v1.3.0-alpha.5...HEAD
+[1.3.0-alpha.5]: https://github.com/mwender/spinupwp-tui/compare/v1.3.0-alpha.4...v1.3.0-alpha.5
 [1.3.0-alpha.4]: https://github.com/mwender/spinupwp-tui/compare/v1.3.0-alpha.3...v1.3.0-alpha.4
 [1.3.0-alpha.3]: https://github.com/mwender/spinupwp-tui/compare/v1.3.0-alpha.2...v1.3.0-alpha.3
 [1.2.1]: https://github.com/mwender/spinupwp-tui/compare/v1.2.0...v1.2.1

package/README.md

@@ -91,6 +91,11 @@
   any machine. One LaunchAgent ticks every 5 minutes and is the clock the other
   modules run on, and a station heartbeat (`h`) pings your Uptime Kuma each
   tick, so a station that stops is noticed from elsewhere. → [docs/scheduler.md](docs/scheduler.md)
+  Then **Sentinel**: watches the fleet, works out what actually broke, and
+  writes it up. A page tells you why, not just that something's down, and a
+  morning digest covers what monitoring can't see, like a crawler that stopped
+  arriving or a cache that stopped hitting. Bring your own agent for diagnosis,
+  or use it without one. → [docs/sentinel.md](docs/sentinel.md)
 - **Non-interactive CLI subcommands for external tooling** — `spinuptui ssh <domain>`
   resolves a domain to a live SSH target with a live connectivity probe;
   `spinuptui ssh-exec <domain> -- <command>` runs a command over SSH, but only
@@ -385,8 +390,9 @@ These can be set in `config.json` or via an environment variable:
 | `w` | Open the selected server/site in the SpinupWP web app |
 | `/` | Jump to global search |
 | `A` | Accounts — switch, add, rename, or remove SpinupWP accounts (from anywhere) |
-| `⏎` / `s` | Set up the selected module — Beacon opens its guided Telegram setup, Scheduler its install plan (Modules tab) |
-| `t` | Send a test page through Beacon (Modules tab, once Beacon is set up) |
+| `⏎` / `s` | Set up the selected module — Beacon opens its guided Telegram setup, Scheduler its install plan, Sentinel its setup (Modules tab) |
+| `t` | Send a test page through Beacon, or preview Sentinel's digest (Modules tab) |
+| `p` | Pause Sentinel for 2 hours, or resume it (Modules tab, Sentinel) |
 | `l` | Beacon's listener: install it so the pager answers `/jobs`, see whether it's running, or remove it (Modules tab, Beacon) |
 | `f` | Your SpinupTUI folder: where jobs and reports live, and sharing it across machines (Modules tab, Scheduler) |
 | `h` | Station heartbeat: set up the Uptime Kuma push monitor, see the last ping, test or remove it (Modules tab, Scheduler) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spinuptui",
-  "version": "1.3.0-alpha.4",
+  "version": "1.3.0-alpha.5",
   "description": "SpinupTUI — a terminal dashboard for browsing, monitoring, and managing your SpinupWP servers and sites.",
   "type": "module",
   "bin": {

package/src/config.ts

@@ -112,6 +112,7 @@ export interface AppConfig {
   // Scheduler's sources and installed dispatcher (lib/scheduler*.ts,
   // docs/2026-10-20_scheduler-spec.md). Machine-level: a station runs one clock.
   scheduler: SchedulerStored | null
+  sentinel: SentinelStored | null
   // Where modules put the user's work (Scheduler's jobs and reports…); null =
   // the default, ~/SpinupTUI. SPINUPTUI_HOME overrides. See modules/contract.ts.
   homeDir: string | null
@@ -127,14 +128,40 @@ export interface BeaconTelegramChannel {
 // are additive.
 export type BeaconChannel = BeaconTelegramChannel
 
+// A Basecamp project's message board, for the team's own record. Not a channel:
+// it's never paged, and only a named post reaches it. `audience` exists so a
+// client-facing board can't be reached by accident: only "team" is accepted
+// until the client channel's gate is built.
+export interface BeaconBoard {
+  type: "basecamp"
+  projectId: string
+  mention?: string // the person @-mentioned on a new post
+  audience: "team"
+}
+
 export interface BeaconStored {
   defaultChannel?: string
   channels?: Record<string, BeaconChannel>
+  boards?: Record<string, BeaconBoard>
   // Written by `beacon listener install --apply`, cleared by uninstall: the
   // resident process that answers the operator (lib/beaconListen.ts).
   listener?: { label: string; unitPath: string; bin: string; channel: string; installedAt: string }
 }
 
+// Sentinel's settings (docs/2026-10-30_sentinel-spec.md). Machine-level, and
+// written only by setup: everything it does while running lives in its state
+// directory.
+export interface SentinelStored {
+  enabled?: boolean
+  mode?: "live" | "shadow"
+  channel?: string | null // Beacon channel for pages; default Beacon's default
+  reportTo?: string | null // a Beacon board's name
+  workspace?: string
+  recurrenceHours?: number
+  maxDiagnosesPerDay?: number
+  diagnosis?: { agent?: "claude" | "codex" | null; model?: string | null; timeoutMin?: number; allow?: string | null }
+}
+
 export interface SchedulerStored {
   // Named job sources beyond the built-in `local` one: directories holding
   // jobs/ and runs/, pulled and pushed when they are git repositories.
@@ -249,6 +276,7 @@ export interface StoredConfig {
   lastSeenVersion?: string
   beacon?: BeaconStored
   scheduler?: SchedulerStored
+  sentinel?: SentinelStored
   homeDir?: string
 }
 
@@ -537,6 +565,7 @@ export function loadConfig(): AppConfig {
     lastSeenVersion: stored.lastSeenVersion?.trim() || null,
     beacon: stored.beacon ?? null,
     scheduler: stored.scheduler ?? null,
+    sentinel: stored.sentinel ?? null,
     homeDir: stored.homeDir?.trim() || null,
   }
 }

package/src/index.tsx

@@ -115,6 +115,9 @@ Usage:
                        Queue a follow-up for this station to run later and report
                        on through Beacon (\`spinuptui scheduler\` for the rest)
   spinuptui scheduler list | status | install --plan|--apply
+  spinuptui sentinel setup | attach | status | list | pause | expect
+                       Watch the fleet, work out what broke, write it up
+                       (runs as Scheduler jobs; see docs/sentinel.md)
   spinuptui home       Where the SpinupTUI folder (your jobs and reports) is
   spinuptui home sync --plan|--apply --github <name> | --remote <url> | --clone <url>
                        Share that folder across machines through a private git
@@ -328,6 +331,11 @@ if (command === "scheduler") {
   process.exit(await runScheduler(args.slice(args.indexOf("scheduler") + 1)))
 }
 
+if (command === "sentinel") {
+  const { runSentinel } = await import("./lib/cliSentinel.ts")
+  process.exit(await runSentinel(args.slice(args.indexOf("sentinel") + 1)))
+}
+
 // `spinuptui login` forces the onboarding wizard even when a token already exists,
 // so the token can be (re)saved to the config file for global use.
 const { startDashboard } = await import("./ui/main.tsx")

package/src/lib/beacon.test.ts

@@ -138,3 +138,17 @@ describe("beaconSend", () => {
     expect(f.calls.length).toBe(2)
   })
 })
+
+describe("buttons on a page", () => {
+  test("go on the last part only", async () => {
+    const bodies: URLSearchParams[] = []
+    const beacon: ResolvedBeacon = { channels: [{ name: "pager", channel: { type: "telegram", botToken: "1:a", chatId: "2" }, env: false }], defaultChannel: "pager" }
+    const fetchImpl = (async (_u: string, init?: RequestInit) => (bodies.push(init!.body as URLSearchParams), Response.json({ ok: true, result: {} }))) as never
+    const long = Array.from({ length: 300 }, (_, i) => `line ${i} ${"x".repeat(40)}`).join("\n")
+    const r = await beaconSend(beacon, long, { replyMarkup: '{"inline_keyboard":[]}', fetchImpl, log: false })
+    expect(r.ok).toBe(true)
+    expect(bodies.length).toBeGreaterThan(1)
+    expect(bodies.slice(0, -1).some((b) => b.has("reply_markup"))).toBe(false)
+    expect(bodies[bodies.length - 1]!.get("reply_markup")).toBe('{"inline_keyboard":[]}')
+  })
+})

package/src/lib/beacon.ts

@@ -227,6 +227,8 @@ export type SendResult =
 export interface SendOptions {
   to?: string | null
   silent?: boolean
+  // Telegram's reply_markup for the last part. Build it with pageMarkup().
+  replyMarkup?: string
   fetchImpl?: Fetch
   wait?: (ms: number) => Promise<unknown>
   log?: boolean
@@ -271,7 +273,7 @@ export async function beaconSend(beacon: ResolvedBeacon, text: string, opts: Sen
   const wait = opts.wait ?? sleep
   let sent = 0
   let failure: string | undefined
-  for (const part of parts) {
+  for (const [i, part] of parts.entries()) {
     const r = await telegramWithRetry(
       channel.botToken,
       "sendMessage",
@@ -280,6 +282,7 @@ export async function beaconSend(beacon: ResolvedBeacon, text: string, opts: Sen
         text: part,
         disable_web_page_preview: "true",
         ...(opts.silent ? { disable_notification: "true" } : {}),
+        ...(opts.replyMarkup && i === parts.length - 1 ? { reply_markup: opts.replyMarkup } : {}),
       },
       fetchImpl,
       wait,

package/src/lib/beaconBoard.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test"
+import type { BeaconBoard } from "../config.ts"
+import { markdownToBasecampHtml, postToBoard, splitTitle, type BasecampRun } from "./beaconBoard.ts"
+
+const board: BeaconBoard = { type: "basecamp", projectId: "123", mention: "Pat Doe", audience: "team" }
+
+function fakeCli(post: { code: number; out: string }): { run: BasecampRun; calls: string[][] } {
+  const calls: string[][] = []
+  const run: BasecampRun = async (args) => {
+    calls.push(args)
+    if (args[0] === "api" && args[1] === "get") return { code: 0, out: JSON.stringify({ ok: true, data: { dock: [{ id: 9, name: "message_board" }] } }) }
+    if (args[0] === "people") return { code: 0, out: JSON.stringify({ ok: true, data: [{ name: "Pat Doe", attachable_sgid: "sg" }] }) }
+    return post
+  }
+  return { run, calls }
+}
+
+describe("markdownToBasecampHtml", () => {
+  test("renders what a report uses", () => {
+    const html = markdownToBasecampHtml("## Root cause\n\nThe **cron** ran `wp` twice.\n\n- [x] done\n- [ ] todo\n\n| A | B |\n|---|---|\n| 1 | 2 |\n\n```\nx < y\n```\n")
+    expect(html).toContain("<h2>Root cause</h2>")
+    expect(html).toContain("<p>The <strong>cron</strong> ran <code>wp</code> twice.</p>")
+    expect(html).toContain("<li>☑ done</li>")
+    expect(html).toContain("<li>☐ todo</li>")
+    expect(html).toContain("<th>A</th>")
+    expect(html).toContain("<td>2</td>")
+    expect(html).toContain("<pre><code>x &lt; y</code></pre>")
+  })
+
+  test("escapes anything a log line could carry, and joins soft-wrapped text", () => {
+    expect(markdownToBasecampHtml("a <script>alert(1)</script>\nb")).toBe("<p>a &lt;script&gt;alert(1)&lt;/script&gt; b</p>")
+    expect(markdownToBasecampHtml("<img src=x onerror=y>")).toBe("<p>&lt;img src=x onerror=y&gt;</p>")
+  })
+
+  test("keeps real links and flattens local ones", () => {
+    expect(markdownToBasecampHtml("[a](https://example.com) [b](2026-10-30-x.md)")).toBe('<p><a href="https://example.com">a</a> b</p>')
+  })
+})
+
+describe("postToBoard", () => {
+  const report = "# 10/30/2026 (13:34) - example.com - health\n\n## Symptom\n\nDown."
+
+  test("uses the H1 as the title and returns the message", async () => {
+    const { run, calls } = fakeCli({ code: 0, out: JSON.stringify({ ok: true, data: { id: 42, app_url: "https://bc/42" } }) })
+    expect(await postToBoard(board, report, run)).toEqual({ ok: true, id: "42", url: "https://bc/42" })
+    const post = calls.find((c) => c[1] === "post")!
+    expect(post[2]).toBe("buckets/123/message_boards/9/messages.json")
+    const payload = JSON.parse(post[4]!) as { subject: string; content: string }
+    expect(payload.subject).toBe("10/30/2026 (13:34) - example.com - health")
+    expect(payload.content).toContain('sgid="sg"')
+    expect(payload.content).not.toContain("<h1")
+  })
+
+  test("refuses a report with no title, and anything but a team board", async () => {
+    const { run } = fakeCli({ code: 0, out: "{}" })
+    expect(await postToBoard(board, "no heading", run)).toMatchObject({ ok: false, reason: "bad_report" })
+    expect(await postToBoard({ ...board, audience: "client" as never }, report, run)).toMatchObject({ ok: false })
+  })
+
+  test("reports a refused post", async () => {
+    const { run } = fakeCli({ code: 1, out: "nope" })
+    expect(await postToBoard(board, report, run)).toMatchObject({ ok: false, reason: "api" })
+  })
+
+  test("splitTitle", () => {
+    expect(splitTitle("# T\nbody")).toEqual({ title: "T", body: "body" })
+    expect(splitTitle("body").title).toBe("")
+  })
+})

package/src/lib/beaconBoard.ts

@@ -0,0 +1,197 @@
+// Beacon's boards: a Basecamp project's message board, for the team's own record
+// (docs/2026-10-30_sentinel-spec.md, "Basecamp"). A board isn't a pager channel.
+// It carries reports for the team that owns the fleet, and nothing here can reach
+// a client: `audience` only accepts "team" until that gate is built.
+//
+// The HTML is made here rather than by the CLI's converter, whose output depends
+// on the installed version: one version posted a whole report as literal ## and
+// **. The post goes through `basecamp api`, so its login stays the CLI's business.
+// Basecamp has no idempotency key, so a caller must record a post before and
+// after making it (see the worker) rather than retry blindly.
+
+import type { BeaconBoard } from "../config.ts"
+import { jobEnv } from "./schedulerRun.ts"
+import { spawn } from "./spawn.ts"
+
+// ---- Markdown → Basecamp HTML ------------------------------------------------------
+
+const esc = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+const escAttr = (s: string) => esc(s).replace(/"/g, "&quot;")
+
+const HEADING = /^(#{1,6})\s+(.*)$/
+const LIST_ITEM = /^\s*(?:([-*+])|(\d+)\.)\s+(.*)$/
+const TASK_MARK = /^\[([ xX])\]\s+/
+const TABLE_SEP = /^\s*\|[\s:|-]+\|\s*$/
+
+function inline(text: string): string {
+  const spans: string[] = []
+  let out = text.replace(/`([^`]+)`/g, (_, code: string) => {
+    spans.push(`<code>${esc(code)}</code>`)
+    return `\x00${spans.length - 1}\x00`
+  })
+  out = esc(out)
+  // A relative link points at a local file that means nothing to a board reader.
+  out = out.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_, label: string, target: string) =>
+    /^(https?:\/\/|mailto:)/.test(target) ? `<a href="${escAttr(target)}">${label}</a>` : label,
+  )
+  out = out.replace(/\*\*(.+?)\*\*/gs, "<strong>$1</strong>")
+  out = out.replace(/(?<![\w*])\*(?!\s)([^*]+?)(?<!\s)\*(?![\w*])/g, "<em>$1</em>")
+  // eslint-disable-next-line no-control-regex
+  return out.replace(/\x00(\d+)\x00/g, (_, n: string) => spans[Number(n)]!)
+}
+
+function splitRow(line: string): string[] {
+  return line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((c) => c.trim())
+}
+
+// Headings, paragraphs, lists with task items, GFM tables, fenced code,
+// blockquotes, rules, bold, italic, code and links: what a report uses.
+export function markdownToBasecampHtml(md: string): string {
+  const lines = md.replace(/<!--[\s\S]*?-->/g, "").split("\n")
+  const out: string[] = []
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i]!
+    if (!line.trim()) {
+      i++
+      continue
+    }
+    if (line.trimStart().startsWith("```")) {
+      const code: string[] = []
+      i++
+      while (i < lines.length && !lines[i]!.trimStart().startsWith("```")) code.push(lines[i++]!)
+      i++
+      out.push(`<pre><code>${esc(code.join("\n"))}</code></pre>`)
+      continue
+    }
+    if (/^\s*-{3,}\s*$/.test(line)) {
+      out.push("<hr>")
+      i++
+      continue
+    }
+    const heading = HEADING.exec(line)
+    if (heading) {
+      const level = Math.min(Math.max(heading[1]!.length, 2), 4) // never an h1 in a post
+      out.push(`<h${level}>${inline(heading[2]!.trim())}</h${level}>`)
+      i++
+      continue
+    }
+    if (line.trim().startsWith("|") && i + 1 < lines.length && TABLE_SEP.test(lines[i + 1]!)) {
+      const rows = [splitRow(line)]
+      i += 2
+      while (i < lines.length && lines[i]!.trim().startsWith("|")) rows.push(splitRow(lines[i++]!))
+      const body = rows.map((cells, n) => `<tr>${cells.map((c) => `<${n ? "td" : "th"}>${inline(c)}</${n ? "td" : "th"}>`).join("")}</tr>`)
+      out.push(`<table>\n${body.join("\n")}\n</table>`)
+      continue
+    }
+    if (line.trimStart().startsWith("> ")) {
+      const quote: string[] = []
+      while (i < lines.length && lines[i]!.trimStart().startsWith(">")) quote.push(lines[i++]!.trimStart().slice(1).trim())
+      out.push(`<blockquote><p>${inline(quote.join(" "))}</p></blockquote>`)
+      continue
+    }
+    const first = LIST_ITEM.exec(line)
+    if (first) {
+      const ordered = first[2] !== undefined
+      const items: string[] = []
+      while (i < lines.length && lines[i]!.trim()) {
+        const m = LIST_ITEM.exec(lines[i]!)
+        if (m && (m[2] !== undefined) === ordered) {
+          const text = m[3]!
+          const task = TASK_MARK.exec(text)
+          items.push(task ? `${task[1]!.toLowerCase() === "x" ? "☑" : "☐"} ${text.slice(task[0].length)}` : text)
+        } else {
+          items[items.length - 1] += ` ${lines[i]!.trim()}`
+        }
+        i++
+      }
+      const tag = ordered ? "ol" : "ul"
+      out.push(`<${tag}>\n${items.map((t) => `<li>${inline(t)}</li>`).join("\n")}\n</${tag}>`)
+      continue
+    }
+    const para: string[] = []
+    while (i < lines.length && lines[i]!.trim()) {
+      const next = lines[i]!
+      if (para.length && (HEADING.test(next) || LIST_ITEM.test(next) || /^\s*(```|> |\|)/.test(next))) break
+      para.push(next.trim())
+      i++
+    }
+    out.push(`<p>${inline(para.join(" "))}</p>`)
+  }
+  return out.join("\n")
+}
+
+// A report's first line, its H1, is the post's title.
+export function splitTitle(md: string): { title: string; body: string } {
+  const m = /^\s*#\s+(.*?)\s*(\n|$)/.exec(md)
+  return m ? { title: m[1]!, body: md.slice(m[0].length) } : { title: "", body: md }
+}
+
+// ---- the post ----------------------------------------------------------------------
+
+export type BasecampRun = (args: string[]) => Promise<{ code: number; out: string }>
+
+const realRun: BasecampRun = async (args) => {
+  const p = spawn(["basecamp", ...args], { stdin: "ignore", stdout: "pipe", stderr: "pipe", env: jobEnv() })
+  const [out, err] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text()])
+  const code = await p.exited
+  return { code, out: code === 0 ? out : `${out}${err}`.trim() }
+}
+
+export type BoardPost = { ok: true; id: string; url: string } | { ok: false; reason: "cli_missing" | "auth" | "bad_report" | "api"; message: string }
+
+interface CliEnvelope<T> {
+  ok?: boolean
+  data?: T
+}
+
+async function cliJson<T>(run: BasecampRun, args: string[]): Promise<T | null> {
+  const r = await run([...args, "--json"])
+  if (r.code !== 0) return null
+  try {
+    const parsed = JSON.parse(r.out) as CliEnvelope<T>
+    return parsed.ok === false ? null : (parsed.data ?? null)
+  } catch {
+    return null
+  }
+}
+
+// Is the CLI logged in? Only meaningful from the real login session (the
+// dispatcher): a sandboxed shell can't read the Keychain, so a "no" there proves
+// nothing. A digest runs under the dispatcher, which is why it can ask.
+export async function boardLogin(run: BasecampRun = realRun): Promise<{ ok: boolean; detail: string }> {
+  try {
+    const me = await cliJson<{ identity?: { first_name?: string; last_name?: string } }>(run, ["me"])
+    if (!me) return { ok: false, detail: "not logged in: run `basecamp auth login` in a real terminal" }
+    return { ok: true, detail: [me.identity?.first_name, me.identity?.last_name].filter(Boolean).join(" ") || "logged in" }
+  } catch {
+    return { ok: false, detail: "the basecamp CLI isn't on the PATH" }
+  }
+}
+
+export async function postToBoard(board: BeaconBoard, report: string, run: BasecampRun = realRun): Promise<BoardPost> {
+  if (board.audience !== "team") return { ok: false, reason: "api", message: "Only team boards are supported." }
+  const { title, body } = splitTitle(report)
+  if (!title) return { ok: false, reason: "bad_report", message: "The report has no H1 to use as the post's title." }
+  try {
+    const project = await cliJson<{ dock?: { id: number; name: string }[] }>(run, ["api", "get", `buckets/${board.projectId}.json`])
+    const boardId = project?.dock?.find((d) => d.name === "message_board")?.id
+    if (!boardId) return { ok: false, reason: "auth", message: `Couldn't read project ${board.projectId}'s message board. Is \`basecamp\` logged in?` }
+    let content = markdownToBasecampHtml(body)
+    if (board.mention) {
+      // A mention's sgid is signed and expires, so it's resolved every time.
+      const people = await cliJson<{ name: string; attachable_sgid: string }[]>(run, ["people", "pingable"])
+      const sgid = people?.find((p) => p.name === board.mention)?.attachable_sgid
+      if (sgid) content = `<p><bc-attachment sgid="${escAttr(sgid)}" content-type="application/vnd.basecamp.mention"></bc-attachment> — new incident diagnosed and documented.</p>\n${content}`
+    }
+    const r = await run(["api", "post", `buckets/${board.projectId}/message_boards/${boardId}/messages.json`, "-d", JSON.stringify({ subject: title, status: "active", content }), "--json"])
+    if (r.code === 0) {
+      const d = (JSON.parse(r.out) as CliEnvelope<{ id: number; app_url: string }>).data
+      if (d?.id) return { ok: true, id: String(d.id), url: d.app_url }
+    }
+    return { ok: false, reason: "api", message: `Basecamp refused the post: ${r.out.slice(0, 300)}` }
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException
+    return e.code === "ENOENT" ? { ok: false, reason: "cli_missing", message: "The basecamp CLI isn't on the PATH." } : { ok: false, reason: "api", message: e.message }
+  }
+}

package/src/lib/beaconListen.test.ts

@@ -1,8 +1,9 @@
 import { beforeEach, describe, expect, test } from "bun:test"
-import { mkdtempSync } from "node:fs"
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { handleUpdate, listen, readListenerState, routesFrom, sendReply, storeButton, takeButton, type TgUpdate } from "./beaconListen.ts"
+import { listenerHealth } from "./beaconListenInstall.ts"
 import type { BeaconReply } from "../modules/contract.ts"
 
 const TOKEN = "123456789:AAEabcdefghijklmnopqrstuvwxyz0123456"
@@ -159,3 +160,31 @@ describe("listen", () => {
     await first
   })
 })
+
+describe("listenerHealth", () => {
+  const install = (state: Record<string, string>) => {
+    const dir = join(process.env.XDG_CONFIG_HOME!, "spinupwp-tui")
+    mkdirSync(join(dir, "modules", "beacon"), { recursive: true })
+    const unitPath = join(dir, "unit.plist")
+    writeFileSync(unitPath, "")
+    writeFileSync(join(dir, "config.json"), JSON.stringify({ beacon: { listener: { label: "t", unitPath, bin: "x", channel: "pager", installedAt: "2026-10-30T12:00:00Z" } } }))
+    writeFileSync(join(dir, "modules", "beacon", "listener.json"), JSON.stringify(state))
+  }
+  const now = Date.parse("2026-10-30T12:00:00Z")
+
+  test("a listener whose first poll is still out is alive, until that takes too long", () => {
+    install({ startedAt: "2026-10-30T11:59:40Z" })
+    expect(listenerHealth(now)?.ok).toBe(true)
+    install({ startedAt: "2026-10-30T11:50:00Z" })
+    expect(listenerHealth(now)?.ok).toBe(false)
+  })
+
+  test("stale polls and polls that keep failing are down", () => {
+    install({ startedAt: "2026-10-29T00:00:00Z", lastPollAt: "2026-10-30T11:59:30Z" })
+    expect(listenerHealth(now)?.ok).toBe(true)
+    install({ startedAt: "2026-10-29T00:00:00Z", lastPollAt: "2026-10-30T11:50:00Z" })
+    expect(listenerHealth(now)?.ok).toBe(false)
+    install({ startedAt: "2026-10-29T00:00:00Z", lastPollAt: "2026-10-30T11:59:30Z", failingSince: "2026-10-30T11:45:00Z", lastError: "Conflict" })
+    expect(listenerHealth(now)?.detail).toContain("Conflict")
+  })
+})

package/src/lib/beaconListen.ts

@@ -21,9 +21,9 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSy
 import { randomBytes } from "node:crypto"
 import { dirname, join } from "node:path"
 import type { BeaconChannel } from "../config.ts"
-import { moduleStateDir, type BeaconActionDecl, type BeaconCommandDecl, type BeaconReply, type ModuleDefinition } from "../modules/contract.ts"
+import { moduleStateDir, type BeaconActionDecl, type BeaconButton, type BeaconCommandDecl, type BeaconReply, type ModuleDefinition } from "../modules/contract.ts"
 import { htmlToPlain, splitMessage, telegramCall, type Fetch } from "./beacon.ts"
-import { tryLock } from "./flock.ts"
+import { tryLock, type HeldLock } from "./flock.ts"
 
 export const POLL_SECONDS = 50
 // A /command older than this when it arrives (sent while the listener was down)
@@ -37,6 +37,7 @@ export const listenerStatePath = () => join(listenerDir(), "listener.json")
 export const listenerLockPath = () => join(listenerDir(), "listener.lock")
 export const listenerLogPath = () => join(listenerDir(), "listener.log")
 const buttonsPath = () => join(listenerDir(), "buttons.json")
+const buttonsLockPath = () => join(listenerDir(), "buttons.lock")
 
 export interface ListenerState {
   channel?: string
@@ -112,23 +113,47 @@ interface StoredButton {
   createdAt: string
 }
 
+// The tick and Sentinel's worker store buttons while the listener takes them, so
+// each read-modify-write holds this. It's held for a millisecond, and a button
+// is worth more than the lock: past the wait, go ahead without it.
+function withButtons<T>(fn: () => T): T {
+  let lock: HeldLock | null = null
+  for (let i = 0; i < 100 && !lock; i++) {
+    lock = tryLock(buttonsLockPath())
+    if (!lock) Bun.sleepSync(10)
+  }
+  try {
+    return fn()
+  } finally {
+    lock?.release()
+  }
+}
+
 export function storeButton(action: string, payload: Record<string, string>, now = new Date()): string {
-  const all = readJson<Record<string, StoredButton>>(buttonsPath(), {})
-  for (const [k, b] of Object.entries(all)) if (now.getTime() - Date.parse(b.createdAt) > BUTTON_TTL_MS) delete all[k]
-  const token = randomBytes(6).toString("base64url")
-  all[token] = { action, payload, createdAt: now.toISOString() }
-  writeJson(buttonsPath(), all)
-  return token
+  return withButtons(() => {
+    const all = readJson<Record<string, StoredButton>>(buttonsPath(), {})
+    for (const [k, b] of Object.entries(all)) if (now.getTime() - Date.parse(b.createdAt) > BUTTON_TTL_MS) delete all[k]
+    const token = randomBytes(6).toString("base64url")
+    all[token] = { action, payload, createdAt: now.toISOString() }
+    writeJson(buttonsPath(), all)
+    return token
+  })
+}
+
+export function buttonMarkup(buttons: BeaconButton[][], now = new Date()): string {
+  return JSON.stringify({ inline_keyboard: buttons.map((row) => row.map((b) => ({ text: b.text, callback_data: `b:${storeButton(b.action, b.payload, now)}` }))) })
 }
 
 // The button for `token`, removed so it can't be used twice.
 export function takeButton(token: string): StoredButton | null {
-  const all = readJson<Record<string, StoredButton>>(buttonsPath(), {})
-  const b = all[token]
-  if (!b) return null
-  delete all[token]
-  writeJson(buttonsPath(), all)
-  return b
+  return withButtons(() => {
+    const all = readJson<Record<string, StoredButton>>(buttonsPath(), {})
+    const b = all[token]
+    if (!b) return null
+    delete all[token]
+    writeJson(buttonsPath(), all)
+    return b
+  })
 }
 
 // ---- Telegram -----------------------------------------------------------------
@@ -168,9 +193,7 @@ export async function sendReply(ctx: ListenContext, reply: BeaconReply): Promise
   for (let i = 0; i < parts.length; i++) {
     const params: Record<string, string> = { chat_id: ctx.channel.chatId, text: parts[i]!, disable_web_page_preview: "true" }
     if (i === parts.length - 1 && reply.buttons?.length) {
-      const now = ctx.now?.() ?? new Date()
-      const keyboard = reply.buttons.map((row) => row.map((b) => ({ text: b.text, callback_data: `b:${storeButton(b.action, b.payload, now)}` })))
-      params.reply_markup = JSON.stringify({ inline_keyboard: keyboard })
+      params.reply_markup = buttonMarkup(reply.buttons, ctx.now?.() ?? new Date())
     }
     if (reply.html) params.parse_mode = "HTML"
     let r = await telegramCall(ctx.channel.botToken, "sendMessage", params, ctx.fetchImpl)

package/src/lib/beaconListenInstall.ts

@@ -9,8 +9,9 @@ import { homedir } from "node:os"
 import { dirname, join } from "node:path"
 import { loadConfig, saveConfig } from "../config.ts"
 import { beaconFromConfig, beaconSend, pickChannel } from "./beacon.ts"
-import { channelProblem, listenerDir, listenerLogPath, readListenerState } from "./beaconListen.ts"
+import { buttonMarkup, channelProblem, listenerDir, listenerLogPath, readListenerState } from "./beaconListen.ts"
 import { helpIncludes, launchctl, resolveRunner } from "./schedulerInstall.ts"
+import type { BeaconButton } from "../modules/contract.ts"
 
 export const DEFAULT_LISTENER_LABEL = "com.spinuptui.beacon-listener"
 // Three missed polls, with room for a restart.
@@ -208,6 +209,12 @@ export function listenerInstalled(): boolean {
 }
 
 // Is the installed listener answering? null when none is installed.
+// Inline buttons for a page. Only the listener can receive a tap, so with none
+// installed a page goes out without them.
+export function pageMarkup(buttons: BeaconButton[][]): string | undefined {
+  return listenerInstalled() ? buttonMarkup(buttons) : undefined
+}
+
 export function listenerHealth(now = Date.now()): { ok: boolean; detail: string } | null {
   if (!listenerInstalled()) return null
   try {
@@ -217,14 +224,16 @@ export function listenerHealth(now = Date.now()): { ok: boolean; detail: string
     // Not paused.
   }
   const st = readListenerState()
-  const last = st.lastPollAt ? Date.parse(st.lastPollAt) : NaN
-  if (!Number.isFinite(last) || now - last > LISTENER_STALE_MS) {
+  // A listener that just started has a first poll still out (up to 50 seconds),
+  // so its start counts as a sign of life too.
+  const last = Math.max(...[st.lastPollAt, st.startedAt].map((t) => (t ? Date.parse(t) : 0)))
+  if (now - last > LISTENER_STALE_MS) {
     return { ok: false, detail: `hasn't polled Telegram since ${st.lastPollAt ?? "it was installed"}; see ${listenerLogPath()}` }
   }
   if (st.failingSince && now - Date.parse(st.failingSince) > LISTENER_FAILING_MS) {
     return { ok: false, detail: `polls failing since ${st.failingSince}: ${st.lastError ?? "unknown error"}` }
   }
-  return { ok: true, detail: `listening on ${st.channel ?? "?"} (pid ${st.pid ?? "?"}, ${st.version ?? "?"}), last poll ${st.lastPollAt}` }
+  return { ok: true, detail: `listening on ${st.channel ?? "?"} (pid ${st.pid ?? "?"}, ${st.version ?? "?"}), ${st.lastPollAt ? `last poll ${st.lastPollAt}` : `started ${st.startedAt}`}` }
 }
 
 // Telegram hands a bot's updates to one reader at a time, so Beacon setup's chat