sportsing 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pardini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# ⚽ sportsing
+
+Sports in your terminal — the FIFA World Cup 2026 schedule, favorites, live
+scores, **ambient fav-alerts**, browser streaming, highlights, stats, and AI
+analysis. No npm dependencies; ships as a self-contained [Bun](https://bun.sh)
+binary.
+
+```
+sportsing fifa today
+sportsing fifa next --team USA
+sportsing today              # the `fifa` prefix is optional during the World Cup
+```
+
+## Install
+
+```sh
+bun install                 # dev deps (TypeScript, types)
+bun run build               # compiles a standalone binary → dist/sportsing
+```
+
+Then run `./dist/sportsing …`, or put it on your `PATH`. For live data, add a
+free [football-data.org](https://www.football-data.org) API key:
+
+```sh
+sportsing fifa setup       # paste your key (or set FOOTBALL_DATA_API_KEY)
+```
+
+Without a key, fixtures fall back to the offline openfootball schedule (no live
+scores or tables).
+
+## Commands
+
+`sportsing fifa <command>` (or just `sportsing <command>` during the Cup):
+
+| Command | What it does |
+|---|---|
+| `today` / `next` | Today's matches / next upcoming match + countdown |
+| `live [--notify [--quiet]]` | Auto-refreshing live scoreboard — see **Live fav-alerts** below |
+| `watch [team] [flags]` | Open the broadcast in your own browser — see **Watch** below |
+| `highlights <team>` | Open a highlights search |
+| `fixtures` / `schedule` / `results` | Fixtures, whole-tournament schedule, finished games (`--mine`) |
+| `table [A-L]` / `bracket` | Group standings / knockout bracket |
+| `teams` / `scorers` / `stats <team>` | Teams, Golden Boot race, match stats (`--json`) |
+| `analyze` / `predict <team>` | AI tactical read / prediction (answered by `serve`) |
+| `serve` | Run the AI answer loop that powers `analyze`, `predict`, and the overlay's "Ask Claude" (see **AI** below) |
+| `fav [add\|rm\|list]` / `me` | Manage favorite teams / your dashboard |
+| `setup [key]` | Add your football-data.org API key |
+
+Run `sportsing fifa help` for the full list (`serve` and `ask` are the AI-bus
+commands; `ask` is low-level plumbing that `serve` wraps).
+
+## Watch
+
+`sportsing fifa watch [team] [team]` opens the broadcast in your own browser
+(your real Chrome, via [ui-leaf](https://www.npmjs.com/package/@openthink/ui-leaf)):
+
+- **`--wait`** — block until the match goes live, then open it (deep-linked to the
+  game with the stats overlay). With no team, waits for the *next* match overall.
+- **`--overlay`** — inject the live-stats panel onto the page (needs a resolved
+  match; `--wait` always opens with it).
+- **`--provider peacock|fubo`** — override the configured default (Fubo by default;
+  Peacock is Spanish/Telemundo).
+- **`--url <link>`** — jump straight to a specific game link, skipping the hub.
+- **`--lang english|spanish`** — preferred broadcast language (default `english`),
+  for providers that carry both airings (Fubo = Fox/English + Telemundo/Spanish;
+  Peacock is Spanish-only). The flag is accepted and carried now; the
+  language-biased deep-link selection is not wired yet (a notice prints when a
+  non-default language is requested).
+
+- **`--smoke`** — open the window, confirm it came up, tear it down, exit 0. For
+  scripts/CI. `watch` is otherwise **interactive** — it blocks until you close the
+  window — so run without a controlling TTY (e.g. `< /dev/null`) it refuses rather
+  than hanging. Use `--smoke` to verify the launch path instead.
+- **`--supervised`** — opt into running headless (no TTY) without that refusal, for
+  a pidfile-managed background watcher. This is what `/loop agent-setup` uses to
+  keep `watch --wait` alive; it still blocks (it's reaped via the pidfile), so it's
+  not a smoke-test — use `--smoke` for that.
+
+For a hands-off, agent-driven session — open the game **and** keep "Ask Claude" /
+"Get caught up" answered — use **`/loop agent-setup`** instead of running `watch`
+yourself (see the **AI** section below).
+
+## Live fav-alerts
+
+Turn `live` into an ambient alerter that pings you when your favorite teams play:
+
+```sh
+sportsing fifa fav add USA                 # set up favorites first
+sportsing fifa live --notify               # live board + OS notifications
+sportsing fifa live --notify --quiet &     # headless: alerts only, backgroundable
+```
+
+Each refresh diffs the latest scores against the previous tick and raises an OS
+notification for every **new** favorite-team event — so each kickoff, goal, and
+full-time alerts exactly once:
+
+- **Kickoff** — *click the notification to start watching* (launches
+  `sportsing fifa watch <team>` for that match).
+- **Goal** — the scorer and the resulting scoreline (with a sound).
+- **Full time** — the final scoreline.
+
+Flags:
+
+- **`--notify`** — fire the alerts. With no favorites set, it warns and runs the
+  board normally. Without it, `live` behaves exactly as before.
+- **`--quiet`** — suppress the full-screen scoreboard so the command can be
+  backgrounded (`&`) as a pure ambient alerter without redrawing your terminal.
+  Only meaningful together with `--notify` — used alone it prints a hint and
+  exits. `Ctrl-C` stops it.
+
+### Click-to-watch requires `terminal-notifier`
+
+Clickable kickoff notifications use
+[`terminal-notifier`](https://github.com/julienXX/terminal-notifier) (macOS):
+
+```sh
+brew install terminal-notifier
+```
+
+Notifications **degrade gracefully** when it's absent: on macOS they fall back to
+`osascript` (plain banner, no click action); on Linux to `notify-send`; otherwise
+to a terminal bell. Nothing errors — you just don't get the one-click-to-watch
+behavior without `terminal-notifier`.
+
+## AI (analyze / predict / overlay "Ask Claude" + "Get caught up")
+
+sportsing never spawns a local model. AI features route to an **external** Claude
+agent over a file bus — opening a game is **not** enough; something must be serving
+the bus or the overlay's Ask Claude / Get caught up panels show "○ No agent".
+
+### Agent-driven watch session — `/loop agent-setup` (the blessed setup)
+
+In a Claude session, drop in:
+
+```
+/loop agent-setup [team]
+```
+
+One supervisor loop that **is** the whole setup: it opens your game and keeps that
+`watch --wait` window alive (relaunching it if it dies), and it serves the bus so
+**Ask Claude** and **Get caught up** (catchup) are actually answered — by that
+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.
+
+> **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".
+> Run it in a minimal-tool session (it answers untrusted viewer text).
+
+### Low-level primitive — `serve`
+
+`sportsing fifa serve` is the bare answerer loop (it powers `analyze` / `predict`
+too). `agent-setup` supersedes the old manual two-step for the agent-driven flow,
+but `serve` remains the primitive if you want to compose it yourself:
+
+```sh
+sportsing fifa watch --wait    # (backgrounded) opens the game when it's live
+/loop sportsing serve          # answer-only loop — no watch supervision
+```
+
+> **Run the answerer in a minimal-tool session.** Whether via `agent-setup` or
+> `serve`, the loop reads **untrusted** text (viewer questions + raw API fields)
+> into a tool-capable Claude session. Give that session no MCP/file tools and only
+> the `sportsing ask --reply` Bash capability, so a prompt-injection in a question
+> can't reach anything dangerous. `serve` prints this reminder each tick.
+
+## Development
+
+This is a stamp-governed repo — read [`AGENTS.md`](./AGENTS.md) before any git
+operation. Changes flow through `stamp review` → gate → `stamp merge`, never a
+direct push to `main`.
+
+```sh
+bun run typecheck
+bun test
+bun run build
+```

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "sportsing",
+  "version": "0.1.0",
+  "description": "Sportsing — the FIFA World Cup 2026 in your terminal: schedule, favorites, live scores, ambient fav-alerts, browser streaming, highlights, stats, and AI analysis.",
+  "type": "module",
+  "bin": {
+    "sportsing": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "build": "bun build src/index.ts --compile --outfile dist/sportsing",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MicroMediaSites/sportsing.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MicroMediaSites/sportsing/issues"
+  },
+  "homepage": "https://github.com/MicroMediaSites/sportsing#readme",
+  "keywords": [
+    "fifa",
+    "world-cup",
+    "wc2026",
+    "soccer",
+    "football",
+    "cli",
+    "terminal",
+    "bun",
+    "live-scores",
+    "sports"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "bun-types": "^1.3.14",
+    "typescript": "^6.0.3"
+  }
+}

package/src/ansi.ts

@@ -0,0 +1,36 @@
+// Tiny ANSI helper — no dependencies. Honors NO_COLOR and non-TTY output.
+
+const enabled = process.env.NO_COLOR == null && process.stdout.isTTY === true;
+
+const wrap = (open: number, close: number) => (s: string | number) =>
+  enabled ? `\x1b[${open}m${s}\x1b[${close}m` : String(s);
+
+export const c = {
+  reset: "\x1b[0m",
+  bold: wrap(1, 22),
+  dim: wrap(2, 22),
+  italic: wrap(3, 23),
+  underline: wrap(4, 24),
+  red: wrap(31, 39),
+  green: wrap(32, 39),
+  yellow: wrap(33, 39),
+  blue: wrap(34, 39),
+  magenta: wrap(35, 39),
+  cyan: wrap(36, 39),
+  gray: wrap(90, 39),
+  white: wrap(97, 39),
+  bgGreen: wrap(42, 49),
+  bgRed: wrap(41, 49),
+};
+
+/** Visible length, ignoring ANSI escape codes — for column alignment. */
+export function visibleLen(s: string): number {
+  return s.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+/** Pad a (possibly colored) string to a visible width. */
+export function pad(s: string, width: number, align: "left" | "right" = "left"): string {
+  const gap = Math.max(0, width - visibleLen(s));
+  const spaces = " ".repeat(gap);
+  return align === "left" ? s + spaces : spaces + s;
+}

package/src/api.ts

@@ -0,0 +1,157 @@
+import { join } from "path";
+import { mkdir } from "fs/promises";
+import { CACHE_DIR, getApiKey } from "./config.ts";
+import type {
+  MatchesResponse,
+  StandingsResponse,
+  ScorersResponse,
+  Match,
+} from "./types.ts";
+
+const BASE = "https://api.football-data.org/v4";
+const COMP = "WC"; // FIFA World Cup
+const OPENFOOTBALL =
+  "https://raw.githubusercontent.com/openfootball/worldcup.json/master/2026/worldcup.json";
+
+export class ApiError extends Error {
+  constructor(public status: number, message: string) {
+    super(message);
+  }
+}
+
+export class NoKeyError extends Error {}
+
+/** Disk cache so we stay under the 10 req/min free-tier limit. Shared with espn.ts. */
+export async function cached<T>(key: string, ttlMs: number, fetcher: () => Promise<T>): Promise<T> {
+  await mkdir(CACHE_DIR, { recursive: true });
+  const file = join(CACHE_DIR, key + ".json");
+  try {
+    const stat = await Bun.file(file).stat();
+    if (Date.now() - stat.mtimeMs < ttlMs) {
+      return (await Bun.file(file).json()) as T;
+    }
+  } catch {
+    /* miss */
+  }
+  const fresh = await fetcher();
+  await Bun.write(file, JSON.stringify(fresh));
+  return fresh;
+}
+
+async function get<T>(path: string): Promise<T> {
+  const key = await getApiKey();
+  if (!key) throw new NoKeyError();
+  const res = await fetch(BASE + path, { headers: { "X-Auth-Token": key } });
+  if (res.status === 429) {
+    throw new ApiError(429, "Rate limited (free tier = 10 req/min). Try again shortly.");
+  }
+  if (res.status === 403) {
+    throw new ApiError(403, "Forbidden — check your API key or plan.");
+  }
+  if (!res.ok) {
+    let detail = res.statusText;
+    try {
+      detail = ((await res.json()) as any).message ?? detail;
+    } catch {}
+    throw new ApiError(res.status, detail);
+  }
+  return (await res.json()) as T;
+}
+
+const q = (params: Record<string, string | number | undefined>) => {
+  const sp = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) if (v != null) sp.set(k, String(v));
+  const s = sp.toString();
+  return s ? "?" + s : "";
+};
+
+export interface MatchFilter {
+  status?: string; // SCHEDULED,TIMED,IN_PLAY,...
+  dateFrom?: string; // YYYY-MM-DD
+  dateTo?: string;
+  stage?: string;
+}
+
+/** All matches, optionally filtered. TTL short so live scores stay fresh. */
+export function getMatches(filter: MatchFilter = {}, ttlMs = 45_000): Promise<MatchesResponse> {
+  const cacheKey =
+    "matches_" +
+    (Object.entries(filter)
+      .filter(([, v]) => v != null)
+      .map(([k, v]) => `${k}-${v}`)
+      .join("_") || "all");
+  return cached(cacheKey, ttlMs, () =>
+    get<MatchesResponse>(`/competitions/${COMP}/matches${q({ ...filter })}`),
+  );
+}
+
+export function getStandings(ttlMs = 5 * 60_000): Promise<StandingsResponse> {
+  return cached("standings", ttlMs, () =>
+    get<StandingsResponse>(`/competitions/${COMP}/standings`),
+  );
+}
+
+export function getScorers(ttlMs = 10 * 60_000): Promise<ScorersResponse> {
+  return cached("scorers", ttlMs, () =>
+    get<ScorersResponse>(`/competitions/${COMP}/scorers?limit=20`),
+  );
+}
+
+const ROUND_TO_STAGE: Record<string, Match["stage"]> = {
+  "Round of 32": "LAST_32",
+  "Round of 16": "LAST_16",
+  "Quarter-final": "QUARTER_FINALS",
+  "Semi-final": "SEMI_FINALS",
+  "Match for third place": "THIRD_PLACE",
+  Final: "FINAL",
+};
+
+/** Parse openfootball times like "13:00 UTC-6" into a true UTC ISO string. */
+function offToUtcIso(date: string, time: string | undefined): string {
+  if (!date) return new Date().toISOString();
+  const m = (time ?? "").match(/(\d{1,2}):(\d{2})\s*UTC([+-]\d{1,2})?/);
+  const [y, mo, d] = date.split("-").map(Number) as [number, number, number];
+  if (!m) return new Date(Date.UTC(y, mo - 1, d, 0, 0)).toISOString();
+  const hour = Number(m[1]);
+  const min = Number(m[2]);
+  const off = m[3] ? Number(m[3]) : 0; // local = UTC+off, so UTC = local - off
+  return new Date(Date.UTC(y, mo - 1, d, hour - off, min)).toISOString();
+}
+
+const teamName = (t: any): string =>
+  typeof t === "string" ? t : t?.name ?? "TBD";
+
+/**
+ * Keyless fallback: openfootball public-domain WC 2026 schedule.
+ * Returns a Match[]-shaped array (fixtures only — no live scores / standings).
+ */
+export async function getOpenFootballMatches(): Promise<Match[]> {
+  return cached("openfootball", 24 * 60 * 60_000, async () => {
+    const res = await fetch(OPENFOOTBALL);
+    if (!res.ok)
+      throw new ApiError(
+        res.status,
+        "Could not fetch the offline fixture schedule — network unavailable. Run `sportsing setup` to add a free API key for live data.",
+      );
+    const data = (await res.json()) as any;
+    const out: Match[] = [];
+    let id = 1;
+    for (const g of data.matches ?? []) {
+      if (!g.team1 && !g.team2) continue;
+      const groupLetter = g.group ? String(g.group).replace(/^Group\s+/i, "") : null;
+      out.push({
+        id: g.num ?? id++,
+        utcDate: offToUtcIso(g.date, g.time),
+        status: "SCHEDULED",
+        stage: ROUND_TO_STAGE[g.round as string] ?? "GROUP_STAGE",
+        group: groupLetter ? `GROUP_${groupLetter}` : null,
+        matchday: null,
+        homeTeam: { name: teamName(g.team1) },
+        awayTeam: { name: teamName(g.team2) },
+        score: { winner: null, fullTime: { home: null, away: null } },
+        venue: g.ground ?? null,
+      });
+    }
+    return out;
+  });
+}

package/src/ask-bus.ts

@@ -0,0 +1,172 @@
+// The "ask bus" — a file-based mailbox that bridges sportsing's AI features to
+// an EXTERNAL Claude agent the user keeps running. sportsing NEVER spawns
+// `claude -p` or an agent-sdk call; instead it posts a question to this bus, and
+// a separate Claude session (looping `sportsing fifa ask --next`) picks it up,
+// answers succinctly, and posts the answer back. The overlay / analyze / predict
+// caller waits for the answer and renders it.
+//
+// Protocol (in ~/.cache/sportsing/ask/):
+//   q-<id>.json  — a question (written by the caller, read by the agent)
+//   a-<id>.json  — its answer (written by the agent, read by the caller)
+// Files are written atomically (.tmp + rename) so a watcher never reads a
+// partial file. The waiting caller deletes both once it has the answer.
+
+import { mkdir, readdir, readFile, writeFile, rename, unlink } from "fs/promises";
+import { join } from "path";
+import { CACHE_DIR } from "./config.ts";
+
+const BUS_DIR = join(CACHE_DIR, "ask");
+const Q_PREFIX = "q-";
+const A_PREFIX = "a-";
+const STALE_MS = 5 * 60_000; // a question nobody answered in 5 min is abandoned
+
+export type AskSource = "overlay" | "analyze" | "predict" | "catchup";
+
+export interface AskQuestion {
+  id: string;
+  source: AskSource;
+  /** The full, self-contained prompt the agent should answer. */
+  question: string;
+  /** Short human label (e.g. "BRA 1-0 ARG, 56'") shown to the agent for context. */
+  context?: string;
+  /** How to answer (length/format guidance), surfaced to the agent. */
+  hint: string;
+  /** Hard cap applied to the answer at delivery time (overlay), or null for none. */
+  maxChars: number | null;
+  ts: number;
+}
+
+async function ensureDir(): Promise<void> {
+  await mkdir(BUS_DIR, { recursive: true });
+}
+
+const ID_RE = /^ask_[a-z0-9]+$/;
+
+function newId(): string {
+  return "ask_" + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+}
+
+// IDs become file paths, so a caller-supplied id (e.g. `ask --reply <id>`) must
+// be validated before it touches the filesystem — otherwise `../…` could escape
+// the bus dir on read or write.
+function assertId(id: string): void {
+  if (typeof id !== "string" || !ID_RE.test(id)) throw new Error(`invalid ask id: ${JSON.stringify(id)}`);
+}
+
+const HEARTBEAT_FILE = join(BUS_DIR, ".serving");
+
+/** A serving agent (`serve` / `ask --next`) refreshes this while it waits, so a
+ *  caller can tell whether anyone is listening before posting a question that
+ *  would otherwise just time out. */
+export async function touchHeartbeat(): Promise<void> {
+  await ensureDir();
+  await writeFile(HEARTBEAT_FILE, String(Date.now())).catch(() => {});
+}
+
+/** True if a serving agent refreshed the heartbeat within `maxAgeMs` (default
+ *  90s — comfortably longer than a `serve` loop's gap between ticks). */
+export async function isServing(maxAgeMs = 90_000): Promise<boolean> {
+  try {
+    const ts = Number(await readFile(HEARTBEAT_FILE, "utf8"));
+    return Number.isFinite(ts) && Date.now() - ts < maxAgeMs;
+  } catch {
+    return false;
+  }
+}
+
+async function writeJsonAtomic(path: string, data: unknown): Promise<void> {
+  const tmp = path + ".tmp";
+  await writeFile(tmp, JSON.stringify(data));
+  await rename(tmp, path); // atomic on the same filesystem
+}
+
+/** Post a question to the bus; returns its id. */
+export async function postQuestion(q: Omit<AskQuestion, "id" | "ts">): Promise<string> {
+  await ensureDir();
+  const id = newId();
+  const full: AskQuestion = { ...q, id, ts: Date.now() };
+  await writeJsonAtomic(join(BUS_DIR, Q_PREFIX + id + ".json"), full);
+  return id;
+}
+
+/** Wait until an answer for `id` lands (or `timeoutMs` elapses). Cleans up both
+ *  the question and answer files on the way out. Returns the answer, or null on
+ *  timeout (no agent answered). */
+export async function waitForAnswer(id: string, timeoutMs: number): Promise<string | null> {
+  assertId(id);
+  await ensureDir();
+  const aPath = join(BUS_DIR, A_PREFIX + id + ".json");
+  const qPath = join(BUS_DIR, Q_PREFIX + id + ".json");
+  const deadline = Date.now() + timeoutMs;
+  try {
+    while (Date.now() < deadline) {
+      try {
+        const { answer } = JSON.parse(await readFile(aPath, "utf8"));
+        return typeof answer === "string" ? answer : "";
+      } catch {
+        /* not answered yet */
+      }
+      await new Promise((r) => setTimeout(r, 300));
+    }
+    return null;
+  } finally {
+    await unlink(qPath).catch(() => {});
+    await unlink(aPath).catch(() => {});
+  }
+}
+
+/** Pending (unanswered, non-stale) questions, oldest first. */
+export async function listPending(): Promise<AskQuestion[]> {
+  await ensureDir();
+  const files = await readdir(BUS_DIR).catch(() => [] as string[]);
+  const answered = new Set(files.filter((f) => f.startsWith(A_PREFIX)).map((f) => f.slice(A_PREFIX.length)));
+  const now = Date.now();
+  const out: AskQuestion[] = [];
+  for (const f of files) {
+    if (!f.startsWith(Q_PREFIX) || !f.endsWith(".json")) continue;
+    if (answered.has(f.slice(Q_PREFIX.length))) continue; // already has an answer waiting
+    try {
+      const q: AskQuestion = JSON.parse(await readFile(join(BUS_DIR, f), "utf8"));
+      // Validate shape so a malformed file (e.g. non-numeric ts) is skipped
+      // visibly rather than producing NaN comparisons downstream.
+      if (ID_RE.test(q?.id ?? "") && typeof q.question === "string" && typeof q.ts === "number" && now - q.ts <= STALE_MS) {
+        out.push(q);
+      }
+    } catch {
+      /* partial/malformed — skip */
+    }
+  }
+  return out.sort((a, b) => a.ts - b.ts);
+}
+
+/** The oldest pending question, optionally blocking up to `waitMs` for one. When
+ *  `markServing` is set, refreshes the serving heartbeat each poll so callers can
+ *  detect that an agent is listening (used by `serve` / `ask --next`). */
+export async function nextPending(waitMs = 0, markServing = false): Promise<AskQuestion | null> {
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    if (markServing) await touchHeartbeat();
+    const pending = await listPending();
+    if (pending.length) return pending[0]!;
+    if (Date.now() >= deadline) return null;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+}
+
+/** Deliver an answer for `id`. Applies the question's maxChars cap if set.
+ *  Returns false if the question is unknown (timed out / already cleaned up). */
+export async function postAnswer(id: string, answer: string): Promise<boolean> {
+  assertId(id);
+  await ensureDir();
+  let maxChars: number | null = null;
+  try {
+    const q: AskQuestion = JSON.parse(await readFile(join(BUS_DIR, Q_PREFIX + id + ".json"), "utf8"));
+    maxChars = q.maxChars;
+  } catch {
+    return false; // unknown id
+  }
+  let text = answer.trim();
+  if (maxChars && text.length > maxChars) text = text.slice(0, maxChars - 1).trimEnd() + "…";
+  await writeJsonAtomic(join(BUS_DIR, A_PREFIX + id + ".json"), { id, answer: text });
+  return true;
+}