sportsing 0.2.1 → 0.3.0

package/README.md

@@ -97,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 |
@@ -174,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.
 
@@ -182,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
@@ -312,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.1",
+  "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()));

package/src/commands/live.ts

@@ -2,11 +2,13 @@ import { c } from "../ansi.ts";
 import { getMatches, NoKeyError } from "../api.ts";
 import { matchLine, fmtTimeOnly, stageLabel } from "../format.ts";
 import { ymd, addDays, localDateOf, sortByDate } from "./_lib.ts";
-import { getApiKey, getFavorites } from "../config.ts";
+import { getApiKey, getFavorites, getStreamProvider } from "../config.ts";
+import type { DaemonGame } from "../daemon.ts";
+
 import { diffEvents, type MatchEvent } from "../events.ts";
 import { LIVE_REFRESH_MS, raise, type Alert, type Alerter } from "../alerts.ts";
 import { inTerminal, selfInvocation, watchCommand } from "../click-to-watch.ts";
-import { matchHasTeam } from "../match-util.ts";
+import { matchHasTeam, matchState } from "../match-util.ts";
 import type { Match } from "../types.ts";
 
 export async function live(args: string[] = []) {
@@ -153,6 +155,34 @@ export async function fifaAlerter(): Promise<Alerter | null> {
   return { label: "FIFA", teams: favorites, poll: async () => feed(await matchesToday()) };
 }
 
+/** FIFA's favorite matches today for `sportsing daemon`; null with no FIFA
+ *  favorites. Always routed "open" via the configured provider, exactly like
+ *  `fifa watch <fav> --wait` — FIFA has no subscriptions/watchability resolver
+ *  (that's NBA/NHL only), so there's no over-the-air or unwatchable branch. */
+export async function fifaDaemonGames(): Promise<DaemonGame[] | null> {
+  const favorites = await getFavorites("fifa");
+  if (favorites.length === 0) return null;
+  if (!(await getApiKey())) throw new Error("needs an API key — run `sportsing fifa setup`");
+  const provider = (await getStreamProvider("fifa")) ?? "fubo";
+  return (await matchesToday()).flatMap((m): DaemonGame[] => {
+    const fav = favorites.find((f) => matchHasTeam(m, f.trim().toLowerCase()))?.trim();
+    if (!fav) return [];
+    return [
+      {
+        key: `fifa:${m.id}`,
+        sport: "fifa",
+        icon: "⚽",
+        fixture: `${m.homeTeam.tla ?? m.homeTeam.name} v ${m.awayTeam.tla ?? m.awayTeam.name}`,
+        start: m.utcDate,
+        state: matchState(m),
+        openArgs: ["fifa", "watch", fav, "--wait", "--supervised"],
+        clickArgs: ["fifa", "watch", fav],
+        route: { kind: "open", note: provider },
+      },
+    ];
+  });
+}
+
 /**
  * The click-to-watch command for a kickoff event, or undefined when none applies.
  * Returns `<exe…> fifa watch <fav>` (shell-quoted) where `fav` is the favourite

package/src/commands/upgrade.ts

@@ -1,5 +1,6 @@
 import { existsSync, realpathSync } from "fs";
 import { c } from "../ansi.ts";
+import { restartDaemonIfLoaded, systemLaunchd, type Launchd } from "../daemon-io.ts";
 import {
   REGISTRY_LATEST_URL,
   canSelfUpgrade,
@@ -42,7 +43,7 @@ async function fetchLatest(): Promise<string> {
 }
 
 /** Realpath of the running entry script, so npm/bun bin symlinks resolve to the package. */
-function runningScript(): string {
+export function runningScript(): string {
   try {
     return realpathSync(Bun.main);
   } catch {
@@ -63,7 +64,7 @@ function installedVersion(bin: string): string | null {
 }
 
 // `sportsing upgrade [--check]` — self-update to the latest npm release.
-export async function upgrade(args: string[], current: string): Promise<void> {
+export async function upgrade(args: string[], current: string, launchd: Launchd = systemLaunchd()): Promise<void> {
   if (args.includes("--help") || args.includes("-h") || args[0] === "help") return usage();
   const unknown = args.filter((a) => a !== "--check");
   if (unknown.length) {
@@ -134,4 +135,9 @@ export async function upgrade(args: string[], current: string): Promise<void> {
     return fail(`Install finished, but ${bin} still reports ${now}. Check which sportsing is on your PATH.`);
   }
   console.log(c.green(`✓ sportsing ${current} → ${now}`));
+
+  // A loaded daemon is still running the old code: restart it onto the new.
+  const restart = restartDaemonIfLoaded(launchd);
+  if (restart === "restarted") console.log(c.green("✓ restarted sportsing daemon on the new version"));
+  else if (restart !== "not-loaded") console.error(c.yellow(`Couldn't restart the daemon (${restart.error}) — run: sportsing daemon install`));
 }

package/src/config.ts

@@ -1,6 +1,7 @@
 import { homedir } from "os";
 import { join } from "path";
 import { mkdir, chmod } from "fs/promises";
+import { daemonModeOf, type DaemonMode } from "./daemon.ts";
 import { SUBSCRIPTIONS, HOME_MARKETS, DEFAULT_HOME_MARKET, isSubscription, type Subscription } from "./watchability.ts";
 
 const CONFIG_DIR = join(homedir(), ".config", "sportsing");
@@ -32,6 +33,8 @@ interface Config {
   subscriptions?: string[];
   /** HOME_MARKETS id for blackouts / local channels; defaults to Utah. */
   homeMarket?: string;
+  /** `sportsing daemon` settings. */
+  daemon?: { mode?: string };
 }
 
 /** Default overlay panel visibility — nothing on by default, so a fresh stream
@@ -279,4 +282,17 @@ export async function setHomeMarket(market: string): Promise<void> {
   await writeConfig(cfg);
 }
 
+// ── Daemon ───────────────────────────────────────────────────────────────────
+
+/** What the daemon does when a favorite's game starts (`open` by default). */
+export async function getDaemonMode(): Promise<DaemonMode> {
+  return daemonModeOf((await readConfig()).daemon?.mode);
+}
+
+export async function setDaemonMode(mode: DaemonMode): Promise<void> {
+  const cfg = await readConfig();
+  cfg.daemon = { ...(cfg.daemon ?? {}), mode };
+  await writeConfig(cfg);
+}
+
 export { CONFIG_FILE };

package/src/daemon-io.ts

@@ -0,0 +1,114 @@
+// The daemon's IO edge: where its files live, its state file (written
+// atomically), and launchd. Kept apart from src/commands/daemon.ts so the
+// bare today/next/me footer and `sportsing upgrade` can use it without pulling
+// in the sport registry. launchctl is behind the `Launchd` interface so tests
+// and smokes use fakes — nothing in the test suite ever talks to launchd.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import { CACHE_DIR } from "./config.ts";
+import {
+  DAEMON_LABEL,
+  evaluateStatus,
+  footerLine,
+  parseDaemonState,
+  parseLaunchctlPrint,
+  type DaemonState,
+  type DaemonStatus,
+  type ServiceInfo,
+} from "./daemon.ts";
+import { pidAlive } from "./liveness.ts";
+
+export const PLIST_PATH = join(homedir(), "Library", "LaunchAgents", `${DAEMON_LABEL}.plist`);
+export const LOG_DIR = join(homedir(), "Library", "Logs", "sportsing");
+export const LOG_FILE = join(LOG_DIR, "daemon.log");
+export const STATE_FILE = join(CACHE_DIR, "daemon-state.json");
+
+/** The daemon's state file, or null if absent/malformed. */
+export function readState(file = STATE_FILE): DaemonState | null {
+  try {
+    return parseDaemonState(JSON.parse(readFileSync(file, "utf8")));
+  } catch {
+    return null;
+  }
+}
+
+/** Write the state file atomically (temp file + rename), so a reader never
+ *  sees a half-written file and a crash mid-write leaves the old one. */
+export function writeState(s: DaemonState, file = STATE_FILE): void {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(s, null, 2) + "\n");
+  renameSync(tmp, file);
+}
+
+/** launchctl, injectable. All calls target the `gui/<uid>` domain. */
+export interface Launchd {
+  /** The job's launchd info, or `{ loaded: false }` when it isn't loaded. */
+  print(label: string): ServiceInfo;
+  /** Load and start a plist. Throws on failure. */
+  bootstrap(plistPath: string): void;
+  /** Unload a job. Throws on failure. */
+  bootout(label: string): void;
+  /** Kill and restart a loaded job. Throws on failure. */
+  kickstart(label: string): void;
+}
+
+function launchctl(args: string[]): { code: number; out: string } {
+  const r = Bun.spawnSync(["launchctl", ...args], { stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+  return { code: r.exitCode ?? 1, out: r.stdout.toString() + r.stderr.toString() };
+}
+
+function must(args: string[]): void {
+  const r = launchctl(args);
+  if (r.code !== 0) throw new Error(`launchctl ${args.join(" ")} failed (${r.code}): ${r.out.trim()}`);
+}
+
+/** The real launchctl. */
+export function systemLaunchd(uid = process.getuid?.() ?? 501): Launchd {
+  const domain = `gui/${uid}`;
+  return {
+    print(label) {
+      const r = launchctl(["print", `${domain}/${label}`]);
+      return r.code === 0 ? parseLaunchctlPrint(r.out) : { loaded: false };
+    },
+    bootstrap: (plistPath) => must(["bootstrap", domain, plistPath]),
+    bootout: (label) => must(["bootout", `${domain}/${label}`]),
+    kickstart: (label) => must(["kickstart", "-k", `${domain}/${label}`]),
+  };
+}
+
+/** The daemon's status. With `launchd`, it's the authority on whether the job
+ *  runs; without it (the cheap footer) the state file's pid is probed. */
+export function gatherStatus(launchd: Launchd | null, now = Date.now()): DaemonStatus {
+  const state = readState();
+  const installed = existsSync(PLIST_PATH);
+  let service: ServiceInfo;
+  if (launchd) service = launchd.print(DAEMON_LABEL);
+  else service = state && pidAlive(state.pid) ? { loaded: true, pid: state.pid } : { loaded: false };
+  return evaluateStatus({ installed, service, state, now });
+}
+
+/** The one-line footer for bare today / next / me. Never throws. */
+export function daemonFooter(): string | null {
+  try {
+    return footerLine(gatherStatus(null), Date.now());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * After `sportsing upgrade`: restart a loaded daemon so it runs the new code.
+ * Returns what happened, for the upgrade's output.
+ */
+export function restartDaemonIfLoaded(launchd: Launchd): "restarted" | "not-loaded" | { error: string } {
+  if (!launchd.print(DAEMON_LABEL).loaded) return "not-loaded";
+  try {
+    launchd.kickstart(DAEMON_LABEL);
+    return "restarted";
+  } catch (e) {
+    return { error: e instanceof Error ? e.message : String(e) };
+  }
+}

package/src/daemon.ts

@@ -0,0 +1,409 @@
+// The always-on `sportsing daemon`: a per-user launchd agent that polls every
+// sport with a favorite and, when a favorite's game starts, opens it the way
+// `<sport> watch` would (or notifies, per `daemon.mode`). Everything here is
+// pure — start detection, dedupe, poll cadence, the launchd plist, the
+// `launchctl print` parse, and the status/staleness verdict — so it's
+// unit-tested without launchd, the real config, or the network. The command
+// (src/commands/daemon.ts) does the IO.
+
+import type { Game, GameState } from "./game.ts";
+import type { InstallMethod } from "./upgrade.ts";
+import { planWatch, watchOf, type WatchContext } from "./watch-route.ts";
+
+/** launchd label, plist basename, and `launchctl … gui/<uid>/<label>` target. */
+export const DAEMON_LABEL = "com.sportsing.daemon";
+
+export const DAEMON_MODES = ["open", "notify"] as const;
+export type DaemonMode = (typeof DAEMON_MODES)[number];
+export const DEFAULT_DAEMON_MODE: DaemonMode = "open";
+
+/** A stored/typed mode, or null when it isn't one. */
+export function parseDaemonMode(v: unknown): DaemonMode | null {
+  const s = typeof v === "string" ? v.trim().toLowerCase() : "";
+  return (DAEMON_MODES as readonly string[]).includes(s) ? (s as DaemonMode) : null;
+}
+
+/** Stored mode, defaulting to `open` for unset/unknown values. */
+export function daemonModeOf(stored: unknown): DaemonMode {
+  return parseDaemonMode(stored) ?? DEFAULT_DAEMON_MODE;
+}
+
+// ── Games ────────────────────────────────────────────────────────────────────
+
+/** What a game start does, as `<sport> watch` would decide it. */
+export type Route =
+  /** A stream to open; `note` says which service and why. */
+  | { kind: "open"; note: string }
+  /** Over the air only — nothing to open; `message` names the channel. */
+  | { kind: "tune"; message: string }
+  /** Can't be watched (or placed); `message` says why. */
+  | { kind: "none"; message: string };
+
+/** One favorite-team game as the daemon sees it, sport-neutral. */
+export interface DaemonGame {
+  /** `<sport>:<game id>` — the dedupe key. */
+  key: string;
+  sport: string;
+  icon: string;
+  /** "DEN @ UTAH" (away @ home). */
+  fixture: string;
+  /** ISO scheduled start. */
+  start: string;
+  state: GameState;
+  /** argv (after the sportsing executable) that opens it with no TTY. */
+  openArgs: string[];
+  /** argv for an interactive `watch` (click-to-watch, in a Terminal window). */
+  clickArgs: string[];
+  route: Route;
+}
+
+/**
+ * How an ESPN-league game start is routed — the same decision `<sport> watch`
+ * makes: with subscriptions, the watchability resolver (Fubo / League Pass
+ * open, over-the-air names the channel, unwatchable says why); without them,
+ * the configured / league-default provider, if any.
+ */
+export function leagueRoute(g: Game, watch: WatchContext | null, fallback: string | null): Route {
+  if (!watch) {
+    return fallback
+      ? { kind: "open", note: `${fallback} (no subscriptions set)` }
+      : { kind: "none", message: "no streaming provider — run `sportsing subscriptions set …`" };
+  }
+  const plan = planWatch(watchOf(g, watch), fallback);
+  return plan.kind === "open" ? { kind: "open", note: plan.note } : plan;
+}
+
+/** The daemon's view of an ESPN-league game; `favIds` picks the team `watch` follows. */
+export function leagueDaemonGame(
+  sport: string,
+  icon: string,
+  g: Game,
+  favIds: ReadonlySet<string>,
+  route: Route,
+): DaemonGame {
+  // Either favorite's id finds the same game; prefer home, as `watch` does.
+  const team = [g.home, g.away].find((t) => favIds.has(t.id))?.id ?? g.home.id;
+  return {
+    key: `${sport}:${g.id}`,
+    sport,
+    icon,
+    fixture: `${g.away.abbreviation} @ ${g.home.abbreviation}`,
+    start: g.date,
+    state: g.state,
+    openArgs: [sport, "watch", team, "--supervised"],
+    clickArgs: [sport, "watch", team],
+    route,
+  };
+}
+
+/** Short "where it'll open" text for status lines. */
+export function routeWhere(r: Route, mode: DaemonMode): string {
+  if (r.kind === "open") return mode === "open" ? `opens ${r.note}` : `notifies (click to open ${r.note})`;
+  if (r.kind === "tune") return `notifies: ${r.message}`;
+  return `notifies: ✗ ${r.message}`;
+}
+
+// ── Cadence ──────────────────────────────────────────────────────────────────
+
+/** Poll interval when no favorite game is close. */
+export const SPARSE_POLL_MS = 10 * 60_000;
+/** Poll interval from LEAD_MS before a scheduled start until it goes live. */
+export const TIGHT_POLL_MS = 30_000;
+/** How long before a scheduled start polling tightens. */
+export const LEAD_MS = 15 * 60_000;
+/** How long past its scheduled start a not-yet-live game is still awaited
+ *  (delayed starts, a lagging feed) — matches `watch`'s START_GRACE_MS. */
+export const START_GRACE_MS = 3 * 60 * 60_000;
+
+/** The not-yet-started game the daemon is waiting for: the earliest `pre`
+ *  game that's upcoming or still within START_GRACE_MS of its start. */
+export function nextUp(games: DaemonGame[], now: number): DaemonGame | null {
+  return (
+    games
+      .filter((g) => g.state === "pre" && Date.parse(g.start) >= now - START_GRACE_MS)
+      .sort((a, b) => Date.parse(a.start) - Date.parse(b.start))[0] ?? null
+  );
+}
+
+/**
+ * How long to sleep before the next poll: tight (30s) from LEAD_MS before the
+ * next game's scheduled start until it flips live — including past the start
+ * for a delayed one — else sparse, waking early enough to be tight by LEAD_MS.
+ */
+export function pollDelayMs(games: DaemonGame[], now: number): number {
+  const n = nextUp(games, now);
+  if (!n) return SPARSE_POLL_MS;
+  const untilLead = Date.parse(n.start) - LEAD_MS - now;
+  if (untilLead <= 0) return TIGHT_POLL_MS;
+  return Math.min(SPARSE_POLL_MS, Math.max(TIGHT_POLL_MS, untilLead));
+}
+
+// ── State ────────────────────────────────────────────────────────────────────
+
+export interface NextGame {
+  key: string;
+  icon: string;
+  fixture: string;
+  start: string;
+  /** routeWhere() text. */
+  where: string;
+}
+
+export interface LastAction {
+  at: string;
+  key: string;
+  icon: string;
+  fixture: string;
+  /** What was done: "opened", "notified", "dry-run", "failed". */
+  did: string;
+  detail: string;
+}
+
+/** The daemon's persisted state (heartbeat, dedupe set, what it's doing). */
+export interface DaemonState {
+  pid: number;
+  startedAt: string;
+  version: string;
+  mode: DaemonMode;
+  /** Last completed poll. */
+  heartbeat: string | null;
+  /** The sleep chosen after that poll. */
+  pollMs: number;
+  next: NextGame | null;
+  lastAction: LastAction | null;
+  /** Game key → when it was acted on. A game is acted on at most once. */
+  acted: Record<string, string>;
+  /** Sport label → error from the last poll (that sport was skipped). */
+  errors: Record<string, string>;
+}
+
+/** How long acted-on keys are remembered (well past any game's length). */
+export const ACTED_TTL_MS = 7 * 24 * 60 * 60_000;
+
+/** Acted-on keys younger than ACTED_TTL_MS. */
+export function pruneActed(acted: Record<string, string>, now: number): Record<string, string> {
+  return Object.fromEntries(Object.entries(acted).filter(([, at]) => now - Date.parse(at) < ACTED_TTL_MS));
+}
+
+/** Live favorite games not yet acted on — what this poll should open. */
+export function startsToAct(games: DaemonGame[], acted: Record<string, string>): DaemonGame[] {
+  const seen = new Set<string>();
+  return games.filter((g) => {
+    if (g.state !== "in" || Object.hasOwn(acted, g.key) || seen.has(g.key)) return false;
+    seen.add(g.key);
+    return true;
+  });
+}
+
+/** Parse a state file's JSON; null for anything malformed. */
+export function parseDaemonState(raw: unknown): DaemonState | null {
+  const s = raw as Partial<DaemonState> | null;
+  if (!s || typeof s !== "object" || typeof s.pid !== "number" || typeof s.startedAt !== "string") return null;
+  return {
+    pid: s.pid,
+    startedAt: s.startedAt,
+    version: typeof s.version === "string" ? s.version : "?",
+    mode: daemonModeOf(s.mode),
+    heartbeat: typeof s.heartbeat === "string" ? s.heartbeat : null,
+    pollMs: typeof s.pollMs === "number" && s.pollMs > 0 ? s.pollMs : SPARSE_POLL_MS,
+    next: s.next ?? null,
+    lastAction: s.lastAction ?? null,
+    acted: s.acted && typeof s.acted === "object" ? s.acted : {},
+    errors: s.errors && typeof s.errors === "object" ? s.errors : {},
+  };
+}
+
+// ── Status ───────────────────────────────────────────────────────────────────
+
+/** A heartbeat older than this means the loop is wedged: ~3 poll intervals,
+ *  never under 3 minutes (a tight-poll fetch can legitimately take a while). */
+export function staleAfterMs(pollMs: number): number {
+  return Math.max(3 * pollMs, 3 * 60_000);
+}
+
+export interface ServiceInfo {
+  /** launchd has the job loaded. */
+  loaded: boolean;
+  /** Its running process, if any. */
+  pid?: number;
+}
+
+export type DaemonLevel =
+  /** Not installed (no plist, nothing loaded). */
+  | "off"
+  /** Installed, but no process is running it. */
+  | "down"
+  /** Running, but it hasn't completed a poll yet. */
+  | "starting"
+  /** Running, heartbeat stale. */
+  | "stuck"
+  /** Running and polling. */
+  | "on";
+
+export interface DaemonStatus {
+  level: DaemonLevel;
+  installed: boolean;
+  pid: number | null;
+  state: DaemonState | null;
+  /** ms since the last heartbeat, when there is one. */
+  heartbeatAgeMs: number | null;
+}
+
+/**
+ * The daemon's health. `service` comes from launchd (`daemon status`) or, for
+ * the cheap footer, from probing the state file's pid. The state only counts
+ * when it belongs to the running process.
+ */
+export function evaluateStatus(o: { installed: boolean; service: ServiceInfo; state: DaemonState | null; now: number }): DaemonStatus {
+  const pid = o.service.pid ?? null;
+  const base = { installed: o.installed, pid, state: o.state, heartbeatAgeMs: null as number | null };
+  if (!o.installed && !o.service.loaded) return { ...base, level: "off" };
+  if (pid === null) return { ...base, level: "down" };
+  const mine = o.state && o.state.pid === pid ? o.state : null;
+  if (!mine?.heartbeat) {
+    const since = mine ? o.now - Date.parse(mine.startedAt) : 0;
+    return { ...base, level: since > staleAfterMs(TIGHT_POLL_MS) ? "stuck" : "starting" };
+  }
+  const age = o.now - Date.parse(mine.heartbeat);
+  return { ...base, heartbeatAgeMs: age, level: age > staleAfterMs(mine.pollMs) ? "stuck" : "on" };
+}
+
+/** `daemon status` exits 0 only for this. */
+export function isHealthy(s: DaemonStatus): boolean {
+  return s.level === "on";
+}
+
+/** "7:00 PM" today, else "Sat 7:00 PM" (local time). */
+export function whenLabel(iso: string, now: number): string {
+  const d = new Date(iso);
+  const time = d.toLocaleString(undefined, { hour: "numeric", minute: "2-digit" });
+  if (d.toDateString() === new Date(now).toDateString()) return time;
+  return `${d.toLocaleString(undefined, { weekday: "short" })} ${time}`;
+}
+
+/** "45s", "12m", "3h 5m", "2d 4h". */
+export function fmtDuration(ms: number): string {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return m % 60 ? `${h}h ${m % 60}m` : `${h}h`;
+  const d = Math.floor(h / 24);
+  return h % 24 ? `${d}d ${h % 24}h` : `${d}d`;
+}
+
+/** The one-line footer under bare today / next / me. */
+export function footerLine(s: DaemonStatus, now: number): string {
+  switch (s.level) {
+    case "off":
+      return "daemon: off — sportsing daemon install";
+    case "down":
+      return "daemon: down — installed but not running (sportsing daemon status)";
+    case "starting":
+      return "daemon: starting — sportsing daemon status";
+    case "stuck": {
+      const age = s.heartbeatAgeMs === null ? "no poll yet" : `last poll ${fmtDuration(s.heartbeatAgeMs)} ago`;
+      return `daemon: stuck — ${age} (sportsing daemon logs)`;
+    }
+    case "on": {
+      const n = s.state?.next;
+      return n ? `daemon: on — waiting for ${n.fixture} ${whenLabel(n.start, now)}` : "daemon: on — no favorite games coming up";
+    }
+  }
+}
+
+/** Pull `state` and `pid` out of `launchctl print gui/<uid>/<label>`. */
+export function parseLaunchctlPrint(out: string): ServiceInfo & { state?: string } {
+  const state = out.match(/^\s*state = (.+)$/m)?.[1]?.trim();
+  const pidStr = out.match(/^\s*pid = (\d+)/m)?.[1];
+  const pid = pidStr ? Number(pidStr) : undefined;
+  return { loaded: true, ...(state ? { state } : {}), ...(pid && state === "running" ? { pid } : {}) };
+}
+
+// ── launchd agent ────────────────────────────────────────────────────────────
+
+/**
+ * ProgramArguments for `sportsing daemon run`, pinned to the stable paths of
+ * how this copy was installed — so the agent keeps working across
+ * `sportsing upgrade` (which reinstalls into the same prefix). The bin is a
+ * Bun script, so it's run by an absolute Bun (launchd's PATH has no Bun):
+ * the bun-global install's own, else the `bun` on the installing shell's PATH
+ * (a stable shim like ~/.bun/bin/bun), else the running one. Null for
+ * installs with no stable path (npx/bunx caches, unrecognised).
+ */
+export function daemonProgram(
+  m: InstallMethod,
+  o: { execPath: string; bunOnPath: string | null; exists: (p: string) => boolean },
+): string[] | null {
+  const bun = o.bunOnPath ?? o.execPath;
+  const run = ["daemon", "run"];
+  switch (m.kind) {
+    case "npm-global":
+      return [bun, `${m.prefix}/bin/sportsing`, ...run];
+    case "bun-global": {
+      const own = `${m.bunInstall}/bin/bun`;
+      return [o.exists(own) ? own : bun, `${m.bunInstall}/bin/sportsing`, ...run];
+    }
+    case "source":
+      return [bun, `${m.root}/src/index.ts`, ...run];
+    case "compiled":
+      return [o.execPath, ...run];
+    default:
+      return null;
+  }
+}
+
+/** PATH for the agent: the installing shell's PATH (so terminal-notifier,
+ *  osascript and Chrome resolve as they do for you), plus the system dirs,
+ *  de-duplicated in order. */
+export function agentPath(shellPath: string | undefined, extra: string[] = []): string {
+  const sys = ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"];
+  const parts = [...extra, ...(shellPath ?? "").split(":"), ...sys].filter(Boolean);
+  return [...new Set(parts)].join(":");
+}
+
+function xml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+/**
+ * The LaunchAgent plist: run at login, restart if it exits (throttled), log
+ * stdout+stderr to `logPath`. AbandonProcessGroup keeps a game window the
+ * daemon opened alive across a daemon restart (e.g. after an upgrade).
+ */
+export function launchAgentPlist(o: { label: string; program: string[]; logPath: string; path: string; home: string }): string {
+  const args = o.program.map((a) => `    <string>${xml(a)}</string>`).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xml(o.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+  <key>AbandonProcessGroup</key>
+  <true/>
+  <key>WorkingDirectory</key>
+  <string>${xml(o.home)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xml(o.path)}</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${xml(o.logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(o.logPath)}</string>
+</dict>
+</plist>
+`;
+}

package/src/index.ts

@@ -4,6 +4,7 @@ import { ApiError } from "./api.ts";
 import { SPORTS as REGISTRY, bare } from "./commands/cross.ts";
 import { subscriptions } from "./commands/subscriptions.ts";
 import { upgrade } from "./commands/upgrade.ts";
+import { daemon } from "./commands/daemon.ts";
 import pkg from "../package.json" with { type: "json" };
 
 // Single source of truth: package.json (a hardcoded copy drifted to a stale
@@ -40,6 +41,7 @@ ${b("YOUR TEAMS")} ${c.dim("(favorites across every sport, each row tagged with
 ${b("SETTINGS")}
   ${c.green("subscriptions")}      What you can watch with + home market ${c.dim("— alias: subs")}
   ${c.green("upgrade")}            Install the latest release ${c.dim("(--check: just compare versions)")}
+  ${c.green("daemon")}             Always-on watcher that opens your teams' games ${c.dim("(install · status · logs · mode · uninstall)")}
 
 ${b("EXAMPLES")}
   sportsing fifa today
@@ -75,6 +77,10 @@ async function dispatch(): Promise<void> {
     await upgrade(rest, VERSION);
     return;
   }
+  if (first === "daemon") {
+    await daemon(rest, VERSION);
+    return;
+  }
 
   // Bare `today`/`next`/`me`/`live` run across every sport; anything else gets a hint.
   await bare(first, rest);

package/src/match-util.ts

@@ -3,8 +3,16 @@
 // like events.ts can share one source of truth without events.ts taking a
 // dependency on the I/O-bearing command layer.
 
+import type { GameState } from "./game.ts";
 import type { Match } from "./types.ts";
 
+/** 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";
+}
+
 /** True if either side of the match matches `needle` (lowercased) by name/tla/shortName. */
 export function matchHasTeam(m: Match, needle: string): boolean {
   const fields = [