spinuptui 1.3.0-alpha.3 → 1.3.0-alpha.5

package/CHANGELOG.md

@@ -11,6 +11,35 @@ 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.
+
+### Added
+- **Keep a job running longer without editing its file.** `spinuptui scheduler extend <id> --by 1y` moves a job's expiry a year later (`--by` takes days, weeks, months or years: `30d`, `2w`, `6m`, `1y`), or `--expires YYYY-MM-DD` sets a date. `--by` counts from the current expiry, or from today if the job has already expired. Only the `expires:` line changes, and in a git source the change is committed and pushed like `add` and `cancel`. It refuses a date that isn't later; to stop a job sooner, cancel it.
+- **The pager answers back: send `/jobs` to your Beacon bot.** Beacon's new listener lets you message the station from Telegram. `/jobs` replies with the station's scheduled jobs, soonest expiry first, and flags any that expire within 14 days. Recurring jobs about to expire get an **Extend 1 year** button, which commits and pushes the change like `scheduler extend`. Turn it on with `l` on the Modules tab's Beacon card, or `spinuptui beacon listener install --plan|--apply`. It runs as a LaunchAgent that launchd keeps alive and restarts itself after an upgrade. Scheduler's tick pages you if it stops polling. It answers only your own private chat with the bot, ignores everyone else without replying, acts on each message once, and makes every button work once. Beacon setup stops it while it looks for your chat, because Telegram allows only one reader of a bot's messages. See [docs/beacon.md](docs/beacon.md#let-the-pager-answer-you).
+
+### Fixed
+- **`scheduler status` points to the right heartbeat setup.** With a saved Uptime Kuma login, the "heartbeat: not set" line now suggests `h` on the Scheduler card or `scheduler heartbeat setup`, which create the monitor for you, instead of the manual `heartbeat set <url>`.
+
 ## [1.3.0-alpha.3] - 2026-10-27
 
 A pre-release, published on npm's `next` tag (`bun add -g spinuptui@next --no-cache`). `@latest` and Homebrew are on 1.2.1.
@@ -1534,7 +1563,9 @@ 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.3...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
 [1.3.0-alpha.2]: https://github.com/mwender/spinupwp-tui/compare/v1.3.0-alpha.1...v1.3.0-alpha.2

package/README.md

@@ -81,7 +81,9 @@
   each set up from the same screen. First up, **Beacon**: `spinuptui beacon send`
   pages you on Telegram from any cron job, watcher or agent, with retries, long
   messages split instead of dropped, and a send log. A guided setup creates the
-  bot connection for you. → [docs/beacon.md](docs/beacon.md)
+  bot connection for you. The pager also answers back: with the listener on
+  (`l`), send `/jobs` to your bot to see the station's jobs and extend the ones
+  expiring soon with a tap. → [docs/beacon.md](docs/beacon.md)
   Then **Scheduler**: follow-ups that run themselves. Queue "check this
   tomorrow at 8" from any session, and the result arrives through Beacon. Jobs
   and reports live in `~/SpinupTUI/scheduler/`; `spinuptui home sync` (or `f`)
@@ -89,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
@@ -383,8 +390,10 @@ 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) |
 | `r` | Refresh data from the API |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spinuptui",
-  "version": "1.3.0-alpha.3",
+  "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,9 +128,38 @@ 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 {
@@ -246,6 +276,7 @@ export interface StoredConfig {
   lastSeenVersion?: string
   beacon?: BeaconStored
   scheduler?: SchedulerStored
+  sentinel?: SentinelStored
   homeDir?: string
 }
 
@@ -534,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

@@ -107,11 +107,17 @@ Usage:
                        Add a channel from a file holding TELEGRAM_BOT_TOKEN and
                        TELEGRAM_CHAT_ID; sends a test message before saving.
   spinuptui beacon test | status | remove <name>
+  spinuptui beacon listen | listener install --plan|--apply
+                       Let the pager answer: /jobs lists this station's scheduled
+                       jobs, with a button to extend any that expire soon
   spinuptui scheduler add <id> --kind spinuptui|script|agent --when <time> | --every <schedule>
                        --expires <date> --created-by <who> -- <body>
                        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
@@ -325,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

@@ -104,6 +104,16 @@ export function splitMessage(text: string, budget = PART_BUDGET, maxParts = MAX_
   return parts.map((p, i) => `(${i + 1}/${parts.length}) ${p}`)
 }
 
+// For replies sent as Telegram HTML, where only these three are special. Pages
+// stay plain text, so a markup mistake can never cost an alert.
+export function escapeHtml(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+}
+
+export function htmlToPlain(html: string): string {
+  return html.replace(/<[^>]*>/g, "").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&")
+}
+
 // Parse a KEY=VALUE env file the way the existing shell senders write them:
 // `export ` prefixes, quotes and # comments allowed.
 export function parseEnvFile(text: string): Record<string, string> {
@@ -217,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
@@ -261,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",
@@ -270,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 }
+  }
+}