moshcode 0.47.0 → 0.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moshcode",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "type": "module",
   "description": "moshcode — a metal wrapper for coding engines and native UGig/CoinPay workflow CLIs, with OpenPRD and moshscript",
   "repository": {

package/src/cli-schema.mjs

@@ -550,10 +550,14 @@ export const CORE_CLI_COMMANDS = [
     synopsis: [
       ["moshcode rss", "open the reader on your feeds"],
       ["moshcode rss <keyword…>", "open it on a search"],
+      ["moshcode rss search <keyword[,keyword…]>", "find feeds to subscribe to"],
+      ["moshcode rss add <url|list|#n>", "subscribe — same as `moshcode news add`"],
     ],
     examples: [
       ["moshcode rss", "feeds on the left, headlines in the middle"],
       ["moshcode rss tariffs", "open straight into a search"],
+      ["moshcode rss search rust,compilers", "search 32k published feeds for one to add"],
+      ["moshcode rss add 3", "subscribe to the third result"],
     ],
     seeAlso: ["news"],
     note: "needs an interactive terminal. ↑↓/jk move · ⏎ read · o open in a browser · "
@@ -800,12 +804,17 @@ export const NEWS_VERBS = [
   },
   { name: "list", description: "the feeds you are subscribed to", synopsis: [["moshcode news list [--json]", ""]] },
   {
-    name: "add", description: "subscribe to a feed, an OPML list, or a bundle",
-    synopsis: [["moshcode news add <url|file|bundle>", "an RSS/Atom link, an OPML list, or journalists|web3|blockchain"]],
+    name: "find", description: "search the published lists for feeds to subscribe to",
+    synopsis: [["moshcode news find <keyword[,keyword…]>", "same as `moshcode rss search <keyword…>`"]],
   },
-  { name: "rm", description: "unsubscribe", synopsis: [["moshcode news rm <name|url>", ""]] },
+  {
+    name: "add", description: "subscribe to a feed, a list, or a numbered result",
+    synopsis: [["moshcode news add <url|file|list|#n>", "an RSS/Atom link, an OPML file, a list by name, or #n from the last find"]],
+  },
+  { name: "rm", description: "unsubscribe from a feed, or a whole list", synopsis: [["moshcode news rm <name|url|list>", ""]] },
   { name: "open", description: "open a headline from the last listing", synopsis: [["moshcode news open <n>", ""]] },
-  { name: "sources", description: "the default feeds and the bundles on offer", synopsis: [["moshcode news sources", ""]] },
+  { name: "lists", description: "the published lists, and which you have added", synopsis: [["moshcode news lists [--json]", ""]] },
+  { name: "sources", description: "the default feeds and the lists on offer", synopsis: [["moshcode news sources", ""]] },
   { name: "export", description: "print the subscription list as OPML", synopsis: [["moshcode news export > feeds.opml", ""]] },
 ];
 

package/src/news-sources.mjs

@@ -7,58 +7,26 @@
 //   brisk.news — apps/web/src/lib/news/fetch-feed.ts builds Google News feeds,
 //     top stories for the front page and one per category, and
 //     scripts/import-opml-feeds.ts seeds its publisher table from four public
-//     OPML lists. Both are represented here: the Google feeds as the defaults,
-//     the OPML lists as named bundles `/news add` accepts by name.
+//     OPML lists. The lists are represented here as named entries `/news add`
+//     accepts; the Google feeds are not, for the reason isDeadEndLink() gives.
 //
 //   advis0r.com — src/providers/news/rss.ts pairs a Google News query feed with
 //     a Bing one (Google's links are interstitials, Bing's carry the publisher
-//     URL in a `url=` parameter), and reads two newswires directly. The search
-//     pairing is why `/news <keyword>` queries both, and the wires are here
-//     under `markets`.
+//     URL in a `url=` parameter), and reads two newswires directly. Only the
+//     Bing half of that pairing survives here — see isDeadEndLink() — and the
+//     wires are under `markets`.
 //
 // Deliberately small. A default list is a claim that every entry works, so it
 // holds feeds with stable well-known URLs and defers everything else to the
-// OPML bundles, where the list is somebody else's to maintain.
-
-/** Google News locale. One place, because every builder below needs it. */
-const GOOGLE_LOCALE = "hl=en-US&gl=US&ceid=US:en";
+// published lists, where the list is somebody else's to maintain.
 
 /**
- * Google News category feeds, keyed the way brisk.news keys them.
+ * Bing News query feed — the only search feed left.
  *
- * `general` is null there and means "top stories", which is a different URL
- * rather than a search for the word "general" — the same distinction is kept.
- */
-export const GOOGLE_NEWS_CATEGORIES = {
-  general: null,
-  science: "science",
-  sports: "sports",
-  business: "business",
-  health: "health",
-  entertainment: "entertainment",
-  tech: "technology",
-  politics: "politics",
-  food: "food",
-  travel: "travel",
-};
-
-/** Google News top stories, or one category from the map above. */
-export function googleNewsFeed(category = null) {
-  const mapped = category ? GOOGLE_NEWS_CATEGORIES[category] ?? null : null;
-  if (!mapped) return `https://news.google.com/rss?${GOOGLE_LOCALE}`;
-  return `https://news.google.com/rss/search?q=${encodeURIComponent(mapped)}&${GOOGLE_LOCALE}`;
-}
-
-/**
- * Google News query feed. `when:7d` style windows keep results recent —
- * advis0r's googleNewsFeed() does the same, for the same reason.
+ * The Google News builders that used to sit here were removed rather than left
+ * unused: keeping them would imply a Google News feed is still a thing this can
+ * read, and isDeadEndLink() explains at length why it is not.
  */
-export function googleNewsSearch(query, { window = "7d" } = {}) {
-  const q = window ? `${query} when:${window}` : String(query);
-  return `https://news.google.com/rss/search?q=${encodeURIComponent(q)}&${GOOGLE_LOCALE}`;
-}
-
-/** Bing News query feed — the half of a search whose links are real articles. */
 export function bingNewsSearch(query) {
   return `https://www.bing.com/news/search?q=${encodeURIComponent(query)}&format=RSS`;
 }
@@ -84,68 +52,176 @@ export function unwrapRedirect(url) {
   }
 }
 
