sportsing 0.2.0 → 0.3.0

package/README.md

@@ -27,6 +27,13 @@ bun install -g sportsing     # or: npm install -g sportsing
 sportsing --version
 ```
 
+To update later, run `sportsing upgrade`. It checks npm for the latest release
+and reinstalls it with whichever of npm or bun installed your copy.
+`sportsing upgrade --check` only compares your version with the latest and
+installs nothing. A source checkout, a compiled binary or an `npx`/`bunx`
+run isn't updated in place. For those, the command prints how to update
+instead.
+
 From source:
 
 ```sh
@@ -90,7 +97,7 @@ through playoffs. Times are local; preseason games are tagged `PRE`, postseason
 | `season [team]` | Your favorites' season: record, home/away splits, playoff race |
 | `bracket [--season YYYY]` | Playoff bracket (projected before the postseason) |
 | `fav [add\|rm\|list]` | Manage NBA favorites (`fav add UTAH`, `fav add Jazz`) |
-| `watch [team] [--wait] [--provider X] [--url L] [--smoke]` | Open the game where you can watch it — see **Where to watch** below |
+| `watch [team] [--wait] [--provider X] [--url L] [--smoke] [--supervised]` | Open the game where you can watch it — see **Where to watch** below |
 | `live [--notify [--quiet]]` | Auto-refreshing live board; `--notify` alerts for favorites — see **Live fav-alerts** below |
 | `analyze <team> [team]` | AI read of the live or latest game: shooting, boards, turnovers, leaders (answered by `serve`; `--prompt` prints it) |
 | `predict <team> [team]` | AI prediction for the next game from both teams' recent form |
@@ -167,7 +174,8 @@ sportsing next       # each favorite's next game + countdown, soonest first
 sportsing me         # last result + next game per favorite team
 ```
 
-Bare `live --notify` alerts across every sport too (see **Live fav-alerts**).
+Bare `live --notify` alerts across every sport too (see **Live fav-alerts**),
+and `sportsing daemon` opens your teams' games when they start (see **Daemon**).
 Every other command needs a sport — a bare one (e.g. `sportsing standings`)
 prints the sports that have it and exits non-zero.
 
@@ -175,6 +183,47 @@ Favorites are stored per sport as `<sport>:<team>` (`nba:UTAH`, `nhl:UTAH`,
 `fifa:USA`) in `~/.config/sportsing/config.json`; add and remove them with each
 sport's `fav` command.
 
+## Daemon — open your teams' games automatically
+
+`sportsing daemon` is an always-on watcher (a per-user launchd agent on macOS):
+it polls every sport you have a favorite in and, when a favorite's game starts,
+does what `<sport> watch` would — Fubo / League Pass **opens the game window**;
+an over-the-air-only game gets a notification naming the channel; an
+unwatchable one gets a notification saying why. It's set up once and survives
+logins and `sportsing upgrade`.
+
+```sh
+sportsing daemon install       # write + load ~/Library/LaunchAgents/com.sportsing.daemon.plist
+sportsing daemon status        # is it running, what it's waiting for, what it last did
+sportsing daemon logs [-f]     # its log (~/Library/Logs/sportsing/daemon.log)
+sportsing daemon mode notify   # notify (click to watch) instead of auto-opening; `open` is the default
+sportsing daemon uninstall     # stop + remove it
+```
+
+- **Status at a glance.** Bare `today` / `next` / `me` end with a one-line
+  footer — `daemon: on — waiting for DEN @ UTAH 7:00 PM`, `daemon: off —
+  sportsing daemon install`, or `daemon: stuck — last poll 47m ago`.
+  `daemon status` shows installed / pid + uptime / last poll / next game and
+  where it'll open / last game acted on, flags **STUCK** when the last poll is
+  older than ~3 poll intervals, and exits 0 only when it's running and healthy
+  (scriptable).
+- **Each game is acted on once** (remembered in
+  `~/.cache/sportsing/daemon-state.json`): close the window and it stays closed;
+  a crash or restart doesn't open it twice. A game already under way that it
+  hasn't acted on yet (say the Mac woke mid-game) is opened then.
+- **Polling** is sparse (every 10 min) until 15 minutes before a favorite's
+  scheduled start, then every 30s until it goes live — including a delayed
+  start (up to 3h late).
+- **One sport failing** (e.g. FIFA without an API key) shows as a warning in
+  `status`; the others keep working.
+- **Install from a global install** (`npm install -g sportsing` or
+  `bun add -g sportsing`): the agent runs that install's stable `sportsing`
+  bin, and `sportsing upgrade` restarts it on the new version. Preview the
+  plist without installing: `sportsing daemon install --dry-run`.
+- The daemon opens the window as a detached `sportsing <sport> watch <team>
+  --supervised` (no terminal needed; closing the window ends it). Set up where
+  you watch first (`sportsing subscriptions set …`, see **Where to watch**).
+
 ## Upgrading to 0.2.0
 
 - **Breaking — bare commands need a sport.** In 0.1.x every bare command ran as a
@@ -305,6 +354,11 @@ One supervisor loop that **is** the whole setup: it opens your game and keeps th
 Claude session itself (no local model is ever spawned). `sportsing fifa agent-setup`
 prints this recipe; `sportsing fifa` and the watch nag point at it.
 
+> **NBA / NHL:** just to have your team's games open when they start, you don't
+> need this loop — use **`sportsing daemon install`** (see **Daemon**). It runs
+> without a Claude session and works across every sport with a favorite.
+> `/loop agent-setup` is for the FIFA overlay's Ask Claude / Get caught up.
+
 > **The cost, honestly:** the loop consumes that Claude session as the always-on
 > answerer for as long as it runs — that's the trade you're choosing. Stop the loop
 > and the heartbeat goes stale within ~90s, so the panels return to "○ No agent".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sportsing",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Sportsing — sports in your terminal: the FIFA World Cup 2026, the NBA, and the NHL. Schedules, favorites across every sport, live scores, standings, where-to-watch, browser streaming, highlights, stats, and AI analysis.",
   "type": "module",
   "bin": {

package/src/commands/cross.ts

@@ -19,13 +19,17 @@ import { fifa, fifaHasCommand } from "../sports/fifa.ts";
 import { NBA, nba } from "../sports/nba.ts";
 import { NHL, nhl } from "../sports/nhl.ts";
 import type { Match } from "../types.ts";
-import { fifaAlerter } from "./live.ts";
+import { matchState } from "../match-util.ts";
+import { fifaAlerter, fifaDaemonGames } from "./live.ts";
+import type { DaemonGame } from "../daemon.ts";
+import { daemonFooter } from "../daemon-io.ts";
 import { EXAMPLE_TEAM, addDays, localDateOf, matchHasTeam, withFallback, ymd } from "./_lib.ts";
 import {
   favoriteIds,
   gameHasTeam,
   gamesOnDays,
   leagueAlerter,
+  leagueDaemonGames,
   leagueHasCommand,
   parseOffset,
   teamSeason,
@@ -63,16 +67,13 @@ export interface Sport {
   favoriteTeams: () => Promise<TeamRows[] | null>;
   /** Favorite-team live alerter; null when the sport has no favorites. */
   alerter: () => Promise<Alerter | null>;
+  /** Favorite games for `sportsing daemon`; null when the sport has no favorites. */
+  daemonGames: () => Promise<DaemonGame[] | null>;
 }
 
 // ── FIFA (football-data `Match`) ─────────────────────────────────────────────
 
-/** A football-data match status as a sport-neutral game state. */
-export function matchState(m: Pick<Match, "status">): GameState {
-  if (m.status === "IN_PLAY" || m.status === "PAUSED") return "in";
-  if (m.status === "FINISHED" || m.status === "AWARDED") return "post";
-  return "pre";
-}
+export { matchState };
 
 const matchRow = (m: Match): Row => ({ id: String(m.id), start: m.utcDate, state: matchState(m), line: matchLine(m) });
 
@@ -89,6 +90,7 @@ const FIFA: Sport = {
   run: fifa,
   has: fifaHasCommand,
   alerter: fifaAlerter,
+  daemonGames: fifaDaemonGames,
   async favoritesOn(day) {
     const favs = await getFavorites("fifa");
     if (favs.length === 0) return null;
@@ -132,6 +134,7 @@ function league(cfg: LeagueConfig, run: Sport["run"]): Sport {
     run,
     has: leagueHasCommand,
     alerter: () => leagueAlerter(cfg),
+    daemonGames: () => leagueDaemonGames(cfg),
     async favoritesOn(day) {
       const favs = await favoriteTeamsOf();
       if (!favs) return null;
@@ -240,7 +243,15 @@ async function perSport<T>(sports: Sport[], load: (s: Sport) => Promise<T | null
 }
 
 /** `today [--tomorrow|--yesterday|--offset N]` — your teams' games on one local day. */
-export async function today(sports: Sport[], args: string[]): Promise<void> {
+/** Supplies the one-line daemon footer under today / next / me (null = none). */
+export type Footer = () => string | null;
+
+function printFooter(footer?: Footer): void {
+  const line = footer?.();
+  if (line) console.log("\n" + c.dim(line));
+}
+
+export async function today(sports: Sport[], args: string[], footer?: Footer): Promise<void> {
   const offset = parseOffset(args);
   const day = addDays(new Date(), offset);
   const loaded = await perSport(sports, (s) => s.favoritesOn(day));
@@ -251,16 +262,16 @@ export async function today(sports: Sport[], args: string[]): Promise<void> {
 
   const label = offset === 0 ? "Today" : offset === 1 ? "Tomorrow" : offset === -1 ? "Yesterday" : ymd(day);
   console.log(c.bold(c.cyan(`★ Your teams — ${label} (${ymd(day)})`)));
-  if (rows.length === 0) {
-    console.log(c.dim("\nNo games for your teams."));
-    return;
+  if (rows.length === 0) console.log(c.dim("\nNo games for your teams."));
+  else {
+    console.log();
+    for (const { sport, row } of rows) console.log("  " + tagged(sport, row.line));
   }
-  console.log();
-  for (const { sport, row } of rows) console.log("  " + tagged(sport, row.line));
+  printFooter(footer);
 }
 
 /** `next` — each favorite team's next game, soonest first, with countdowns. */
-export async function next(sports: Sport[]): Promise<void> {
+export async function next(sports: Sport[], footer?: Footer): Promise<void> {
   const loaded = await perSport(sports, (s) => s.favoriteTeams());
   if (!loaded) return;
   const now = Date.now();
@@ -269,18 +280,16 @@ export async function next(sports: Sport[]): Promise<void> {
     .sort((a, b) => byStart(a.row, b.row));
 
   console.log(c.bold(c.cyan("★ Your teams — Next up")));
-  if (rows.length === 0) {
-    console.log(c.dim("\nNo upcoming games for your teams."));
-    return;
-  }
+  if (rows.length === 0) console.log(c.dim("\nNo upcoming games for your teams."));
   for (const { sport, row } of rows) {
     console.log("\n  " + tagged(sport, row.line));
     console.log(`  ${c.bold(fmtDate(row.start))}  ${c.green("— starts " + relativeTime(row.start))}`);
   }
+  printFooter(footer);
 }
 
 /** `me` — every favorite team, every sport: last result and next game. */
-export async function me(sports: Sport[]): Promise<void> {
+export async function me(sports: Sport[], footer?: Footer): Promise<void> {
   const loaded = await perSport(sports, (s) => s.favoriteTeams());
   if (!loaded) return;
   const now = Date.now();
@@ -295,6 +304,7 @@ export async function me(sports: Sport[]): Promise<void> {
       if (!last && !next) console.log(c.dim("  no games found"));
     }
   }
+  printFooter(footer);
 }
 
 /** Startup line for bare `live`, e.g. "NBA: Utah Jazz · NHL: Utah Mammoth". */
@@ -342,10 +352,10 @@ export async function live(sports: Sport[], args: string[]): Promise<void> {
 
 /** Dispatch a bare `sportsing <cmd> …` (no sport prefix). */
 export async function bare(cmd: string, args: string[]): Promise<void> {
-  if (cmd === "today" || cmd === "t") return today(SPORTS, args);
+  if (cmd === "today" || cmd === "t") return today(SPORTS, args, daemonFooter);
   if (cmd === "live") return live(SPORTS, args);
   const run = cmd === "next" || cmd === "n" ? next : cmd === "me" ? me : null;
-  if (run && args.length === 0) return run(SPORTS);
+  if (run && args.length === 0) return run(SPORTS, daemonFooter);
   // Options on `next`/`me` (e.g. `--team`) are per-sport: say so rather than ignore them.
   const [first, ...rest] = bareHint(cmd, args, SPORTS, run !== null);
   console.error(c.red(first!));

package/src/commands/daemon.ts

@@ -0,0 +1,335 @@
+// `sportsing daemon …` — the always-on watcher (see src/daemon.ts for the
+// pure logic and src/daemon-io.ts for files + launchd).
+//
+//   install [--dry-run]   write + load the LaunchAgent (dry run: print the plist)
+//   uninstall             unload + remove it
+//   status [--json]       installed / running / last poll / next game / last action; exit 0 only if healthy
+//   logs [-f] [-n N]      tail the log
+//   mode [open|notify]    show or set what a game start does
+//   run [--once] [--dry-run]   the poll loop launchd runs (also usable in the foreground)
+
+import { spawn } from "child_process";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname } from "path";
+import { c } from "../ansi.ts";
+import { notify } from "../notify.ts";
+import { getDaemonMode, setDaemonMode } from "../config.ts";
+import { inTerminal, selfInvocation, shQuote } from "../click-to-watch.ts";
+import {
+  DAEMON_LABEL,
+  DAEMON_MODES,
+  agentPath,
+  daemonProgram,
+  fmtDuration,
+  isHealthy,
+  launchAgentPlist,
+  nextUp,
+  parseDaemonMode,
+  pollDelayMs,
+  pruneActed,
+  routeWhere,
+  staleAfterMs,
+  startsToAct,
+  whenLabel,
+  type DaemonGame,
+  type DaemonMode,
+  type DaemonState,
+  type DaemonStatus,
+  type LastAction,
+} from "../daemon.ts";
+import { LOG_DIR, LOG_FILE, PLIST_PATH, STATE_FILE, gatherStatus, readState, systemLaunchd, writeState, type Launchd } from "../daemon-io.ts";
+import { describeInstall, detectInstall } from "../upgrade.ts";
+import { SPORTS, type Sport } from "./cross.ts";
+import { runningScript } from "./upgrade.ts";
+
+function usage(): void {
+  console.log(`${c.bold("sportsing daemon")} — always-on watcher: opens your teams' games when they start
+
+  sportsing daemon install [--dry-run]   install + start the LaunchAgent (runs at login, restarts if it dies)
+  sportsing daemon uninstall             stop + remove it
+  sportsing daemon status [--json]       is it running, what it's waiting for, what it last did (exit 0 = healthy)
+  sportsing daemon logs [-f] [-n N]      show (or follow) its log
+  sportsing daemon mode [open|notify]    what a game start does: open the window (default) or notify with click-to-watch
+  sportsing daemon run [--once] [--dry-run]   the loop itself, in the foreground (--dry-run: act on nothing)`);
+}
+
+function fail(msg: string, hint?: string): void {
+  console.error(c.red(msg));
+  if (hint) console.error(c.dim(hint));
+  process.exitCode = 1;
+}
+
+const tilde = (p: string) => (p.startsWith(homedir()) ? "~" + p.slice(homedir().length) : p);
+
+// ── install / uninstall ──────────────────────────────────────────────────────
+
+/** The plist for this install, or an error saying why there isn't one. */
+export function plistForThisInstall(): { plist: string; program: string[] } | { error: string } {
+  const install = detectInstall(runningScript());
+  const program = daemonProgram(install, { execPath: process.execPath, bunOnPath: Bun.which("bun"), exists: existsSync });
+  if (!program) {
+    return {
+      error: `Can't install the daemon from a ${describeInstall(install)} — it needs a stable path to run. Install sportsing globally first: npm install -g sportsing (or bun add -g sportsing).`,
+    };
+  }
+  const plist = launchAgentPlist({ label: DAEMON_LABEL, program, logPath: LOG_FILE, path: agentPath(process.env.PATH), home: homedir() });
+  return { plist, program };
+}
+
+export function install(args: string[], launchd: Launchd): void {
+  const made = plistForThisInstall();
+  if ("error" in made) return fail(made.error);
+  if (args.includes("--dry-run")) {
+    console.log(c.dim(`# would write ${PLIST_PATH} and run: launchctl bootstrap gui/<uid> ${tilde(PLIST_PATH)}`));
+    process.stdout.write(made.plist);
+    return;
+  }
+  // Idempotent: unload a previous copy, rewrite the plist, load it fresh.
+  if (launchd.print(DAEMON_LABEL).loaded) launchd.bootout(DAEMON_LABEL);
+  mkdirSync(LOG_DIR, { recursive: true });
+  mkdirSync(dirname(PLIST_PATH), { recursive: true });
+  writeFileSync(PLIST_PATH, made.plist);
+  try {
+    launchd.bootstrap(PLIST_PATH);
+  } catch (e) {
+    return fail(`Wrote ${tilde(PLIST_PATH)} but couldn't load it: ${(e as Error).message}`);
+  }
+  console.log(c.green(`✓ sportsing daemon installed and started (${DAEMON_LABEL}).`));
+  console.log(c.dim(`  runs: ${made.program.join(" ")}`));
+  console.log(c.dim(`  log:  ${tilde(LOG_FILE)}`));
+  console.log(c.dim("  check it with: sportsing daemon status"));
+}
+
+export function uninstall(launchd: Launchd): void {
+  const loaded = launchd.print(DAEMON_LABEL).loaded;
+  if (loaded) {
+    try {
+      launchd.bootout(DAEMON_LABEL);
+    } catch (e) {
+      return fail(`Couldn't stop the daemon: ${(e as Error).message}`);
+    }
+  }
+  const had = existsSync(PLIST_PATH);
+  rmSync(PLIST_PATH, { force: true });
+  console.log(loaded || had ? c.green("✓ sportsing daemon stopped and removed.") : c.dim("sportsing daemon wasn't installed — nothing to do."));
+}
+
+// ── status ───────────────────────────────────────────────────────────────────
+
+const LEVEL_COLOR = { on: c.green, starting: c.yellow, stuck: c.red, down: c.red, off: c.yellow } as const;
+
+/** `daemon status` text, one fact per line. */
+export function statusLines(s: DaemonStatus, now: number): string[] {
+  const st = s.state && s.state.pid === s.pid ? s.state : null;
+  const head = `sportsing daemon: ${LEVEL_COLOR[s.level](c.bold(s.level))}`;
+  const row = (k: string, v: string) => `  ${c.dim(k.padEnd(11))} ${v}`;
+  const out = [head];
+  if (s.level === "off") {
+    out.push(row("installed", "no — install it with: sportsing daemon install"));
+    return out;
+  }
+  out.push(row("installed", s.installed ? tilde(PLIST_PATH) : "no plist (running in the foreground?)"));
+  if (s.pid === null) out.push(row("running", c.red("no") + c.dim(" — see: sportsing daemon logs")));
+  else {
+    const up = st ? ` · up ${fmtDuration(now - Date.parse(st.startedAt))} · v${st.version} · mode ${st.mode}` : "";
+    out.push(row("running", `pid ${s.pid}${up}`));
+  }
+  const last = s.state;
+  if (last?.heartbeat) {
+    const age = now - Date.parse(last.heartbeat);
+    const ago = `${new Date(last.heartbeat).toLocaleTimeString()} (${fmtDuration(age)} ago)`;
+    const stuck = s.level === "stuck" ? c.red(` — STUCK: no poll for over ${fmtDuration(staleAfterMs(last.pollMs))}`) : c.dim(` · polling every ${fmtDuration(last.pollMs)}`);
+    out.push(row("last poll", ago + stuck));
+  } else out.push(row("last poll", c.dim("none yet")));
+  if (last) {
+    const n = last.next;
+    out.push(row("next game", n ? `${n.icon} ${n.fixture} · ${whenLabel(n.start, now)} → ${n.where}` : c.dim("no favorite games coming up")));
+    const a = last.lastAction;
+    out.push(row("last acted", a ? `${a.icon} ${a.did} ${a.fixture} · ${whenLabel(a.at, now)}${a.detail ? c.dim(` (${a.detail})`) : ""}` : c.dim("nothing yet")));
+    for (const [sport, err] of Object.entries(last.errors)) out.push(row("warning", c.yellow(`${sport}: ${err}`)));
+  }
+  out.push(row("log", tilde(LOG_FILE)));
+  return out;
+}
+
+function status(args: string[], launchd: Launchd): void {
+  const now = Date.now();
+  const s = gatherStatus(launchd, now);
+  if (args.includes("--json")) console.log(JSON.stringify({ ...s, healthy: isHealthy(s) }, null, 2));
+  else for (const l of statusLines(s, now)) console.log(l);
+  if (!isHealthy(s)) process.exitCode = 1;
+}
+
+// ── logs ─────────────────────────────────────────────────────────────────────
+
+async function logs(args: string[]): Promise<void> {
+  if (!existsSync(LOG_FILE)) return fail(`No daemon log yet (${tilde(LOG_FILE)}).`, "It's created when the daemon first runs: sportsing daemon install");
+  const nIdx = args.indexOf("-n");
+  const n = nIdx >= 0 ? Number(args[nIdx + 1]) : 50;
+  const follow = args.includes("-f") || args.includes("--follow");
+  const cmd = ["tail", "-n", String(Number.isInteger(n) && n > 0 ? n : 50), ...(follow ? ["-f"] : []), LOG_FILE];
+  const proc = Bun.spawn(cmd, { stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+  process.exitCode = await proc.exited;
+}
+
+// ── mode ─────────────────────────────────────────────────────────────────────
+
+async function mode(args: string[]): Promise<void> {
+  if (args.length === 0) {
+    console.log(`daemon mode: ${c.bold(await getDaemonMode())}  ${c.dim("(open = open the game window · notify = notification, click to watch)")}`);
+    return;
+  }
+  const m = parseDaemonMode(args[0]);
+  if (!m) return fail(`Unknown mode "${args[0]}". Use one of: ${DAEMON_MODES.join(", ")}.`);
+  await setDaemonMode(m);
+  console.log(c.green(`✓ daemon mode: ${m}`) + c.dim(" — takes effect from the next game start."));
+}
+
+// ── run ──────────────────────────────────────────────────────────────────────
+
+function log(msg: string): void {
+  console.log(`${new Date().toISOString()}  ${msg}`);
+}
+
+/** Every sport's favorite games; a sport that fails is recorded and skipped. */
+async function collect(sports: Sport[]): Promise<{ games: DaemonGame[]; errors: Record<string, string> }> {
+  const settled = await Promise.allSettled(sports.map((s) => s.daemonGames()));
+  const games: DaemonGame[] = [];
+  const errors: Record<string, string> = {};
+  settled.forEach((r, i) => {
+    if (r.status === "fulfilled") games.push(...(r.value ?? []));
+    else errors[sports[i]!.label] = r.reason instanceof Error ? r.reason.message : String(r.reason);
+  });
+  return { games, errors };
+}
+
+/** Run `args` as a detached sportsing child (its own process group, so it
+ *  outlives a daemon restart), output into the daemon's log. */
+function spawnDetached(exe: string[], args: string[]): void {
+  const child = spawn(exe[0]!, [...exe.slice(1), ...args], { detached: true, stdio: ["ignore", "inherit", "inherit"] });
+  child.on("error", (e) => log(`couldn't start ${args.join(" ")}: ${e.message}`));
+  child.unref();
+}
+
+/** Act on one game start. */
+function act(g: DaemonGame, mode: DaemonMode, exe: string[], dry: boolean): LastAction {
+  const base = { at: new Date().toISOString(), key: g.key, icon: g.icon, fixture: g.fixture };
+  const click = `${exe.map(shQuote).join(" ")} ${g.clickArgs.map(shQuote).join(" ")}`;
+  const title = `${g.icon} ${g.fixture} is under way`;
+  if (g.route.kind === "open" && mode === "open") {
+    if (dry) return { ...base, did: "dry-run", detail: `would open: ${g.openArgs.join(" ")}` };
+    spawnDetached(exe, g.openArgs);
+    notify(title, `Opening — ${g.route.note}`, { group: `sportsing-daemon-${g.key}` });
+    return { ...base, did: "opened", detail: g.route.note };
+  }
+  const body = g.route.kind === "open" ? `Click to watch — ${g.route.note}` : g.route.kind === "tune" ? `📺 ${g.route.message}` : `✗ ${g.route.message}`;
+  if (dry) return { ...base, did: "dry-run", detail: `would notify: ${body}` };
+  notify(title, body, { group: `sportsing-daemon-${g.key}`, onClick: g.route.kind === "open" ? inTerminal(click) : undefined });
+  return { ...base, did: "notified", detail: body };
+}
+
+/**
+ * The poll loop. Each poll: fetch every sport's favorite games, act on any
+ * live one not acted on before (recorded in the state file *before* acting,
+ * so a crash or restart never double-opens), record the heartbeat and next
+ * game, then sleep — sparse when nothing's near, tight around a start.
+ */
+export async function run(args: string[], version: string, sports: Sport[] = SPORTS): Promise<void> {
+  const once = args.includes("--once");
+  const dry = args.includes("--dry-run");
+  const exe = selfInvocation();
+  const prev = readState();
+  const state: DaemonState = {
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    version,
+    mode: await getDaemonMode(),
+    heartbeat: null,
+    pollMs: 0,
+    next: null,
+    lastAction: prev?.lastAction ?? null,
+    acted: prev?.acted ?? {},
+    errors: {},
+  };
+  const save = () => {
+    if (!dry) writeState(state);
+  };
+  log(`sportsing daemon ${version} started (pid ${process.pid}${dry ? ", dry run" : ""}; state ${tilde(STATE_FILE)})`);
+  save();
+
+  let stop = false;
+  let wake: (() => void) | null = null;
+  for (const sig of ["SIGINT", "SIGTERM"] as const) {
+    process.on(sig, () => {
+      log(`${sig} — stopping`);
+      stop = true;
+      wake?.();
+    });
+  }
+
+  while (!stop) {
+    state.mode = await getDaemonMode().catch(() => state.mode);
+    const { games, errors } = await collect(sports);
+    const now = Date.now();
+    state.errors = errors;
+    for (const [sport, err] of Object.entries(errors)) log(`${sport}: ${err}`);
+
+    state.acted = pruneActed(state.acted, now);
+    for (const g of startsToAct(games, state.acted)) {
+      state.acted[g.key] = new Date(now).toISOString();
+      save(); // persist the dedupe before acting
+      try {
+        state.lastAction = act(g, state.mode, exe, dry);
+      } catch (e) {
+        state.lastAction = { at: new Date().toISOString(), key: g.key, icon: g.icon, fixture: g.fixture, did: "failed", detail: (e as Error).message };
+      }
+      log(`${state.lastAction.did} ${g.fixture} — ${state.lastAction.detail}`);
+    }
+
+    const n = nextUp(games, now);
+    state.next = n && { key: n.key, icon: n.icon, fixture: n.fixture, start: n.start, where: routeWhere(n.route, state.mode) };
+    state.pollMs = pollDelayMs(games, now);
+    state.heartbeat = new Date(now).toISOString();
+    save();
+    const waiting = n ? `next ${n.fixture} ${new Date(n.start).toLocaleString()} (${state.next!.where})` : "no favorite games coming up";
+    log(`poll: ${games.length} favorite game(s); ${waiting}; next poll in ${fmtDuration(state.pollMs)}`);
+    if (once) break;
+    await new Promise<void>((r) => {
+      const t = setTimeout(r, state.pollMs);
+      wake = () => {
+        clearTimeout(t);
+        r();
+      };
+    });
+  }
+}
+
+// ── dispatch ─────────────────────────────────────────────────────────────────
+
+export async function daemon(args: string[], version: string, launchd: Launchd = systemLaunchd()): Promise<void> {
+  const [sub, ...rest] = args;
+  switch (sub) {
+    case "install":
+      return install(rest, launchd);
+    case "uninstall":
+      return uninstall(launchd);
+    case "status":
+      return status(rest, launchd);
+    case "logs":
+    case "log":
+      return logs(rest);
+    case "mode":
+      return mode(rest);
+    case "run":
+      return run(rest, version);
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      return usage();
+    default:
+      usage();
+      return fail(`Unknown daemon command: ${sub}`);
+  }
+}

package/src/commands/league.ts

@@ -36,6 +36,7 @@ import { LIVE_REFRESH_MS, raise, type Alert, type Alerter } from "../alerts.ts";
 import { selfInvocation } from "../click-to-watch.ts";
 import { isGameSport } from "../game-events.ts";
 import { leagueFeed } from "../league-alerts.ts";
+import { leagueDaemonGame, leagueRoute, type DaemonGame } from "../daemon.ts";
 
 export interface LeagueConfig {
   /** CLI namespace and favorites key, e.g. "nba" (`sportsing nba …`, `nba:UTAH`). */
@@ -552,7 +553,7 @@ function pickOrReport(key: string, sport: string): { key: string; label: string;
 }
 
 /**
- * `watch [team] [--wait] [--overlay] [--provider X] [--url L] [--size WxH] [--smoke]` —
+ * `watch [team] [--wait] [--overlay] [--provider X] [--url L] [--size WxH] [--smoke] [--supervised]` —
  * open the game's stream in that provider's persistent Chrome profile, so an
  * existing login is reused. No team = your favorites.
  *
@@ -566,7 +567,8 @@ function pickOrReport(key: string, sport: string): { key: string; label: string;
  *
  * `--wait` blocks until the next game is live, then opens it. `--smoke` opens
  * the window, confirms it came up over CDP, and tears it down (bounded; for
- * scripts and agents).
+ * scripts and agents). `--supervised` lets it run with no TTY on purpose (the
+ * daemon opens a game this way; the window's close ends it).
  * `--overlay` adds the live-stats overlay, which follows the game you open.
  */
 async function watch(cfg: LeagueConfig, args: string[]): Promise<void> {
@@ -609,8 +611,10 @@ async function watch(cfg: LeagueConfig, args: string[]): Promise<void> {
     const target = url ?? pick.hub;
     return overlay ? smokeLeagueOverlay(cfg, target, pick.label, windowSize) : smokeWatch(target, pick.label, windowSize);
   }
-  // watch blocks until the window is closed; with no TTY nothing ever closes it.
-  if (process.stdin.isTTY !== true) {
+  // watch blocks until the window is closed; with no TTY nothing ever closes it
+  // — unless `--supervised`: the daemon deliberately runs it detached, with no
+  // TTY, to open a game window that the user closes.
+  if (process.stdin.isTTY !== true && !args.includes("--supervised")) {
     console.error(c.yellow("`watch` is interactive — it opens a stream window and blocks until you close it."));
     console.error(c.dim(`Run it in a terminal, or use \`sportsing ${cfg.sport} watch --smoke\` to just confirm the window opens.`));
     process.exitCode = 1;
@@ -619,7 +623,7 @@ async function watch(cfg: LeagueConfig, args: string[]): Promise<void> {
 
   if (scope === undefined) scope = await watchScope(cfg, args);
   if (!scope) {
-    console.error(c.red(`Usage: sportsing ${cfg.sport} watch <team> [--wait] [--overlay] [--provider ${pick.key}] [--url <link>] [--smoke]`));
+    console.error(c.red(`Usage: sportsing ${cfg.sport} watch <team> [--wait] [--overlay] [--provider ${pick.key}] [--url <link>] [--smoke] [--supervised]`));
     console.error(c.dim(`Or add a favorite (sportsing ${cfg.sport} fav add ${EXAMPLE_TEAM[cfg.sport] ?? "<team>"}) and omit the team.`));
     process.exitCode = 1;
     return;
@@ -673,6 +677,30 @@ export async function leagueAlerter(cfg: LeagueConfig): Promise<Alerter | null>
   return { label: cfg.label, teams: alerts.teams, poll: async () => alerts.feed(await liveGames(cfg)) };
 }
 
+/**
+ * The league's favorite games for `sportsing daemon`: live and nearby ones
+ * from the scoreboards (local yesterday → tomorrow), each routed the way
+ * `watch` would. When none of those is upcoming, the favorites' next scheduled
+ * game is added from their season schedules (5-min cache) so status can say
+ * what it's waiting for. Null with no (resolvable) favorites.
+ */
+export async function leagueDaemonGames(cfg: LeagueConfig): Promise<DaemonGame[] | null> {
+  const favs = await getFavorites(cfg.sport);
+  if (favs.length === 0) return null;
+  const ids = favoriteIds(cfg, await getTeams(cfg.league), favs);
+  if (ids.size === 0) return null;
+  const [all, watch, fallback] = await Promise.all([liveGames(cfg), watchContext(cfg), watchFallback(cfg)]);
+  const nearby = all.filter((g) => gameHasTeam(g, ids));
+  const now = Date.now();
+  let later: Game | null = null;
+  if (!nearby.some((g) => g.state === "pre" && Date.parse(g.date) >= now)) {
+    later = firstUpcoming(await scopedSeasons(cfg, ids), now);
+    if (later && nearby.some((g) => g.id === later!.id)) later = null;
+  }
+  const games = later ? [...nearby, later] : nearby;
+  return games.map((g) => leagueDaemonGame(cfg.sport, cfg.icon, g, ids, leagueRoute(g, watch, fallback)));
+}
+
 /** Full-screen live board: in play, later today, finished today. */
 function renderLiveBoard(cfg: LeagueConfig, games: Game[]): void {
   const { live, upcoming, done } = liveBoard(games, ymd(new Date()));