+/**
+ * Is this a link that can never be resolved to the article it stands for?
+ *
+ * Google News item links are `news.google.com/rss/articles/CBMi…?oc=5`, and
+ * they are a dead end in the strict sense — this was measured, not assumed:
+ *
+ *   · A HEAD returns 302 whose `location` is the *same* URL with the locale
+ *     appended, which then 200s on a Google page. There is no publisher URL in
+ *     any header, so unwrapping by redirect does not work.
+ *   · The base64 segment decodes to a protobuf holding an opaque `AU_yqL…`
+ *     token and no URL.
+ *   · A full GET returns a 600KB Angular shell — the redirect is client-side,
+ *     and the target is not in the HTML.
+ *   · That leaves Google's internal `/_/DotsSplashUi/data/batchexecute`, which
+ *     answered 429 Too Many Requests on the first unauthenticated call. A
+ *     reader cannot be built on an endpoint that rate-limits a single request.
+ *   · Their `<description>` is an `<ol><li><a href=…>` list of more Google
+ *     links rather than a summary, so there is no content to show either.
+ *
+ * So an item behind one of these is a headline that cannot be read and cannot
+ * be opened. collectNews drops them rather than listing rows that do nothing.
+ * Bing's search feed is unaffected: it carries the publisher URL in `url=` and
+ * a real summary, which is why it is the one kept for searching.
+ */
+export function isDeadEndLink(url) {
+  try {
+    const parsed = new URL(String(url));
+    return /(^|\.)news\.google\.com$/i.test(parsed.hostname)
+      && /^\/rss\/articles\//i.test(parsed.pathname);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * The feeds a fresh install reads.
  *
- * Google News carries the general desks because that is exactly what brisk.news
- * serves its front page from, and it means one URL shape covers ten sections
- * without ten publisher relationships to keep working. The named publishers are
- * tier-1 hosts from advis0r's own tiering table that publish a stable feed, and
- * they earn their place by being readable end to end — a Google News item is a
- * headline behind an interstitial, theirs is the article.
+ * Every one of them is a publisher speaking for itself. Google News used to
+ * carry the general desks here — one URL shape covering ten sections without
+ * ten publisher relationships — and it was dropped precisely because of what
+ * isDeadEndLink() documents: its items cannot be opened and carry no summary,
+ * so a default list built on it is a list of rows that do nothing. The desks it
+ * covered (world, science, politics) are named publishers now instead.
+ *
+ * The profullstack blogs are here too, so `profullstack.com/feeds.opml` is read
+ * out of the box rather than only after `/news add profullstack`.
  */
 export const DEFAULT_FEEDS = [
-  { name: "top-stories", title: "Google News — Top Stories", url: googleNewsFeed(), site: "https://news.google.com", category: "" },
-  { name: "world", title: "Google News — World", url: googleNewsSearch("world news", { window: "2d" }), site: "https://news.google.com", category: "" },
-
-  { name: "tech", title: "Google News — Technology", url: googleNewsFeed("tech"), site: "https://news.google.com", category: "tech" },
   { name: "ars-technica", title: "Ars Technica", url: "https://feeds.arstechnica.com/arstechnica/index", site: "https://arstechnica.com", category: "tech" },
   { name: "techcrunch", title: "TechCrunch", url: "https://techcrunch.com/feed/", site: "https://techcrunch.com", category: "tech" },
   { name: "the-register", title: "The Register", url: "https://www.theregister.com/headlines.atom", site: "https://www.theregister.com", category: "tech" },
   { name: "hacker-news", title: "Hacker News — Front Page", url: "https://hnrss.org/frontpage", site: "https://news.ycombinator.com", category: "tech" },
 
-  { name: "business", title: "Google News — Business", url: googleNewsFeed("business"), site: "https://news.google.com", category: "markets" },
   { name: "marketwatch", title: "MarketWatch — Top Stories", url: "https://feeds.content.dowjones.io/public/rss/mw_topstories", site: "https://www.marketwatch.com", category: "markets" },
   // The two newswires advis0r reads directly. Tier 0 there: issuers speaking
   // for themselves rather than a publication speaking about them.
   { name: "pr-newswire", title: "PR Newswire — Financial Services", url: "https://www.prnewswire.com/rss/financial-services-latest-news/financial-services-latest-news-list.rss", site: "https://www.prnewswire.com", category: "markets" },
   { name: "globenewswire", title: "GlobeNewswire — Public Companies", url: "https://www.globenewswire.com/RssFeed/orgclass/1/feedTitle/GlobeNewswire%20-%20News%20about%20Public%20Companies", site: "https://www.globenewswire.com", category: "markets" },
 
-  { name: "science", title: "Google News — Science", url: googleNewsFeed("science"), site: "https://news.google.com", category: "science" },
-  { name: "politics", title: "Google News — Politics", url: googleNewsFeed("politics"), site: "https://news.google.com", category: "politics" },
+  { name: "npr-world", title: "NPR — World", url: "https://feeds.npr.org/1004/rss.xml", site: "https://www.npr.org", category: "world" },
+  { name: "bbc-world", title: "BBC News — World", url: "https://feeds.bbci.co.uk/news/world/rss.xml", site: "https://www.bbc.co.uk/news", category: "world" },
+  { name: "guardian-world", title: "The Guardian — World", url: "https://www.theguardian.com/world/rss", site: "https://www.theguardian.com", category: "world" },
+
+  { name: "science-daily", title: "ScienceDaily — Top Science", url: "https://www.sciencedaily.com/rss/top/science.xml", site: "https://www.sciencedaily.com", category: "science" },
+  { name: "phys-org", title: "Phys.org", url: "https://phys.org/rss-feed/", site: "https://phys.org", category: "science" },
+
+  { name: "npr-politics", title: "NPR — Politics", url: "https://feeds.npr.org/1014/rss.xml", site: "https://www.npr.org", category: "politics" },
+
+  // The profullstack blogs, read out of the box. This is the one published list
+  // small enough to be a default: profullstack.com/feeds.opml is 14 feeds, where
+  // smallweb is 33,000 and could only ever be searched. Kept in step with that
+  // file by hand rather than fetched, because defaultFeeds() is synchronous and
+  // a fresh install must not wait on a network call to show anything at all.
+  { name: "bittorrented-blog", title: "BitTorrented Blog", url: "https://bittorrented.com/blog/rss.xml", site: "https://bittorrented.com/blog", category: "profullstack" },
+  { name: "bl0ggers-blog", title: "bl0ggers Blog", url: "https://bl0ggers.com/blog/rss.xml", site: "https://bl0ggers.com/blog", category: "profullstack" },
+  { name: "c0mpute-blog", title: "c0mpute Blog", url: "https://c0mpute.com/blog/rss.xml", site: "https://c0mpute.com/blog", category: "profullstack" },
+  { name: "c0upons-blog", title: "c0upons Blog", url: "https://c0upons.com/blog/rss.xml", site: "https://c0upons.com/blog", category: "profullstack" },
+  { name: "coinpay-blog", title: "CoinPay Blog", url: "https://coinpayportal.com/blog/rss.xml", site: "https://coinpayportal.com/blog", category: "profullstack" },
+  { name: "crawlproof-blog", title: "CrawlProof Blog", url: "https://crawlproof.com/blog/rss.xml", site: "https://crawlproof.com/blog", category: "profullstack" },
+  { name: "d0rz-blog", title: "d0rz Blog", url: "https://d0rz.com/blog/rss.xml", site: "https://d0rz.com/blog", category: "profullstack" },
+  { name: "logicsrc-blog", title: "LogicSRC Blog", url: "https://logicsrc.com/blog/rss.xml", site: "https://logicsrc.com/blog", category: "profullstack" },
+  { name: "pairux-blog", title: "PairUX Blog", url: "https://pairux.com/blog/rss.xml", site: "https://pairux.com/blog", category: "profullstack" },
+  { name: "qryptchat-blog", title: "QryptChat Blog", url: "https://qrypt.chat/blog/rss.xml", site: "https://qrypt.chat/blog", category: "profullstack" },
+  { name: "saasrow-blog", title: "SaaSRow Blog", url: "https://www.saasrow.com/blog/rss.xml", site: "https://www.saasrow.com/blog", category: "profullstack" },
+  { name: "sh1pt-blog", title: "sh1pt Blog", url: "https://sh1pt.com/blog/rss.xml", site: "https://sh1pt.com/blog", category: "profullstack" },
+  { name: "threatcrush-blog", title: "ThreatCrush Blog", url: "https://threatcrush.com/blog/rss.xml", site: "https://threatcrush.com/blog", category: "profullstack" },
+  { name: "ugig-blog", title: "ugig Blog", url: "https://ugig.net/blog/rss.xml", site: "https://ugig.net/blog", category: "profullstack" },
 ];
 
 /**
- * The public OPML lists brisk.news imports its publisher table from.
+ * The public feed lists, offered by name.
  *
  * Offered by name (`/news add journalists`) rather than only by URL because
  * these are long, exact raw.githubusercontent paths that nobody is going to
  * retype, and importing one is the fastest way from an empty reader to a real
  * one. They are somebody else's lists, and that is the point: the feeds inside
  * them stay current without moshcode shipping a release.
+ *
+ * Two shapes, because the lists worth reading come in two:
+ *
+ *   `format: "opml"` — an OPML document, parsed by parseOpml.
+ *   `format: "text"` — one feed URL per line, `#` comments ignored. Kagi's
+ *     smallweb list is published this way and there is no OPML of it.
+ *
+ * `searchOnly` marks a list too large to subscribe to wholesale. smallweb is
+ * 32,000+ feeds: importing it would write a 32,000-entry news.opml and then try
+ * to fetch every one of them on the next `/news`. It is a catalogue to search,
+ * not a subscription — `/rss search <keyword>` is how you get feeds out of it.
  */
-export const OPML_BUNDLES = [
+export const FEED_LISTS = [
   {
     name: "journalists",
     description: "Dave Winer's feedsForJournalists — mainstream desks",
     url: "https://raw.githubusercontent.com/scripting/feedsForJournalists/master/list.opml",
+    format: "opml",
   },
   {
     name: "web3",
     description: "ChainFeeds RSSAggregatorforWeb3 — crypto and web3",
     url: "https://raw.githubusercontent.com/chainfeeds/RSSAggregatorforWeb3/main/RAW.opml",
+    format: "opml",
   },
   {
     name: "blockchain",
     description: "CoinFabrik decentralized-and-blockchain-feeds",
     url: "https://raw.githubusercontent.com/CoinFabrik/resources/master/decentralized-and-blockchain-feeds.opml",
+    format: "opml",
+  },
+  {
+    name: "profullstack",
+    description: "Profullstack product blogs",
+    url: "https://profullstack.com/feeds.opml",
+    format: "opml",
+  },
+  {
+    name: "smallweb",
+    description: "Kagi Small Web — 33k personal blogs, with titles",
+    url: "https://kagi.com/smallweb/opml",
+    format: "opml",
+    searchOnly: true,
+  },
+  {
+    name: "smallweb-txt",
+    description: "Kagi Small Web, profullstack's fork — the plain-text list",
+    url: "https://raw.githubusercontent.com/ralyodio/smallweb/refs/heads/main/smallweb.txt",
+    format: "text",
+    searchOnly: true,
   },
 ];
 
-/** Resolve a bundle name to its OPML URL, or null. */
-export function resolveBundle(name) {
+/**
+ * The old name for the list catalogue.
+ *
+ * Kept because `/news sources --json` published it and a caller may be reading
+ * that key; the shape is unchanged for the three lists that were in it.
+ */
+export const OPML_BUNDLES = FEED_LISTS;
+
+/** Resolve a list name to its entry, or null. */
+export function resolveList(name) {
   const wanted = String(name ?? "").trim().toLowerCase();
-  return OPML_BUNDLES.find((b) => b.name === wanted) ?? null;
+  return FEED_LISTS.find((b) => b.name === wanted) ?? null;
+}
+
+/** The former name of resolveList. */
+export const resolveBundle = resolveList;
+
+/** The lists `/news add <name>` will import in full. */
+export function subscribableLists() {
+  return FEED_LISTS.filter((list) => !list.searchOnly);
 }
 
 /** A fresh copy of the defaults — callers mutate feed lists. */

package/src/news.mjs

@@ -26,9 +26,10 @@ import { acid, ash, amber, bone, danger } from "./ui.mjs";
 import {
   bingNewsSearch,
   defaultFeeds,
-  googleNewsSearch,
-  OPML_BUNDLES,
-  resolveBundle,
+  FEED_LISTS,
+  isDeadEndLink,
+  resolveList,
+  subscribableLists,
   unwrapRedirect,
 } from "./news-sources.mjs";
 
@@ -39,11 +40,14 @@ const USAGE = `usage: moshcode news [verb|keyword…] [args…]
   <keyword…>                     search the news for a word or phrase
   <url>                          read one feed without subscribing to it
   list                           the feeds you are subscribed to
-  add <url|file|bundle>          subscribe — an RSS/Atom link, an OPML list, or
-                                 a bundle: ${OPML_BUNDLES.map((b) => b.name).join(", ")}
-  rm <name|url>                  unsubscribe
+  find <keyword[,keyword…]>      search every published list for feeds to add
+  add <url|file|list|#n>         subscribe — an RSS/Atom link, an OPML file, a
+                                 list by name (${subscribableLists().map((b) => b.name).join(", ")}),
+                                 or #n from the last find
+  rm <name|url|list>             unsubscribe — one feed, or a whole list at once
   open <n>                       open headline <n> from the last listing
-  sources                        the default feeds and the bundles on offer
+  lists                          the published lists, and which you have added
+  sources                        the default feeds and the lists on offer
   export                         print the subscription list as OPML
 
   --json                         print structured data instead of headlines
@@ -63,7 +67,7 @@ export function newsUsage() {
 }
 
 /** Verb names, in help order. cli-schema's NEWS_VERBS must match (drift test). */
-export const NEWS_VERB_NAMES = ["latest", "search", "list", "add", "rm", "open", "sources", "export"];
+export const NEWS_VERB_NAMES = ["latest", "search", "list", "find", "add", "rm", "open", "lists", "sources", "export"];
 
 // The same reasoning as crypto's alias table: the obvious synonym should not be
 // an error. `import` is the word an OPML file invites, and it is the same verb
@@ -75,7 +79,9 @@ const VERB_ALIASES = {
   sub: "add", subscribe: "add", import: "add", follow: "add",
   remove: "rm", unsub: "rm", unsubscribe: "rm", del: "rm", delete: "rm",
   read: "open", browse: "open", www: "open",
-  bundles: "sources", defaults: "sources",
+  discover: "find", catalog: "find", catalogue: "find",
+  bundles: "lists",
+  defaults: "sources",
   opml: "export", dump: "export",
 };
 
@@ -399,6 +405,176 @@ export function findFeed(feeds, needle) {
     ?? null;
 }
 
+// ---------------------------------------------------------------------------
+// Published lists — a catalogue to search, and a unit to subscribe to
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a newline-delimited feed list: one URL per line, `#` comments ignored.
+ *
+ * The other shape a published list comes in. Kagi's smallweb list is a plain
+ * text file of 32,000 URLs and there is no OPML of it, so a reader that only
+ * speaks OPML cannot read the largest list there is. No titles are invented
+ * beyond the hostname — naming 32,000 feeds properly would mean fetching
+ * 32,000 feeds, and the host is what the URL already tells us for free.
+ */
+export function parseFeedList(text) {
+  const feeds = [];
+  const seen = new Set();
+  for (const line of String(text ?? "").split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const url = safeUrl(trimmed);
+    if (!url || seen.has(url)) continue;
+    seen.add(url);
+    feeds.push({ name: hostSlug(url), title: hostOf(url), url, site: "", category: "" });
+  }
+  return feeds;
+}
+
+/** Parse a list document as whichever of the two shapes it is. */
+export function parseListDocument(body, format = "") {
+  if (format === "text") return parseFeedList(body);
+  if (format === "opml") return parseOpml(body);
+  return looksLikeOpml(body) ? parseOpml(body) : parseFeedList(body);
+}
+
+/** Where a fetched list is cached, so searching does not refetch 32k feeds. */
+export function listCacheFile(name, env = process.env) {
+  return path.join(path.dirname(opmlFile(env)), "lists", `${slugify(name) || "list"}.json`);
+}
+
+/** Where the last `find` results are remembered, so `add 3` knows what 3 was. */
+export function findCacheFile(env = process.env) {
+  return path.join(path.dirname(opmlFile(env)), "news-found.json");
+}
+
+/** A day. These lists change on the order of weeks; a search must not wait on the network. */
+const LIST_CACHE_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * The feeds in a published list, from cache when it is fresh.
+ *
+ * A stale cache is preferred to an error when the fetch fails: the list was
+ * good yesterday and a search that works offline beats one that does not.
+ */
+export async function loadListFeeds(list, {
+  fetchImpl, env = process.env, timeoutMs = DEFAULT_TIMEOUT_MS, now = Date.now(), refresh = false,
+} = {}) {
+  const file = listCacheFile(list.name, env);
+  const cached = () => {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+      return Array.isArray(parsed?.feeds) ? parsed : null;
+    } catch { return null; }
+  };
+
+  if (!refresh) {
+    const hit = cached();
+    if (hit && now - Number(hit.at || 0) < LIST_CACHE_MS) {
+      return { ok: true, feeds: hit.feeds, cached: true };
+    }
+  }
+
+  const res = await readSource(list.url, { fetchImpl, timeoutMs });
+  if (!res.ok) {
+    const hit = cached();
+    if (hit) return { ok: true, feeds: hit.feeds, cached: true, stale: true };
+    return { ok: false, error: res.error, feeds: [] };
+  }
+
+  const feeds = parseListDocument(res.body, list.format);
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, `${JSON.stringify({ at: now, url: list.url, feeds })}\n`, { mode: FILE_MODE });
+    try { fs.chmodSync(file, FILE_MODE); } catch { /* best effort */ }
+  } catch { /* a cache that cannot be written must not fail the search */ }
+  return { ok: true, feeds, cached: false };
+}
+
+/**
+ * Split `ai,crypto` into keywords.
+ *
+ * Comma-separated rather than space-separated because feed titles have spaces
+ * in them: `/rss search hacker news` means one thing to a person and two to a
+ * tokenizer, and the comma settles it. Spaces around a comma are trimmed.
+ */
+export function parseKeywords(raw) {
+  return String(raw ?? "")
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+/**
+ * Feeds matching any keyword, best match first.
+ *
+ * Ranked rather than filtered, because filtering cannot win both halves of this:
+ *
+ *   · Plain substring matching searches 32,000 feeds for `rust` and returns
+ *     Trust Machines, Trustnodes, frustrat.com and popthruster.com.
+ *   · Requiring the keyword to start a word fixes that and then finds nothing
+ *     at all for `homelab`, because the list's only metadata is the hostname
+ *     and the blog is called myhomelab.net.
+ *
+ * So everything containing the keyword is kept, and a whole-word match sorts
+ * above a word that starts with it, which sorts above a match buried anywhere.
+ * With the results capped for display, the good ones are the ones you see.
+ * Sorting is stable, so the list's own order survives within a rank.
+ */
+export function scoreFeed(feed, keywords) {
+  const hay = `${feed.title || ""} ${feed.url} ${feed.category || ""}`.toLowerCase();
+  let best = 0;
+  for (const k of keywords) {
+    if (!hay.includes(k)) continue;
+    const tokens = hay.split(/[^a-z0-9]+/).filter(Boolean);
+    if (tokens.some((t) => t === k)) { best = Math.max(best, 3); continue; }
+    if (tokens.some((t) => t.startsWith(k))) { best = Math.max(best, 2); continue; }
+    best = Math.max(best, 1);
+  }
+  return best;
+}
+
+export function matchFeeds(feeds, keywords) {
+  if (!keywords.length) return [];
+  return feeds
+    .map((feed, i) => ({ feed, rank: scoreFeed(feed, keywords), i }))
+    .filter((row) => row.rank > 0)
+    .sort((a, b) => (b.rank - a.rank) || (a.i - b.i))
+    .map((row) => row.feed);
+}
+
+/**
+ * The list a subscribed feed came from, or "".
+ *
+ * Provenance rides in the OPML folder — the first path segment of `category` —
+ * rather than in a sidecar file, so it survives a round trip through any other
+ * reader and needs no format of our own. Only catalogue names count, so a
+ * folder someone happens to call "tech" is not mistaken for a list.
+ */
+export function listOf(feed) {
+  const head = String(feed?.category || "").split("/")[0];
+  return resolveList(head) ? head : "";
+}
+
+/** How many subscribed feeds came from each published list. */
+export function subscribedLists(feeds = []) {
+  const counts = new Map();
+  for (const feed of feeds) {
+    const name = listOf(feed);
+    if (name) counts.set(name, (counts.get(name) || 0) + 1);
+  }
+  return counts;
+}
+
+/** Tag a list's feeds with where they came from, keeping any folder they had. */
+export function tagWithList(feeds, listName) {
+  return feeds.map((feed) => ({
+    ...feed,
+    category: feed.category ? `${listName}/${feed.category}` : listName,
+  }));
+}
+
 // ---------------------------------------------------------------------------
 // Feeds — RSS 2.0, Atom, and RSS 1.0/RDF
 // ---------------------------------------------------------------------------
@@ -597,6 +773,11 @@ export async function collectNews(feeds, { fetchImpl, timeoutMs = DEFAULT_TIMEOU
       // before deduping, so the same story arriving via Google News and via the
       // publisher's own feed is recognised as one story rather than two.
       const link = item.link ? unwrapRedirect(item.link) : null;
+      // A link that unwrapping cannot rescue is a row that would do nothing
+      // when opened, so the headline is dropped rather than shown. Only
+      // aggregator interstitials qualify; an item with no link at all is still
+      // worth listing, because its title carries the news.
+      if (link && isDeadEndLink(link)) continue;
       const key = link || `${result.feed.name}:${item.title}`;
       if (seen.has(key)) continue;
       seen.add(key);
@@ -621,8 +802,11 @@ export async function collectNews(feeds, { fetchImpl, timeoutMs = DEFAULT_TIMEOU
  * openable links wherever the two overlap.
  */
 export function searchFeeds(query) {
+  // Bing only. The Google half of advis0r's pairing returned headlines whose
+  // links go nowhere and whose descriptions are lists of more Google links, so
+  // every one of its results was dropped downstream anyway — see
+  // isDeadEndLink(). Bing carries the publisher URL and a real summary.
   return [
-    { name: "google", title: `Google News — ${query}`, url: googleNewsSearch(query), site: "", category: "" },
     { name: "bing", title: `Bing News — ${query}`, url: bingNewsSearch(query), site: "", category: "" },
   ];
 }
@@ -723,13 +907,28 @@ export function newsArgs(argv = []) {
     if (!query) return { error: "usage: moshcode news search <keyword…>" };
     return { ...base, verb, query };
   }
+  if (verb === "find") {
+    const query = tail.join(" ").trim();
+    if (!query) return { error: "usage: moshcode news find <keyword[,keyword…]>" };
+    const keywords = parseKeywords(query);
+    if (!keywords.length) return { error: "find needs a keyword" };
+    return { ...base, verb, keywords };
+  }
   if (verb === "add") {
-    if (!tail.length) return { error: "usage: moshcode news add <url|file>" };
-    if (tail.length > 1) return { error: "add takes one URL or file at a time" };
+    if (!tail.length) return { error: "usage: moshcode news add <url|file|list|#n>" };
+    if (tail.length > 1) return { error: "add takes one URL, list, or number at a time" };
+    // `add 3` and `add #3` take the third result of the last find. A feed URL
+    // is never a bare number, so this cannot shadow one.
+    const asIndex = /^#?(\d+)$/.exec(String(tail[0]).trim());
+    if (asIndex) {
+      const n = Number(asIndex[1]);
+      if (n < 1) return { error: `add takes a result number from 1, got ${JSON.stringify(tail[0])}` };
+      return { ...base, verb, target: null, index: n };
+    }
     return { ...base, verb, target: tail[0] };
   }
   if (verb === "rm") {
-    if (!tail.length) return { error: "usage: moshcode news rm <name|url>" };
+    if (!tail.length) return { error: "usage: moshcode news rm <name|url|list>" };
     return { ...base, verb, target: tail.join(" ") };
   }
   if (verb === "open") {
@@ -808,8 +1007,9 @@ export function renderFeeds(feeds, { file = "", usingDefaults = false } = {}) {
   if (!feeds.length) {
     return ["", `  ${ash("no feeds yet")}`, "",
       `  ${ash("add one:")}    ${bone("/news add https://example.com/feed.xml")}`,
-      `  ${ash("or a list:")}  ${bone("/news add ~/subscriptions.opml")}`,
-      `  ${ash("or a bundle:")}${bone(" /news add journalists")}`].join("\n");
+      `  ${ash("or a file:")}  ${bone("/news add ~/subscriptions.opml")}`,
+      `  ${ash("or a list:")}  ${bone("/news add journalists")}`,
+      `  ${ash("or search:")}  ${bone("/rss search ai,crypto")}`].join("\n");
   }
   const width = Math.max(...feeds.map((f) => f.name.length));
   const header = usingDefaults
@@ -825,7 +1025,7 @@ export function renderFeeds(feeds, { file = "", usingDefaults = false } = {}) {
     lines.push(`  ${acid(feed.name.padEnd(width))}  ${bone(clip(feed.title || "", 34).padEnd(36))}${ash(feed.url)}`);
   }
   lines.push("", usingDefaults
-    ? `  ${ash("subscribe to your own with")} ${bone("/news add <url|bundle>")} ${ash("· see them with")} ${bone("/news sources")}`
+    ? `  ${ash("subscribe to your own with")} ${bone("/news add <url|list>")} ${ash("· see them with")} ${bone("/news lists")}`
     : `  ${ash("read them with")} ${bone("/news")} ${ash("· one of them with")} ${bone("/news --feed <name>")}`);
   return lines.join("\n");
 }
@@ -843,12 +1043,60 @@ export function renderSources() {
     }
     lines.push(`  ${acid(feed.name.padEnd(width))}  ${ash(clip(feed.title || "", 44))}`);
   }
-  lines.push("", `  ${bone("bundles")} ${ash("— public OPML lists, pull one in by name")}`, "");
-  const bw = Math.max(...OPML_BUNDLES.map((b) => b.name.length));
-  for (const bundle of OPML_BUNDLES) {
-    lines.push(`  ${acid(bundle.name.padEnd(bw))}  ${ash(bundle.description)}`);
+  lines.push("", `  ${bone("lists")} ${ash("— published feed lists, pull one in by name")}`, "");
+  const bw = Math.max(...FEED_LISTS.map((b) => b.name.length));
+  for (const list of FEED_LISTS) {
+    const note = list.searchOnly ? ash(" (search only)") : "";
+    lines.push(`  ${acid(list.name.padEnd(bw))}  ${ash(clip(list.description, 52))}${note}`);
   }
-  lines.push("", `  ${ash("pull one in with")} ${bone(`/news add ${OPML_BUNDLES[0].name}`)}`);
+  lines.push("", `  ${ash("pull one in with")} ${bone(`/news add ${subscribableLists()[0].name}`)} ${ash("· search them all with")} ${bone("/rss search <keyword>")}`);
+  return lines.join("\n");
+}
+
+/**
+ * The published lists, and how many feeds you have from each.
+ *
+ * `subscribed` is counted from the subscription file rather than remembered
+ * separately, so a list stays "added" exactly as long as its feeds are there —
+ * removing them by hand cannot leave a phantom membership behind.
+ */
+export function renderLists(feeds = []) {
+  const mine = subscribedLists(feeds);
+  const width = Math.max(...FEED_LISTS.map((b) => b.name.length));
+  const lines = ["", `  ${ash("published lists")}`, ""];
+  for (const list of FEED_LISTS) {
+    const count = mine.get(list.name) || 0;
+    const state = count
+      ? acid(`✓ ${count} feed${count === 1 ? "" : "s"}`)
+      : (list.searchOnly ? ash("search only") : ash("—"));
+    lines.push(`  ${acid(list.name.padEnd(width))}  ${bone(clip(list.description, 46).padEnd(48))}${state}`);
+  }
+  lines.push("",
+    `  ${ash("add one:")}     ${bone("/news add profullstack")}`,
+    `  ${ash("drop one:")}    ${bone("/news rm profullstack")} ${ash("— removes every feed it brought in")}`,
+    `  ${ash("search them:")} ${bone("/rss search ai,crypto")}`);
+  return lines.join("\n");
+}
+
+/** Feeds found in the published lists, numbered so `add #n` can take one. */
+export function renderFindHits(hits, { keywords = [], total = 0, subscribed = [] } = {}) {
+  if (!hits.length) {
+    return ["", `  ${ash(`nothing in the published lists matches ${keywords.join(", ")}`)}`, "",
+      `  ${ash("the lists searched:")} ${bone(FEED_LISTS.map((l) => l.name).join(", "))}`,
+      `  ${ash("or subscribe by URL:")} ${bone("/rss add https://example.com/feed.xml")}`].join("\n");
+  }
+  const have = new Set(subscribed.map((f) => f.url));
+  const width = String(hits.length).length;
+  const lines = ["",
+    `  ${ash(`${total} feed${total === 1 ? "" : "s"} match ${keywords.join(", ")}${total > hits.length ? ` · showing ${hits.length}` : ""}`)}`,
+    ""];
+  hits.forEach((feed, i) => {
+    const n = String(i + 1).padStart(width);
+    const mark = have.has(feed.url) ? acid(" ✓") : "  ";
+    lines.push(`  ${bone(n)}.${mark} ${acid(clip(feed.title || hostOf(feed.url), 30).padEnd(32))}${ash(clip(feed.url, 58))}`);
+    if (feed.list) lines.push(`      ${ash(`from ${feed.list}`)}`);
+  });
+  lines.push("", `  ${ash("subscribe with")} ${bone("/rss add 1")} ${ash("· or the URL ·")} ${acid("✓")} ${ash("means already subscribed")}`);
   return lines.join("\n");
 }
 
@@ -903,11 +1151,28 @@ export async function newsCommand(argv = [], deps = {}) {
   }
 
   if (request.verb === "sources") {
-    if (request.json) { out(JSON.stringify({ defaults: defaultFeeds(), bundles: OPML_BUNDLES }, null, 2)); return 0; }
+    // `bundles` is the old key for the same array; kept so a caller reading it
+    // does not break on the rename.
+    if (request.json) { out(JSON.stringify({ defaults: defaultFeeds(), lists: FEED_LISTS, bundles: FEED_LISTS }, null, 2)); return 0; }
     out(renderSources());
     return 0;
   }
 
+  if (request.verb === "lists") {
+    const feeds = loadFeeds(env);
+    if (request.json) {
+      const mine = subscribedLists(feeds);
+      out(JSON.stringify({
+        lists: FEED_LISTS.map((list) => ({ ...list, subscribed: mine.get(list.name) || 0 })),
+      }, null, 2));
+      return 0;
+    }
+    out(renderLists(feeds));
+    return 0;
+  }
+
+  if (request.verb === "find") return findCommand(request, { out, fail, fetchImpl, env });
+
   if (request.verb === "export") {
     // The defaults deliberately: exporting an empty file to hand to a reader is
     // not what anyone means by "export my feeds" on a fresh install.
@@ -979,11 +1244,86 @@ export async function newsCommand(argv = [], deps = {}) {
   return items.length === 0 && failures.length === feeds.length ? 1 : 0;
 }
 
-/** `news add <url|file|bundle>` — one feed, or every feed in an OPML list. */
+/** How many matches a find prints. The rest are counted, not listed. */
+const FIND_LIMIT = 25;
+
+/**
+ * `news find <keyword,…>` — search every published list for feeds to subscribe to.
+ *
+ * This is the way into the big lists. smallweb alone is 32,000 feeds, which is
+ * a fine thing to search and an impossible thing to subscribe to, so the
+ * catalogue is read here and only the matches become candidates for `add`.
+ */
+async function findCommand(request, { out, fail, fetchImpl, env }) {
+  const hits = [];
+  const seen = new Set();
+  const failures = [];
+
+  for (const list of FEED_LISTS) {
+    const loaded = await loadListFeeds(list, { fetchImpl, env, timeoutMs: request.timeoutMs });
+    if (!loaded.ok) { failures.push(`${list.name}: ${loaded.error}`); continue; }
+    for (const feed of matchFeeds(loaded.feeds, request.keywords)) {
+      if (seen.has(feed.url)) continue;
+      seen.add(feed.url);
+      hits.push({ ...feed, list: list.name });
+    }
+  }
+
+  // Ranked across every list, not within each one. Sorting per list and then
+  // concatenating puts all of web3's weak matches above smallweb's exact ones
+  // purely because web3 is fetched first.
+  hits.sort((a, b) => scoreFeed(b, request.keywords) - scoreFeed(a, request.keywords));
+
+  if (!hits.length && failures.length === FEED_LISTS.length) {
+    fail(danger("✗ could not read any of the published lists"));
+    for (const line of failures) fail(`  ${ash(line)}`);
+    return 1;
+  }
+
+  const shown = hits.slice(0, FIND_LIMIT);
+  // Remembered so `add 3` resolves, and only the shown ones — a number the
+  // operator never saw is not a number they can have meant.
+  try {
+    const file = findCacheFile(env);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, `${JSON.stringify({ at: Date.now(), keywords: request.keywords, hits: shown }, null, 2)}\n`, { mode: FILE_MODE });
+    try { fs.chmodSync(file, FILE_MODE); } catch { /* best effort */ }
+  } catch { /* a cache that cannot be written must not fail the search */ }
+
+  if (request.json) { out(JSON.stringify({ keywords: request.keywords, total: hits.length, hits: shown, failures }, null, 2)); return 0; }
+  out(renderFindHits(shown, { keywords: request.keywords, total: hits.length, subscribed: loadFeeds(env) }));
+  for (const line of failures) fail(`  ${ash(`· ${line}`)}`);
+  return 0;
+}
+
+/** The feed a previous `find` numbered `n`, or null. */
+function foundAt(index, env) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(findCacheFile(env), "utf8"));
+    return Array.isArray(parsed?.hits) ? parsed.hits[index - 1] ?? null : null;
+  } catch { return null; }
+}
+
+/** `news add <url|file|list|#n>` — one feed, or every feed in a list. */
 async function addCommand(request, { out, fail, fetchImpl, env }) {
-  // A bundle name resolves to somebody else's OPML list. Checked before the URL
-  // and the path so `journalists` is a name rather than a missing file.
-  const bundle = resolveBundle(request.target);
+  // `add 3` — the third result of the last find, subscribed by its URL.
+  if (request.index != null) {
+    const found = foundAt(request.index, env);
+    if (!found) {
+      fail(danger(`✗ there is no result ${request.index} — run \`/rss search <keyword>\` first`));
+      return 1;
+    }
+    request = { ...request, target: found.url, index: null };
+  }
+
+  // A list name resolves to somebody else's published list. Checked before the
+  // URL and the path so `journalists` is a name rather than a missing file.
+  const bundle = resolveList(request.target);
+  if (bundle?.searchOnly) {
+    fail(danger(`✗ ${bundle.name} is ${bundle.description}`));
+    fail(`  ${ash("too large to subscribe to wholesale — search it instead:")} ${bone(`/rss search <keyword>`)}`);
+    return 1;
+  }
   const target = bundle ? bundle.url : request.target;
   if (bundle) out(`${ash("· ")}fetching ${bone(bundle.name)} ${ash(`— ${bundle.description}`)}`);
 
@@ -996,9 +1336,13 @@ async function addCommand(request, { out, fail, fetchImpl, env }) {
   const existing = loadFeeds(env);
   const asUrl = safeUrl(target);
 
-  if (looksLikeOpml(res.body)) {
-    const incoming = parseOpml(res.body);
-    if (!incoming.length) { fail(danger("✗ that OPML file lists no feeds")); return 1; }
+  // A named list is whichever shape it says it is; anything else is a list only
+  // if it announces itself as OPML, so a plain feed is never read as one.
+  if (bundle || looksLikeOpml(res.body)) {
+    const parsedList = parseListDocument(res.body, bundle?.format);
+    // Tagged with the list it came from, so `rm <list>` can take it back out.
+    const incoming = bundle ? tagWithList(parsedList, bundle.name) : parsedList;
+    if (!incoming.length) { fail(danger(`✗ that ${bundle?.format === "text" ? "list" : "OPML file"} lists no feeds`)); return 1; }
     let feeds = existing;
     const added = [];
     let skipped = 0;
@@ -1054,9 +1398,27 @@ async function addCommand(request, { out, fail, fetchImpl, env }) {
   return 0;
 }
 
-/** `news rm <name|url>` — unsubscribe. */
+/** `news rm <name|url|list>` — unsubscribe from one feed, or a whole list. */
 function removeCommand(request, { out, fail, env }) {
   const feeds = loadFeeds(env);
+
+  // A list name takes the whole list back out. Checked first: subscribing to a
+  // list is one action and unsubscribing from it should be one action too,
+  // rather than the operator deleting forty feeds by hand.
+  const asList = resolveList(request.target);
+  if (asList) {
+    const mine = feeds.filter((f) => listOf(f) === asList.name);
+    if (!mine.length) {
+      fail(danger(`✗ you have no feeds from "${asList.name}"`));
+      return 1;
+    }
+    try { saveFeeds(feeds.filter((f) => listOf(f) !== asList.name), env); }
+    catch (e) { fail(danger(`✗ can't write ${opmlFile(env)}: ${e.message}`)); return 1; }
+    if (request.json) { out(JSON.stringify({ removed: mine, list: asList.name }, null, 2)); return 0; }
+    out(`${acid("✓ ")}unsubscribed from ${bone(asList.name)} ${ash(`— ${mine.length} feed${mine.length === 1 ? "" : "s"}`)}`);
+    return 0;
+  }
+
   const feed = findFeed(feeds, request.target);
   if (!feed) {
     fail(danger(`✗ no feed named "${request.target}"`));

package/src/rss-ui.mjs

@@ -18,10 +18,21 @@ import {
   ago,
   collectNews,
   findFeed,
+  newsCommand,
   readingList,
+  resolveVerb,
   searchFeeds,
 } from "./news.mjs";
 
+/**
+ * Verbs `/rss` hands straight to `moshcode news`.
+ *
+ * Everything that manages the subscription list rather than reading it. They
+ * print and exit, so they work with no TTY — which is why this runs before the
+ * interactive-terminal check.
+ */
+const MANAGEMENT_VERBS = new Set(["add", "rm", "list", "lists", "find", "sources", "export", "open"]);
+
 const ESC = {
   altOn: "\x1b[?1049h", altOff: "\x1b[?1049l",
   hideCursor: "\x1b[?25l", showCursor: "\x1b[?25h",
@@ -305,14 +316,37 @@ export async function rssUi(argv = [], deps = {}) {
     write = (s) => process.stdout.write(`${s}\n`),
   } = deps;
 
+  const args = (Array.isArray(argv) ? argv : []).map(String);
+  const words = args.filter((a) => !a.startsWith("-"));
+  const verb = resolveVerb(words[0]);
+
+  // Managing subscriptions is the same work under either name, and `/rss add
+  // <url>` is what people type — the reader is where you are when you decide to
+  // subscribe to something. Handing these to newsCommand rather than reading
+  // them as a search is the whole difference between `/rss add <url>` working
+  // and it silently opening a reader on the literal phrase "add <url>".
+  //
+  // `search` is deliberately not among them. On `/news` it searches headlines;
+  // here it searches the published lists for feeds to add, because a reader
+  // already has `/` for searching what it is showing.
+  if (verb && MANAGEMENT_VERBS.has(verb)) {
+    return newsCommand(args, { fetchImpl, openUrl, env, out: write, fail: write });
+  }
+  if (verb === "search") {
+    const keywords = words.slice(1).join(" ").trim();
+    if (!keywords) { write("usage: moshcode rss search <keyword[,keyword…]>"); return 1; }
+    return newsCommand(["find", ...words.slice(1)], { fetchImpl, openUrl, env, out: write, fail: write });
+  }
+
   if (!stdin.isTTY || !stdout.isTTY) {
     write("moshcode rss needs an interactive terminal — try `moshcode news`");
     return 1;
   }
 
   // A query on the command line (`moshcode rss tariffs`) opens straight into
-  // the search, which is the same shape `/news <keyword>` has.
-  const query = argv.filter((a) => !String(a).startsWith("-")).join(" ").trim();
+  // the search, which is the same shape `/news <keyword>` has. `latest` is the
+  // verb for "no query", so it is dropped rather than searched for.
+  const query = (verb === "latest" ? "" : words.join(" ")).trim();
   const list = readingList(env);
 
   const state = {

package/src/settings-sync.mjs

@@ -58,6 +58,12 @@ export const MAX_TOTAL_BYTES = 256 * 1024;
 export const SYNCED_FILES = [
   { path: "aliases.json", json: true, label: "pit aliases" },
   { path: "herd/rules.json", json: true, label: "herd state rules" },
+  // OPML rather than JSON, so `json: false`: it is the interchange format every
+  // feed reader already imports and exports, which is the whole reason a feed
+  // list is worth carrying between machines at all. Written by `tcfeed rss add`
+  // and read by nothing here — moshcode's interest in it begins and ends with
+  // moving it, and a file this does not parse cannot be broken by this.
+  { path: "feeds.opml", json: false, label: "rss feeds" },
 ];
 
 /**
@@ -349,7 +355,7 @@ function endpoint(creds) {
  * code; a thrown network error inside the pit's dispatch loop would take the
  * prompt down instead, which is a lost session over a dropped wifi connection.
  */
-async function request(method, route, { creds, body = null, fetchImpl = fetch, timeoutMs = 20_000 } = {}) {
+async function attempt(method, route, { creds, body, fetchImpl, timeoutMs }) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
@@ -374,6 +380,36 @@ async function request(method, route, { creds, body = null, fetchImpl = fetch, t
   }
 }
 
+/**
+ * Retried only where a retry can be right: the app not answering.
+ *
+ * 502, 503, 504 and a dead socket say nothing about the request — the platform
+ * returned them without the app seeing it, so the same bytes sent a second
+ * later are as likely to work as they were the first time. Every other status
+ * is an answer: 400 will be 400 again, 401 wants `/login`, and 409 is another
+ * machine having saved first, which retrying would only re-ask.
+ *
+ * Unretried, one blip is a visible failure — and it looked frequent because
+ * every one of them was. `/save` had no retry at all while the scan workflow
+ * this same repository ships retries `npm install` three times for precisely
+ * this reasoning.
+ *
+ * Safe to repeat a PUT because the write is conditional: `ifRevision` pins the
+ * revision the caller last agreed on, so a retry that lands after a first
+ * attempt secretly succeeded is refused with 409 rather than writing twice.
+ */
+const RETRY_STATUS = new Set([0, 502, 503, 504]);
+const RETRY_BACKOFF_MS = [400, 1200];
+
+async function request(method, route, { creds, body = null, fetchImpl = fetch, timeoutMs = 20_000, retries = RETRY_BACKOFF_MS.length } = {}) {
+  let last;
+  for (let i = 0; ; i++) {
+    last = await attempt(method, route, { creds, body, fetchImpl, timeoutMs });
+    if (!RETRY_STATUS.has(last.status) || i >= retries) return last;
+    await new Promise((r) => setTimeout(r, RETRY_BACKOFF_MS[i] ?? RETRY_BACKOFF_MS.at(-1)));
+  }
+}
+
 export const pushSnapshot = (snapshot, { ifRevision = null, ...opts }) =>
   request("PUT", "/api/settings", { ...opts, body: { snapshot, ifRevision } });