@ouro.bot/cli 0.1.0-alpha.85 → 0.1.0-alpha.850

package/deploy/unraid/sanctuary.ouro/mcp/media-mcp.mjs

@@ -0,0 +1,1072 @@
+#!/usr/bin/env node
+// Sanctuary media MCP server — the Mendelow Cloud Butler's media surface.
+//
+// Design authority: the Butler's own tool-surface spec (Telegram msgs 1700-1713, 2026-09-19).
+// Two hard constraints it set, enforced here:
+//   1. Anything deterministic lives in the tool, not in the agent's reasoning.
+//   2. No "call A, parse it, build B" — every return payload carries the cross-reference
+//      fields needed to answer the obvious follow-up without a second call.
+//
+// Protocol: JSON-RPC 2.0 over stdio, newline framed, MCP 2024-11-05.
+
+import { readFileSync } from "node:fs"
+import { pathToFileURL } from "node:url"
+
+const CRED_PATH = process.env.SANCTUARY_MEDIA_CREDENTIALS ?? "/home/ouro/AgentBundles/sanctuary.ouro/mcp/media-credentials.json"
+
+// Credentials are host-specific and deliberately NOT packaged. A fresh install
+// has none, and the server must still start and list its tools — otherwise the
+// whole MCP server fails to connect and the agent silently loses the surface.
+// Missing credentials become a named, reportable per-call failure instead.
+let cred = null
+let credError = null
+try {
+  cred = JSON.parse(readFileSync(CRED_PATH, "utf8"))
+} catch (e) {
+  credError = `Media credentials are unavailable at ${CRED_PATH} (${e.code ?? e.message}). The media tools cannot reach Jellyseerr/Sonarr/Radarr/Prowlarr until that file is created.`
+}
+
+const SEERR = cred?.jellyseerr ?? { url: "", apiKey: "" }
+const SONARR = cred?.sonarr ?? { url: "", apiKey: "" }
+const RADARR = cred?.radarr ?? { url: "", apiKey: "" }
+const PROWLARR = cred?.prowlarr ?? { url: "", apiKey: "" }
+const JELLYFIN_WEB = cred?.jellyfinWebUrl ?? "https://media.mendelow.cloud"
+// Optional: when the credential file carries { jellyfin: { url, apiKey } } the library
+// is searched in Jellyfin too. Absent, title resolution uses Sonarr and Radarr only.
+const JELLYFIN = cred?.jellyfin ?? { url: "", apiKey: "" }
+
+const TIMEOUT_MS = 45_000
+
+// ---------------------------------------------------------------- http helpers
+
+async function req(base, path, { key, header = "X-Api-Key", method = "GET", body, query } = {}) {
+  let url = `${base}${path}`
+  if (query) {
+    const parts = Object.entries(query)
+      .filter(([, v]) => v !== undefined && v !== null && v !== "")
+      // encodeURIComponent, not URLSearchParams: Jellyseerr rejects '+' for spaces.
+      .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+    if (parts.length) url += `?${parts.join("&")}`
+  }
+  const headers = { [header]: key, Accept: "application/json" }
+  if (body !== undefined) headers["Content-Type"] = "application/json"
+  let res
+  try {
+    res = await fetch(url, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(TIMEOUT_MS) })
+  } catch (e) {
+    throw new ServiceError(`${serviceOf(base)}_unreachable`, `${serviceOf(base)} did not respond: ${e.name === "TimeoutError" ? "timeout" : e.message}`)
+  }
+  if (!res.ok) {
+    const text = await res.text().catch(() => "")
+    throw new ServiceError(`${serviceOf(base)}_http_${res.status}`, `${serviceOf(base)} returned ${res.status}${text ? `: ${text.slice(0, 200)}` : ""}`)
+  }
+  if (res.status === 204) return null
+  return res.json()
+}
+
+function serviceOf(base) {
+  if (base === SEERR.url) return "jellyseerr"
+  if (base === SONARR.url) return "sonarr"
+  if (base === RADARR.url) return "radarr"
+  if (base === PROWLARR.url) return "prowlarr"
+  if (JELLYFIN.url && base === JELLYFIN.url) return "jellyfin"
+  return "service"
+}
+
+class ServiceError extends Error {
+  constructor(code, message) { super(message); this.code = code }
+}
+
+const seerr = (path, opts = {}) => req(SEERR.url, `/api/v1${path}`, { key: SEERR.apiKey, ...opts })
+// Long enough that an ordinary slow start is not called dead, short enough that
+// nobody waits a day for a release that was never going to arrive.
+const STALL_AFTER_HOURS = 6
+
+const sonarr = (path, opts = {}) => req(SONARR.url, `/api/v3${path}`, { key: SONARR.apiKey, ...opts })
+const radarr = (path, opts = {}) => req(RADARR.url, `/api/v3${path}`, { key: RADARR.apiKey, ...opts })
+const prowlarr = (path, opts = {}) => req(PROWLARR.url, `/api/v1${path}`, { key: PROWLARR.apiKey, ...opts })
+
+// ------------------------------------------------------------------ mapping
+
+// Jellyseerr media status codes.
+const MEDIA_STATUS = { 1: "unknown", 2: "pending", 3: "processing", 4: "partially_available", 5: "available" }
+const REQUEST_STATUS = { 1: "pending_approval", 2: "approved", 3: "declined", 4: "failed" }
+
+const TMDB_GENRES = {
+  28: "Action", 12: "Adventure", 16: "Animation", 35: "Comedy", 80: "Crime", 99: "Documentary",
+  18: "Drama", 10751: "Family", 14: "Fantasy", 36: "History", 27: "Horror", 10402: "Music",
+  9648: "Mystery", 10749: "Romance", 878: "Science Fiction", 10770: "TV Movie", 53: "Thriller",
+  10752: "War", 37: "Western", 10759: "Action & Adventure", 10762: "Kids", 10763: "News",
+  10764: "Reality", 10765: "Sci-Fi & Fantasy", 10766: "Soap", 10767: "Talk", 10768: "War & Politics",
+}
+
+function genreNames(item) {
+  const ids = item.genreIds ?? (item.genres ?? []).map((g) => g.id)
+  return ids.map((id) => TMDB_GENRES[id]).filter(Boolean)
+}
+
+function shelfItem(item) {
+  const kind = item.mediaType === "tv" ? "series" : item.mediaType === "movie" ? "movie" : (item.firstAirDate ? "series" : "movie")
+  const date = item.releaseDate ?? item.firstAirDate ?? ""
+  const info = item.mediaInfo ?? {}
+  const status = MEDIA_STATUS[info.status] ?? "not_on_shelf"
+  return {
+    title: item.title ?? item.name ?? null,
+    year: date ? Number(date.slice(0, 4)) : null,
+    kind,
+    tmdb_id: item.id ?? null,
+    tvdb_id: info.tvdbId ?? null,
+    genres: genreNames(item),
+    overview: typeof item.overview === "string" ? item.overview.slice(0, 400) : null,
+    // The two fields that stop a second call:
+    on_shelf: status === "available" || status === "partially_available",
+    shelf_state: status,
+    request_state: info.status ? (status === "available" ? "available" : status) : "never_requested",
+    sonarr_id: info.externalServiceId ?? null,
+    radarr_id: kind === "movie" ? (info.externalServiceId ?? null) : null,
+    poster_path: item.posterPath ? `https://image.tmdb.org/t/p/w500${item.posterPath}` : null,
+    vote_average: item.voteAverage ?? null,
+  }
+}
+
+// ------------------------------------------------------- title resolution
+//
+// One resolver for every tool that takes a title. A title typed from memory is
+// rarely the catalogue's title: "chef" is "The Chef Show", "chef shwo" is a typo.
+// The 2026-09-29 failure was a library search that required the whole title and
+// so reported a tracked series as nonexistent. Matching is therefore partial and
+// typo-tolerant, in-library candidates always come first, and the TVDB/TMDB
+// lookup only runs when the library has nothing.
+
+export function normalizeTitle(s) {
+  return String(s ?? "")
+    .normalize("NFKD").replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase().replace(/&/g, " and ").replace(/['\u2019]/g, "")
+    .replace(/[^a-z0-9]+/g, " ").trim().replace(/^the /, "")
+}
+
+// Optimal-string-alignment distance: an adjacent swap ("shwo") costs one edit.
+function editDistance(a, b) {
+  const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)])
+  for (let j = 1; j <= b.length; j += 1) d[0][j] = j
+  for (let i = 1; i <= a.length; i += 1) {
+    for (let j = 1; j <= b.length; j += 1) {
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1)
+    }
+  }
+  return d[a.length][b.length]
+}
+
+const MATCH_RANK = { exact: 0, prefix: 1, token: 2, fuzzy: 3 }
+
+// Returns "exact" | "prefix" | "token" | "fuzzy" | null.
+export function matchKind(query, title) {
+  const nq = normalizeTitle(query)
+  const nt = normalizeTitle(title)
+  if (!nq || !nt) return null
+  if (nq === nt) return "exact"
+  if (nt.startsWith(nq)) return "prefix"
+  const qt = nq.split(" ")
+  const tt = nt.split(" ")
+  if (qt.every((q) => tt.some((t) => t === q || (q.length >= 3 && t.includes(q))))) return "token"
+  if (nq.length >= 3 && nt.includes(nq)) return "token"
+  // Typos. Short tokens must be exact; a 4-letter token may only be fuzzy when
+  // another query token already matched exactly, so "chef" never drifts to "chess".
+  const exactHit = (q) => tt.includes(q)
+  const fuzzyHit = (q) => tt.some((t) => {
+    if (q.length < 4 || t.length < 4) return false
+    const tol = q.length >= 8 ? 2 : 1
+    return editDistance(q, t) <= tol
+  })
+  const anyExact = qt.some(exactHit)
+  const ok = qt.every((q) => exactHit(q) || (fuzzyHit(q) && (q.length >= 5 || (qt.length > 1 && anyExact))))
+  return ok ? "fuzzy" : null
+}
+
+function rankCandidates(term, items) {
+  return items
+    .map((c) => ({ ...c, match: matchKind(term, c.title) }))
+    .filter((c) => c.match)
+    .sort((x, y) => MATCH_RANK[x.match] - MATCH_RANK[y.match]
+      || Math.abs(normalizeTitle(x.title).length - normalizeTitle(term).length) - Math.abs(normalizeTitle(y.title).length - normalizeTitle(term).length))
+}
+
+const libraryCandidate = (kind, i) => ({ kind, source: kind === "series" ? "sonarr" : "radarr", service_id: i.id, title: i.title,
+  year: i.year ?? null, tmdb_id: i.tmdbId ?? null, tvdb_id: i.tvdbId ?? null, in_library: true })
+
+// Every library item whose title matches, best first. Sonarr and Radarr are the
+// source of truth for what is tracked; Jellyfin (when configured) adds what is
+// on the shelf and marks items it shares with them.
+export async function findLibraryCandidates(term, kind = "any") {
+  const jobs = []
+  if (kind !== "movie") jobs.push(sonarr("/series").then((l) => (Array.isArray(l) ? l : []).map((i) => libraryCandidate("series", i))))
+  if (kind !== "series") jobs.push(radarr("/movie").then((l) => (Array.isArray(l) ? l : []).map((i) => libraryCandidate("movie", i))))
+  // One service being down must not hide the other's matches; say which failed.
+  const settled = await Promise.allSettled(jobs)
+  const notes = []
+  for (const r of settled) if (r.status === "rejected") notes.push(`library_unavailable: ${r.reason?.message ?? r.reason}`)
+  if (settled.every((r) => r.status === "rejected")) throw settled[0].reason
+  let items = settled.flatMap((r) => (r.status === "fulfilled" ? r.value : []))
+  if (JELLYFIN.url && JELLYFIN.apiKey) {
+    try {
+      const body = await req(JELLYFIN.url, "/Items", { key: JELLYFIN.apiKey, header: "X-Emby-Token",
+        query: { searchTerm: term, IncludeItemTypes: kind === "series" ? "Series" : kind === "movie" ? "Movie" : "Series,Movie", Recursive: true, Limit: 25 } })
+      for (const j of body?.Items ?? []) {
+        const k = j.Type === "Series" ? "series" : "movie"
+        const tmdb = Number(j.ProviderIds?.Tmdb ?? j.ProviderIds?.tmdb) || null
+        const twin = items.find((i) => i.kind === k && ((tmdb && i.tmdb_id === tmdb) || normalizeTitle(i.title) === normalizeTitle(j.Name)))
+        if (twin) twin.in_jellyfin = true
+        else items.push({ kind: k, source: "jellyfin", service_id: null, jellyfin_id: j.Id ?? null, title: j.Name, year: j.ProductionYear ?? null,
+          tmdb_id: tmdb, tvdb_id: null, in_library: true, in_jellyfin: true })
+      }
+    } catch (e) {
+      notes.push(`jellyfin_unavailable: ${e.message}`)
+    }
+  }
+  const ranked = rankCandidates(term, items)
+  if (notes.length) Object.defineProperty(ranked, "notes", { value: notes, enumerable: false })
+  return ranked
+}
+
+// The catalogue fallback, used only when the library has no candidate. These are
+// titles Sonarr/Radarr could add, so they are labelled not_in_library.
+export async function lookupCandidates(term, kind = "any") {
+  const out = []
+  const jobs = []
+  if (kind !== "movie") jobs.push(sonarr("/series/lookup", { query: { term } }).then((l) => (Array.isArray(l) ? l : []).forEach((i) => out.push({ kind: "series", source: "sonarr_lookup", service_id: i.id ?? null, title: i.title, year: i.year ?? null, tmdb_id: i.tmdbId ?? null, tvdb_id: i.tvdbId ?? null, in_library: Boolean(i.id), match: matchKind(term, i.title) ?? "lookup" }))).catch(() => {}))
+  if (kind !== "series") jobs.push(radarr("/movie/lookup", { query: { term } }).then((l) => (Array.isArray(l) ? l : []).forEach((i) => out.push({ kind: "movie", source: "radarr_lookup", service_id: i.id ?? null, title: i.title, year: i.year ?? null, tmdb_id: i.tmdbId ?? null, tvdb_id: null, in_library: Boolean(i.id), match: matchKind(term, i.title) ?? "lookup" }))).catch(() => {}))
+  await Promise.all(jobs)
+  return out.sort((x, y) => (MATCH_RANK[x.match] ?? 4) - (MATCH_RANK[y.match] ?? 4)).slice(0, 10)
+}
+
+// In-library candidates first; the lookup fallback only when there are none.
+export async function resolveTitle(term, kind = "any") {
+  const library = await findLibraryCandidates(term, kind)
+  if (library.length) return { library_matches: library, lookup_candidates: [], not_in_library: false, notes: library.notes ?? [] }
+  const lookup = (await lookupCandidates(term, kind)).filter((c) => !c.in_library).map((c) => ({ ...c, not_in_library: true }))
+  return { library_matches: [], lookup_candidates: lookup, not_in_library: true, notes: [] }
+}
+
+// ------------------------------------------------------------- tool: search
+
+export async function mediaSearch(a) {
+  const kind = a.kind ?? "any"
+  const limit = Math.min(Math.max(a.limit ?? 12, 1), 20)
+  const onShelf = a.on_shelf // true | false | undefined(any)
+  let raw = []
+  let source
+
+  if (a.query) {
+    source = "title_search"
+    const body = await seerr("/search", { query: { query: a.query, page: 1 } })
+    raw = body.results ?? []
+  } else {
+    source = "discover"
+    const keywordIds = []
+    for (const kw of a.keywords ?? []) {
+      const hit = await seerr("/search/keyword", { query: { query: kw, page: 1 } })
+      const exact = (hit.results ?? []).find((k) => k.name.toLowerCase() === kw.toLowerCase()) ?? (hit.results ?? [])[0]
+      if (exact) keywordIds.push(exact.id)
+    }
+    const genreIds = (a.genres ?? [])
+      .map((name) => Number(Object.entries(TMDB_GENRES).find(([, v]) => v.toLowerCase() === String(name).toLowerCase())?.[0]))
+      .filter((n) => Number.isFinite(n))
+    const [yMin, yMax] = a.year_range ?? []
+    const paths = kind === "series" ? ["/discover/tv"] : kind === "movie" ? ["/discover/movies"] : ["/discover/movies", "/discover/tv"]
+    // One page of discover is ~20 popular titles, of which only a couple are
+    // usually on this shelf — answering "what cozy autumn films do we own?" from
+    // that reads as though the shelf is nearly empty. When the caller filters by
+    // shelf state, walk further pages until enough matches accumulate.
+    const maxPages = onShelf === undefined ? 1 : 5
+    for (const p of paths) {
+      const isTv = p.endsWith("/tv")
+      for (let page = 1; page <= maxPages; page += 1) {
+        const q = { page, sortBy: a.sort === "release_year" ? "primary_release_date.desc" : "popularity.desc" }
+        if (genreIds.length) q.genre = genreIds.join(",")
+        if (keywordIds.length) q.keywords = keywordIds.join(",")
+        if (yMin) q[isTv ? "firstAirDateGte" : "primaryReleaseDateGte"] = `${yMin}-01-01`
+        if (yMax) q[isTv ? "firstAirDateLte" : "primaryReleaseDateLte"] = `${yMax}-12-31`
+        const body = await seerr(p, { query: q })
+        const results = body.results ?? []
+        raw.push(...results.map((r) => ({ ...r, mediaType: isTv ? "tv" : "movie" })))
+        const matchesSoFar = raw
+          .map((r) => (r.mediaInfo?.status === 5 || r.mediaInfo?.status === 4))
+          .filter((hit) => hit === (onShelf === true)).length
+        if (results.length === 0 || page >= (body.totalPages ?? 1) || matchesSoFar >= limit) break
+      }
+    }
+  }
+
+  // Partial and typo-tolerant library match, so a half-remembered title still
+  // finds what is tracked. Lookup candidates appear only when the library has none.
+  const resolution = a.query ? await resolveTitle(a.query, kind).catch((e) => ({ library_matches: [], lookup_candidates: [], not_in_library: null, notes: [`title_resolution_failed: ${e.message}`] })) : null
+
+  let items = raw.filter((r) => r.mediaType !== "person").map(shelfItem)
+  if (kind !== "any") items = items.filter((i) => i.kind === kind)
+  if (a.year_range) {
+    const [lo, hi] = a.year_range
+    items = items.filter((i) => i.year && (!lo || i.year >= lo) && (!hi || i.year <= hi))
+  }
+  if (onShelf === true) items = items.filter((i) => i.on_shelf)
+  if (onShelf === false) items = items.filter((i) => !i.on_shelf)
+  if (a.sort === "release_year") items.sort((x, y) => (y.year ?? 0) - (x.year ?? 0))
+
+  return {
+    source,
+    matched: items.length,
+    items: items.slice(0, limit),
+    ...(resolution ? { library_matches: resolution.library_matches.slice(0, 10), lookup_candidates: resolution.lookup_candidates, notes: resolution.notes } : {}),
+    applied_filters: { kind, year_range: a.year_range ?? null, genres: a.genres ?? [], keywords: a.keywords ?? [], on_shelf: onShelf ?? "any" },
+    // So the agent never claims something is missing when the filter caused it:
+    note: resolution?.library_matches.length ? "library_matches lists items already tracked in Sonarr/Radarr (or on the Jellyfin shelf) whose titles match, best first. Offer these before anything else."
+      : items.length === 0 && resolution?.lookup_candidates.length ? "Nothing in the library matches; lookup_candidates are TVDB/TMDB titles that are not in the library."
+      : items.length === 0 ? "No matches for these filters. Loosen year_range/genres/keywords before concluding the shelf lacks it." : null,
+  }
+}
+
+// ------------------------------------------------------------ tool: request
+
+// Resolve by TMDB id against the title itself rather than scanning the request
+// list: this household has over a thousand requests, so a page-limited scan
+// silently misses older ones and would file a duplicate.
+async function findExistingRequest(tmdbId, kind) {
+  const kinds = kind ? [kind] : ["movie", "series"]
+  for (const k of kinds) {
+    let detail
+    try {
+      detail = await seerr(`/${k === "series" ? "tv" : "movie"}/${tmdbId}`)
+    } catch {
+      continue
+    }
+    const info = detail?.mediaInfo
+    if (!info) continue
+    const requests = info.requests ?? []
+    const latest = requests.length ? requests[requests.length - 1] : null
+    return {
+      id: latest?.id ?? null,
+      status: latest?.status ?? null,
+      createdAt: latest?.createdAt ?? null,
+      type: k === "series" ? "tv" : "movie",
+      media: { ...info, tmdbId, title: detail.title ?? detail.name ?? null },
+      hasRequest: requests.length > 0,
+    }
+  }
+  return null
+}
+
+async function mediaRequest(a) {
+  let tmdbId = a.tmdb_id
+  let kind = a.kind ?? "movie"
+  let resolvedTitle = a.title ?? null
+  let resolvedYear = a.year ?? null
+
+  if (!tmdbId) {
+    if (!a.title) throw new ServiceError("bad_arguments", "media_request needs tmdb_id, or title (year optional).")
+    const body = await seerr("/search", { query: { query: a.title, page: 1 } })
+    let cands = (body.results ?? []).filter((r) => r.mediaType === "movie" || r.mediaType === "tv")
+    if (a.kind) cands = cands.filter((r) => (a.kind === "series" ? r.mediaType === "tv" : r.mediaType === "movie"))
+    if (a.year) cands = cands.filter((r) => ((r.releaseDate ?? r.firstAirDate ?? "").slice(0, 4)) === String(a.year))
+    const pick = cands[0]
+    if (!pick) {
+      return { resolved: false, reason: "no_tmdb_match", searched: { title: a.title, year: a.year ?? null, kind: a.kind ?? "any" },
+               human_action_required: true, human_action_reason: `No TMDB match for "${a.title}"${a.year ? ` (${a.year})` : ""}. Check the title or give a year.` }
+    }
+    tmdbId = pick.id
+    kind = pick.mediaType === "tv" ? "series" : "movie"
+    resolvedTitle = pick.title ?? pick.name
+    resolvedYear = Number((pick.releaseDate ?? pick.firstAirDate ?? "").slice(0, 4)) || null
+  }
+
+  const existing = await findExistingRequest(tmdbId, kind)
+  if (existing?.hasRequest) {
+    const shelf = MEDIA_STATUS[existing.media?.status] ?? "unknown"
+    return {
+      resolved: true, title: resolvedTitle ?? existing.media?.title ?? null, year: resolvedYear, kind, tmdb_id: tmdbId,
+      request_id: `jellyseerr:${existing.id}`,
+      approval_state: "already_requested",
+      duplicate_of: `jellyseerr:${existing.id}`,
+      jellyseerr_status: REQUEST_STATUS[existing.status] ?? "unknown",
+      shelf_state: shelf,
+      submitted_at: existing.createdAt,
+      tvdb_id: existing.media?.tvdbId ?? null,
+      sonarr_id: kind === "series" ? (existing.media?.externalServiceId ?? null) : null,
+      radarr_id: kind === "movie" ? (existing.media?.externalServiceId ?? null) : null,
+      note: shelf === "available" ? "Already on the shelf." : "Already requested; use media_request_status to see why it has not landed.",
+    }
+  }
+
+  const payload = { mediaType: kind === "series" ? "tv" : "movie", mediaId: tmdbId }
+  if (kind === "series") {
+    payload.seasons = a.season_number ? [a.season_number] : "all"
+  }
+  const created = await seerr("/request", { method: "POST", body: payload })
+  return {
+    resolved: true, title: resolvedTitle, year: resolvedYear, kind, tmdb_id: tmdbId,
+    request_id: `jellyseerr:${created.id}`,
+    approval_state: REQUEST_STATUS[created.status] ?? "submitted",
+    duplicate_of: null,
+    jellyseerr_status: REQUEST_STATUS[created.status] ?? "submitted",
+    shelf_state: MEDIA_STATUS[created.media?.status] ?? "processing",
+    submitted_at: created.createdAt,
+    tvdb_id: created.media?.tvdbId ?? null,
+    sonarr_id: kind === "series" ? (created.media?.externalServiceId ?? null) : null,
+    radarr_id: kind === "movie" ? (created.media?.externalServiceId ?? null) : null,
+    seasons_requested: kind === "series" ? (a.season_number ? [a.season_number] : "all") : null,
+    note: "Submitted. The indexer hunt runs next; media_request_status will show whether a release was grabbed.",
+  }
+}
+
+// -------------------------------------------------- acquisition chain health
+
+// The failure that stalled this house for three weeks: Prowlarr had zero indexers,
+// so Sonarr reported "0 active indexers" and every request sat at "requested"
+// forever. That must be a first-class, named answer — never something the agent
+// has to infer from an empty release list.
+async function chainHealth() {
+  const out = { indexers: { total: 0, enabled: 0, failing: [], ok: [] }, apps: [], problems: [], healthy: true }
+  try {
+    const list = await prowlarr("/indexer")
+    out.indexers.total = list.length
+    out.indexers.enabled = list.filter((i) => i.enable).length
+    const status = await prowlarr("/indexerstatus").catch(() => [])
+    const disabled = new Set((status ?? []).map((s) => s.indexerId))
+    for (const i of list) {
+      if (!i.enable) continue
+      ;(disabled.has(i.id) ? out.indexers.failing : out.indexers.ok).push(i.name)
+    }
+    const health = await prowlarr("/health").catch(() => [])
+    for (const h of health ?? []) {
+      if (h.type === "error" && /indexer/i.test(h.source ?? "")) out.problems.push({ service: "prowlarr", message: h.message })
+    }
+    out.apps = (await prowlarr("/applications").catch(() => [])).map((x) => ({ name: x.name, sync: x.syncLevel }))
+  } catch (e) {
+    out.problems.push({ service: "prowlarr", message: e.message })
+  }
+
+  if (out.indexers.total === 0) {
+    out.healthy = false
+    out.problems.push({ service: "prowlarr", message: "Prowlarr has zero indexers configured. Nothing can ever be found or downloaded until indexers are added." })
+  } else if (out.indexers.ok.length === 0) {
+    out.healthy = false
+    out.problems.push({ service: "prowlarr", message: "Every enabled indexer is currently failing. Searches will return nothing." })
+  }
+  if (out.apps.length === 0) {
+    out.healthy = false
+    out.problems.push({ service: "prowlarr", message: "Prowlarr is not syncing to Sonarr/Radarr, so they have no working indexers." })
+  }
+
+  for (const [name, call] of [["sonarr", sonarr], ["radarr", radarr]]) {
+    try {
+      const h = await call("/health")
+      for (const item of h ?? []) {
+        if (/indexer/i.test(item.source ?? "") && (item.type === "error" || /unavailable/i.test(item.message ?? ""))) {
+          out.problems.push({ service: name, message: item.message })
+          if (/all/i.test(item.message ?? "")) out.healthy = false
+        }
+      }
+    } catch (e) { out.problems.push({ service: name, message: e.message }) }
+  }
+  return out
+}
+
+// --------------------------------------------------- tool: request status
+
+async function resolveTarget(a) {
+  if (a.tmdb_id) {
+    const r = await findExistingRequest(a.tmdb_id, a.kind)
+    if (r?.hasRequest) return r
+  }
+  if (a.request_id) {
+    const id = Number(String(a.request_id).replace(/^jellyseerr:/, ""))
+    if (Number.isFinite(id)) {
+      try { return await seerr(`/request/${id}`) } catch { /* fall through to title */ }
+    }
+  }
+  if (a.title) {
+    const body = await seerr("/search", { query: { query: a.title, page: 1 } })
+    // Only titles Jellyseerr already knows about can have a request behind them.
+    for (const pick of (body.results ?? []).filter((r) => r.mediaInfo)) {
+      const found = await findExistingRequest(pick.id, pick.mediaType === "tv" ? "series" : "movie")
+      if (found?.hasRequest) return found
+    }
+    // Jellyseerr's own search missed it: try the partial/typo-tolerant library
+    // match, and follow its best candidate back to a request by TMDB id.
+    const best = (await findLibraryCandidates(a.title).catch(() => [])).find((c) => c.tmdb_id)
+    if (best) {
+      const found = await findExistingRequest(best.tmdb_id, best.kind)
+      if (found?.hasRequest) return found
+    }
+  }
+  return null
+}
+
+export async function mediaRequestStatus(a) {
+  const request = await resolveTarget(a)
+  if (!request) {
+    const resolution = a.title ? await resolveTitle(a.title).catch(() => null) : null
+    return { found: false, reason: "no_matching_request",
+             searched: { request_id: a.request_id ?? null, tmdb_id: a.tmdb_id ?? null, title: a.title ?? null },
+             ...(resolution ? { library_matches: resolution.library_matches.slice(0, 10), lookup_candidates: resolution.lookup_candidates,
+                                note: resolution.library_matches.length ? "Not requested through Jellyseerr, but these titles are already in the library. Use media_search_now with the service_id to act on one." : undefined } : {}),
+             diagnosis: { stuck_stage: "request", stuck_reason: "never_requested",
+                          likely_fix: "Submit it with media_request.", human_action_required: false } }
+  }
+
+  const kind = request.type === "tv" ? "series" : "movie"
+  const media = request.media ?? {}
+  const shelf = MEDIA_STATUS[media.status] ?? "unknown"
+  const svcId = media.externalServiceId ?? null
+
+  const result = {
+    found: true,
+    request: {
+      id: `jellyseerr:${request.id}`,
+      kind,
+      tmdb_id: media.tmdbId ?? null,
+      tvdb_id: media.tvdbId ?? null,
+      jellyseerr_status: REQUEST_STATUS[request.status] ?? "unknown",
+      shelf_state: shelf,
+      submitted_at: request.createdAt,
+      sonarr_id: kind === "series" ? svcId : null,
+      radarr_id: kind === "movie" ? svcId : null,
+    },
+    search: null, download: null, file: null, chain: null, diagnosis: null,
+  }
+
+  let entity = null, queueRecs = [], history = []
+  try {
+    if (kind === "series" && svcId) {
+      entity = await sonarr(`/series/${svcId}`)
+      const q = await sonarr("/queue", { query: { pageSize: 200, includeSeries: true } })
+      queueRecs = (q.records ?? []).filter((r) => r.seriesId === svcId)
+      history = await sonarr("/history/series", { query: { seriesId: svcId } }).catch(() => [])
+      result.request.title = entity.title
+      result.file = { on_shelf: (entity.statistics?.episodeFileCount ?? 0) > 0,
+                      episodes_on_disk: entity.statistics?.episodeFileCount ?? 0,
+                      episodes_total: entity.statistics?.episodeCount ?? 0,
+                      size_bytes: entity.statistics?.sizeOnDisk ?? 0,
+                      path: entity.path ?? null }
+    } else if (kind === "movie" && svcId) {
+      entity = await radarr(`/movie/${svcId}`)
+      const q = await radarr("/queue", { query: { pageSize: 200 } })
+      queueRecs = (q.records ?? []).filter((r) => r.movieId === svcId)
+      history = await radarr("/history/movie", { query: { movieId: svcId } }).catch(() => [])
+      result.request.title = entity.title
+      result.file = { on_shelf: Boolean(entity.hasFile), size_bytes: entity.sizeOnDisk ?? 0, path: entity.path ?? null }
+    }
+  } catch (e) {
+    result.chain_error = e.message
+  }
+
+  const grabs = (history ?? []).filter((h) => h.eventType === "grabbed")
+  result.search = {
+    grab_attempts: grabs.length,
+    last_grab_at: grabs[0]?.date ?? null,
+    last_grab_title: grabs[0]?.sourceTitle ?? null,
+    monitored: entity ? Boolean(entity.monitored) : null,
+  }
+  result.download = computeDownloadState(queueRecs, Date.now())
+
+  const chain = await chainHealth()
+  result.chain = chain
+  result.diagnosis = diagnose({ shelf, result, chain, entity, kind })
+  return result
+}
+
+// The deterministic core, split out so it can be tested without a live
+// Sonarr/Radarr. `computeDownloadState` and `diagnose` are the whole reason the
+// media surface can answer "why hasn't this downloaded" without the agent
+// guessing, and D-013 (a stalled download read as progress) shipped verified
+// only in production because there was no seam to test them through.
+//
+// A season pack shows up as one queue row per episode, all sharing one
+// downloadId. Summing rows would report a 45 GB pack as 450 GB, so size and
+// "how many downloads" are counted per distinct download, not per row. A
+// torrent that has not moved a byte since it was grabbed is dead, not slow:
+// Radarr reports trackedDownloadStatus "ok" for these indefinitely, so
+// progress is measured against age rather than trusted from the row.
+// The one stall rule: nothing downloaded yet, and older than the stall window.
+export function isStalledRow(r, nowMs) {
+  return (r.size ?? 0) > 0 && (r.sizeleft ?? 0) >= (r.size ?? 0) && Boolean(r.added)
+    && (nowMs - Date.parse(r.added)) / 3_600_000 >= STALL_AFTER_HOURS
+}
+
+export function computeDownloadState(queueRecs, nowMs) {
+  const byDownload = new Map()
+  for (const r of queueRecs) byDownload.set(r.downloadId ?? `row:${r.id}`, r)
+  const downloads = [...byDownload.values()]
+  const sizeLeft = downloads.reduce((s, r) => s + (r.sizeleft ?? 0), 0)
+  const sizeTotal = downloads.reduce((s, r) => s + (r.size ?? 0), 0)
+  const stalledItems = downloads
+    .filter((r) => isStalledRow(r, nowMs))
+    .map((r) => ({
+      title: r.title ?? null,
+      added_at: r.added ?? null,
+      age_hours: Math.round((nowMs - Date.parse(r.added)) / 3_600_000),
+      size_gb: Number(((r.size ?? 0) / 1073741824).toFixed(2)),
+      queue_id: r.id ?? null,
+    }))
+  return {
+    active_downloads: downloads.length,
+    active_items: queueRecs.length,
+    states: [...new Set(downloads.map((r) => r.status))],
+    tracked_states: [...new Set(downloads.map((r) => r.trackedDownloadState).filter(Boolean))],
+    errors: [...new Set(downloads.map((r) => r.errorMessage).filter(Boolean))],
+    size_left_bytes: sizeLeft,
+    size_total_bytes: sizeTotal,
+    percent_complete: sizeTotal > 0 ? Math.round(((sizeTotal - sizeLeft) / sizeTotal) * 100) : null,
+    stalled: stalledItems.length > 0,
+    stalled_items: stalledItems,
+  }
+}
+
+// The deterministic core. The agent must never have to work this out itself.
+export function diagnose({ shelf, result, chain, entity, kind }) {
+  const file = result.file ?? {}
+  const onShelf = kind === "series" ? (file.episodes_on_disk ?? 0) > 0 : Boolean(file.on_shelf)
+  const complete = kind === "series" ? (file.episodes_on_disk ?? 0) >= (file.episodes_total ?? Infinity) : onShelf
+
+  if (complete) {
+    return { stuck_stage: null, stuck_reason: null, likely_fix: null, human_action_required: false,
+             summary: "On the shelf and complete. Nothing is stuck." }
+  }
+  if (result.download.stalled) {
+    const items = result.download.stalled_items
+    const oldest = Math.max(...items.map((i) => i.age_hours))
+    return { stuck_stage: "download", stuck_reason: "stalled_no_progress",
+             likely_fix: "blocklist_and_research", human_action_required: false,
+             percent_complete: result.download.percent_complete,
+             detail: items,
+             summary: `Stalled, not slow. ${items.length === 1 ? "The release" : `${items.length} releases`} ${items.length === 1 ? "has" : "have"} not downloaded a single byte in ${oldest} hours, which means no seeders rather than a quiet queue. Waiting will not fix it; blocklist the release and search again for a different one.` }
+  }
+  if (result.download.active_downloads > 0) {
+    const left = result.download.size_left_bytes
+    const total = result.download.size_total_bytes
+    const gb = (left / 1073741824).toFixed(1)
+    const pct = total > 0 ? Math.round(((total - left) / total) * 100) : null
+    const what = result.download.active_downloads === 1 && result.download.active_items > 1
+      ? `a ${result.download.active_items}-episode pack`
+      : `${result.download.active_downloads} download(s)`
+    return { stuck_stage: null, stuck_reason: null, likely_fix: null, human_action_required: false,
+             percent_complete: pct,
+             summary: `Downloading now — ${what}${pct === null ? "" : `, ${pct}% done`}, about ${gb} GB to go.` }
+  }
+  if (result.download.errors.length) {
+    return { stuck_stage: "download", stuck_reason: "download_client_error", likely_fix: "retry_or_replace_release",
+             human_action_required: false, detail: result.download.errors,
+             summary: `The download client reported: ${result.download.errors.join("; ")}` }
+  }
+  if (!chain.healthy) {
+    return { stuck_stage: "indexers", stuck_reason: "acquisition_chain_down",
+             likely_fix: "restore_indexers", human_action_required: true,
+             detail: chain.problems,
+             summary: `Nothing can download: ${chain.problems.map((p) => p.message).join(" ")} This blocks every request, not just this one.` }
+  }
+  if (entity && entity.monitored === false) {
+    return { stuck_stage: "request", stuck_reason: "not_monitored", likely_fix: "enable_monitoring",
+             human_action_required: false, summary: "It is not monitored, so no search will ever run for it." }
+  }
+  if (result.search.grab_attempts === 0) {
+    return { stuck_stage: "search", stuck_reason: "no_search_run_or_no_acceptable_release",
+             likely_fix: "rescan", human_action_required: false,
+             summary: "Indexers are healthy but nothing has ever been grabbed. A fresh search (media_diagnose_and_fix action=rescan) is the next step." }
+  }
+  if (onShelf && !complete) {
+    return { stuck_stage: "import", stuck_reason: "partially_imported", likely_fix: "rescan",
+             human_action_required: false,
+             summary: `Partly here: ${file.episodes_on_disk} of ${file.episodes_total} episodes. The rest still need grabbing.` }
+  }
+  return { stuck_stage: "import", stuck_reason: "grabbed_but_not_imported", likely_fix: "force_import_scan",
+           human_action_required: false,
+           summary: `It was grabbed (${result.search.last_grab_title ?? "unknown release"}) but never landed on the shelf.` }
+}
+
+// -------------------------------------------------- tool: diagnose_and_fix
+
+async function mediaDiagnoseAndFix(a) {
+  const before = await mediaRequestStatus({ request_id: a.request_id, tmdb_id: a.tmdb_id, title: a.title })
+  if (!before.found) return { result: "no_such_request", before, after: null, human_action_required: true,
+                              human_action_reason: "Nothing to fix — it was never requested." }
+  const action = a.action ?? (before.diagnosis?.likely_fix ?? "rescan")
+
+  if (before.diagnosis?.stuck_reason === "acquisition_chain_down" && action !== "report_only") {
+    return { action, dry_run: Boolean(a.dry_run), result: "rejected_fix_unsafe", before, after: null,
+             human_action_required: true,
+             human_action_reason: "The acquisition chain itself is down (see before.chain.problems). Re-searching cannot help until indexers are restored." }
+  }
+  if (a.dry_run) {
+    return { action, dry_run: true, result: "would_apply", before,
+             would_do: describeAction(action), human_action_required: false }
+  }
+
+  const kind = before.request.kind
+  const svcId = kind === "series" ? before.request.sonarr_id : before.request.radarr_id
+  if (!svcId) return { action, result: "manual_required", before, after: null, human_action_required: true,
+                       human_action_reason: "This request is not yet mapped into Sonarr/Radarr, so no search can be triggered." }
+
+  let commanded = null
+  if (action === "rescan" || action === "enable_monitoring" || action === "force_import_scan") {
+    if (action === "enable_monitoring") {
+      if (kind === "series") await sonarr(`/series/${svcId}`, { method: "PUT", body: { ...(await sonarr(`/series/${svcId}`)), monitored: true } })
+      else await radarr(`/movie/${svcId}`, { method: "PUT", body: { ...(await radarr(`/movie/${svcId}`)), monitored: true } })
+    }
+    const cmd = kind === "series"
+      ? (action === "force_import_scan" ? { name: "RescanSeries", seriesId: svcId } : { name: "SeriesSearch", seriesId: svcId })
+      : (action === "force_import_scan" ? { name: "RescanMovie", movieIds: [svcId] } : { name: "MoviesSearch", movieIds: [svcId] })
+    commanded = kind === "series" ? await sonarr("/command", { method: "POST", body: cmd }) : await radarr("/command", { method: "POST", body: cmd })
+  } else if (action === "blocklist_and_research") {
+    // Removing with blocklist=true is what stops the same dead release being
+    // grabbed straight back. The search that follows is then free to pick a
+    // different one.
+    const stalled = before.download.stalled_items ?? []
+    if (!stalled.length) return { action, result: "nothing_to_blocklist", before, after: null, human_action_required: false,
+                                  human_action_reason: "No download has been sitting at zero long enough to call it stalled." }
+    for (const item of stalled) {
+      if (item.queue_id === null) continue
+      const client = kind === "series" ? sonarr : radarr
+      await client(`/queue/${item.queue_id}`, { method: "DELETE", query: { removeFromClient: true, blocklist: true, skipRedownload: true } })
+    }
+    const cmd = kind === "series" ? { name: "SeriesSearch", seriesId: svcId } : { name: "MoviesSearch", movieIds: [svcId] }
+    commanded = kind === "series" ? await sonarr("/command", { method: "POST", body: cmd }) : await radarr("/command", { method: "POST", body: cmd })
+  } else {
+    return { action, result: "unsupported_action", before, after: null, human_action_required: true,
+             human_action_reason: `Action "${action}" is not implemented. Supported: rescan, enable_monitoring, force_import_scan, blocklist_and_research, report_only.` }
+  }
+
+  await new Promise((r) => setTimeout(r, 12_000))
+  const after = await mediaRequestStatus({ request_id: a.request_id, tmdb_id: a.tmdb_id, title: a.title })
+  return {
+    action, dry_run: false, applied_at: new Date().toISOString(),
+    command: { id: commanded?.id ?? null, name: commanded?.name ?? null },
+    before: { diagnosis: before.diagnosis, grab_attempts: before.search.grab_attempts, active_downloads: before.download.active_downloads },
+    after: { diagnosis: after.diagnosis, grab_attempts: after.search.grab_attempts, active_downloads: after.download.active_downloads },
+    result: after.download.active_downloads > before.download.active_downloads ? "grabbed_and_downloading"
+          : after.search.grab_attempts > before.search.grab_attempts ? "grabbed"
+          : "queued_for_search",
+    human_action_required: Boolean(after.diagnosis?.human_action_required),
+    human_action_reason: after.diagnosis?.human_action_required ? after.diagnosis.summary : null,
+  }
+}
+
+function describeAction(action) {
+  return {
+    rescan: "Trigger a fresh indexer search and grab the best acceptable release.",
+    enable_monitoring: "Mark it monitored, then search.",
+    force_import_scan: "Re-scan the disk so an already-downloaded file gets imported.",
+    blocklist_and_research: "Blocklist the stalled release so it cannot be grabbed again, then search for a different one.",
+    report_only: "Report only; change nothing.",
+  }[action] ?? "Unknown action."
+}
+
+// ------------------------------------------------------- tool: play/resolve
+
+async function mediaPlayOrResolve(a) {
+  const status = await mediaRequestStatus({ request_id: a.request_id, tmdb_id: a.tmdb_id, title: a.title })
+  if (!status.found || !status.file) {
+    return { playable: false, reason: "not_on_shelf", diagnosis: status.diagnosis ?? null,
+             human_action_required: true, human_action_reason: "It is not on the shelf yet." }
+  }
+  const onShelf = status.request.kind === "series" ? (status.file.episodes_on_disk ?? 0) > 0 : status.file.on_shelf
+  return {
+    playable: Boolean(onShelf),
+    title: status.request.title ?? null,
+    kind: status.request.kind,
+    tmdb_id: status.request.tmdb_id,
+    episodes_on_disk: status.file.episodes_on_disk ?? null,
+    episodes_total: status.file.episodes_total ?? null,
+    path: status.file.path,
+    size_bytes: status.file.size_bytes,
+    play_url: onShelf ? `${JELLYFIN_WEB}/web/index.html#!/search.html?query=${encodeURIComponent(status.request.title ?? "")}` : null,
+    diagnosis: status.diagnosis,
+  }
+}
+
+// --------------------------------------------------------- tool: chain health
+
+async function mediaChainHealth() {
+  const chain = await chainHealth()
+  return {
+    healthy: chain.healthy,
+    indexers: chain.indexers,
+    app_sync: chain.apps,
+    problems: chain.problems,
+    summary: chain.healthy
+      ? `Acquisition chain healthy: ${chain.indexers.ok.length} of ${chain.indexers.enabled} enabled indexers responding${chain.indexers.failing.length ? `, failing: ${chain.indexers.failing.join(", ")}` : ""}.`
+      : `Acquisition chain DOWN. ${chain.problems.map((p) => p.message).join(" ")}`,
+  }
+}
+
+// ------------------------------------- tools: search_now / blocklist_stalled
+
+// Act on an item already in Sonarr/Radarr directly; no Jellyseerr request needed.
+// Never adds a library item: an unknown title is reported, not created.
+const arrFor = (kind) => (kind === "series" ? sonarr : radarr)
+
+async function resolveLibraryItem(a) {
+  let candidates
+  if ((a.service_id !== undefined && a.service_id !== null) || a.tmdb_id) {
+    const list = await arrFor(a.kind)(a.kind === "series" ? "/series" : "/movie")
+    const items = (Array.isArray(list) ? list : []).map((i) => libraryCandidate(a.kind, i))
+    const hit = items.filter((i) => (a.service_id !== undefined && a.service_id !== null ? i.service_id === Number(a.service_id) : i.tmdb_id === Number(a.tmdb_id)))
+    if (hit.length === 1) return { item: { id: hit[0].service_id, title: hit[0].title } }
+    candidates = hit
+  } else if (a.title) {
+    const ranked = (await findLibraryCandidates(a.title, a.kind)).filter((c) => c.service_id !== null)
+    // Act only when the best tier holds exactly one item and it is not merely a
+    // typo-distance match; otherwise name the candidates and let the caller pick.
+    const bestTier = ranked.filter((c) => c.match === ranked[0]?.match)
+    if (bestTier.length === 1 && bestTier[0].match !== "fuzzy") return { item: { id: bestTier[0].service_id, title: bestTier[0].title } }
+    if (!ranked.length) {
+      const lookup = (await lookupCandidates(a.title, a.kind)).filter((c) => !c.in_library).map((c) => ({ ...c, not_in_library: true }))
+      return { result: "not_found", candidates: lookup }
+    }
+    candidates = ranked
+  } else candidates = []
+  return { result: candidates.length ? "ambiguous" : "not_found", candidates: candidates.slice(0, 10) }
+}
+
+const QUEUE_PAGE_SIZE = 200
+const QUEUE_MAX_PAGES = 20
+
+// The item's queue rows. Filtered server-side (seriesIds/movieIds) and paged, so a
+// long queue cannot hide a row; the client-side filter stays as the backstop.
+async function itemQueue(kind, serviceId) {
+  const client = arrFor(kind)
+  const idKey = kind === "series" ? "seriesId" : "movieId"
+  const filter = kind === "series" ? { seriesIds: serviceId, includeSeries: true } : { movieIds: serviceId }
+  const rows = []
+  for (let page = 1; page <= QUEUE_MAX_PAGES; page++) {
+    const q = await client("/queue", { query: { ...filter, page, pageSize: QUEUE_PAGE_SIZE } })
+    const records = q?.records ?? []
+    rows.push(...records)
+    if (!records.length || !(Number(q?.totalRecords) > page * QUEUE_PAGE_SIZE)) break
+  }
+  return rows.filter((r) => r[idKey] === serviceId)
+}
+
+function queueReport(rows) {
+  const now = Date.now()
+  return rows.map((r) => ({ queue_id: r.id ?? null, title: r.title ?? null, status: r.status ?? null,
+                            size_left_bytes: r.sizeleft ?? 0, stalled: isStalledRow(r, now) }))
+}
+
+async function runSearch(kind, serviceId) {
+  const body = kind === "series" ? { name: "SeriesSearch", seriesId: serviceId } : { name: "MoviesSearch", movieIds: [serviceId] }
+  const c = await arrFor(kind)("/command", { method: "POST", body })
+  return { id: c?.id ?? null, name: c?.name ?? body.name, status: c?.status ?? null }
+}
+
+export async function mediaSearchNow(a) {
+  if (a.kind !== "series" && a.kind !== "movie") return { result: "invalid_kind", message: "kind must be 'series' or 'movie'." }
+  const found = await resolveLibraryItem(a)
+  if (!found.item) return { result: found.result, kind: a.kind, candidates: found.candidates }
+  const { item } = found
+  const command = await runSearch(a.kind, item.id)
+  return { kind: a.kind, service_id: item.id, title: item.title, command, queue: queueReport(await itemQueue(a.kind, item.id)) }
+}
+
+export async function mediaBlocklistStalled(a) {
+  if (a.kind !== "series" && a.kind !== "movie") return { result: "invalid_kind", message: "kind must be 'series' or 'movie'." }
+  if (a.service_id === undefined || a.service_id === null) return { result: "service_id_required" }
+  const serviceId = Number(a.service_id)
+  const rows = await itemQueue(a.kind, serviceId)
+  const now = Date.now()
+  let targets
+  if (Array.isArray(a.queue_ids) && a.queue_ids.length) {
+    const own = new Set(rows.map((r) => r.id))
+    const foreign = a.queue_ids.filter((id) => !own.has(id))
+    if (foreign.length) return { result: "queue_id_not_for_item", foreign_queue_ids: foreign, queue: queueReport(rows) }
+    targets = rows.filter((r) => a.queue_ids.includes(r.id))
+  } else {
+    targets = rows.filter((r) => isStalledRow(r, now))
+  }
+  // A season pack is many queue rows sharing one downloadId; deleting one removes
+  // the download for all, so delete once per download.
+  const seen = new Set()
+  targets = targets.filter((r) => {
+    const key = r.downloadId ? `d:${r.downloadId}` : `q:${r.id}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+  if (!targets.length) return { result: "nothing_to_blocklist", queue: queueReport(rows) }
+  const removed = []
+  const failed = []
+  for (const row of targets) {
+    try {
+      await arrFor(a.kind)(`/queue/${row.id}`, { method: "DELETE", query: { removeFromClient: true, blocklist: true, skipRedownload: true } })
+      removed.push(row.id)
+    } catch (e) {
+      // 404: the row went away (finished or removed with its pack); not a failure to retry.
+      if (/_http_404$/.test(e.code ?? "")) removed.push(row.id)
+      else failed.push({ queue_id: row.id, error: e.message })
+    }
+  }
+  const command = a.research === false ? null : await runSearch(a.kind, serviceId)
+  return { removed, ...(failed.length ? { failed } : {}), command, queue: queueReport(await itemQueue(a.kind, serviceId)) }
+}
+
+// ------------------------------------------------------------------- schema
+
+const TOOLS = [
+  {
+    name: "media_search",
+    description: "Search or browse the household media catalogue. Use `query` for a title lookup: partial and misspelled titles are matched against the library first (Sonarr, Radarr, Jellyfin) and returned as `library_matches` with their kind and service id, and when nothing in the library matches, `lookup_candidates` (TVDB/TMDB) cover titles not in the library. Never say a title does not exist without reading both; use `genres`/`keywords`/`year_range` to browse by vibe (e.g. keywords ['autumn','thanksgiving'] for cozy fall films). `on_shelf: true` restricts to what is already downloaded, `false` to what is not, omit for both. Every item says whether it is on the shelf and carries its tmdb_id so a follow-up media_request needs no second lookup.",
+    inputSchema: { type: "object", properties: {
+      query: { type: "string", description: "Title or free text. Omit to browse by filters." },
+      kind: { type: "string", enum: ["movie", "series", "any"], description: "Default any." },
+      year_range: { type: "array", items: { type: "number" }, minItems: 2, maxItems: 2, description: "[minYear, maxYear]" },
+      genres: { type: "array", items: { type: "string" }, description: "TMDB genre names, e.g. ['Romance','Drama']." },
+      keywords: { type: "array", items: { type: "string" }, description: "TMDB keywords, e.g. ['autumn','small town']. Best lever for mood/vibe requests." },
+      on_shelf: { type: "boolean", description: "true = only what we already have; false = only what we do not; omit = both." },
+      limit: { type: "number", description: "1-20, default 12." },
+      sort: { type: "string", enum: ["relevance", "release_year"] },
+    } },
+  },
+  {
+    name: "media_request",
+    description: "Request a film or series so it gets downloaded. Give tmdb_id when known (from media_search), otherwise title plus optional year. Idempotent: if it was already requested you get approval_state 'already_requested' and duplicate_of, never a duplicate. Returns the downstream sonarr_id/radarr_id so media_request_status needs no re-resolution.",
+    inputSchema: { type: "object", properties: {
+      tmdb_id: { type: "number" },
+      title: { type: "string" },
+      year: { type: "number" },
+      kind: { type: "string", enum: ["movie", "series"] },
+      season_number: { type: "number", description: "Series only. Omit to request all seasons." },
+    } },
+  },
+  {
+    name: "media_request_status",
+    description: "One call, every stage: request, indexer search, download, file on disk, plus acquisition-chain health and a deterministic `diagnosis` block naming what is stuck, why, and the fix. Use this for any 'is it here yet?' or 'why hasn't X downloaded?' question. A queue row is not proof of progress: a release sitting at zero bytes comes back as stalled, not as downloading. Never infer the cause yourself — read diagnosis.summary.",
+    inputSchema: { type: "object", properties: {
+      request_id: { type: "string", description: "e.g. jellyseerr:42" },
+      tmdb_id: { type: "number" },
+      title: { type: "string" },
+    } },
+  },
+  {
+    name: "media_diagnose_and_fix",
+    description: "Act on a stuck request. Omit `action` to apply the fix that media_request_status already identified, including 'blocklist_and_research' for a release that has stalled at zero bytes. Refuses to act (result 'rejected_fix_unsafe') when the acquisition chain itself is down, because re-searching cannot help then. Use dry_run to preview.",
+    inputSchema: { type: "object", properties: {
+      request_id: { type: "string" }, tmdb_id: { type: "number" }, title: { type: "string" },
+      action: { type: "string", enum: ["rescan", "enable_monitoring", "force_import_scan", "blocklist_and_research", "report_only"] },
+      dry_run: { type: "boolean" },
+    } },
+  },
+  {
+    name: "media_chain_health",
+    description: "Health of the whole acquisition chain: Prowlarr indexers, their failure state, and whether Prowlarr is syncing to Sonarr/Radarr. Call this when several things are stuck at once, or before telling anyone a specific title is the problem — a dead chain blocks everything and is the single most likely cause.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "media_play_or_resolve",
+    description: "Resolve something on the shelf to a playable link plus what is actually on disk (episode counts, size, path). If it is not playable you get the same diagnosis block explaining why.",
+    inputSchema: { type: "object", properties: {
+      request_id: { type: "string" }, tmdb_id: { type: "number" }, title: { type: "string" },
+    } },
+  },
+  {
+    name: "media_search_now",
+    description: "Trigger a Sonarr/Radarr search for a series or movie that is already in the library, and report its queue. Use this when the owner asks to search, re-search, or look again for something already in Sonarr/Radarr; no Jellyseerr request id is needed. Identify it by service_id, tmdb_id, or exact title. Never adds anything new: zero or several matches come back as 'not_found' or 'ambiguous' with candidates. Never tell the owner to click Search in the web UI.",
+    inputSchema: { type: "object", properties: {
+      kind: { type: "string", enum: ["series", "movie"] },
+      service_id: { type: "number", description: "Sonarr series id or Radarr movie id." },
+      title: { type: "string" },
+      tmdb_id: { type: "number" },
+    }, required: ["kind"] },
+  },
+  {
+    name: "media_blocklist_stalled",
+    description: "Clear stuck downloads for a series or movie already in Sonarr/Radarr: remove stalled queue rows from the download client, blocklist those releases so they are not grabbed again, then search again (research, default true). Use this when the owner asks to clear stuck or stalled downloads; no Jellyseerr request id is needed. Without queue_ids it targets the item's stalled rows; with queue_ids only those, and each must belong to the item. Explicit queue_ids are removed even if still downloading, so pass them only when the owner named those downloads. Rows of one season pack are removed once; a delete that fails is reported in `failed` and the re-search still runs.",
+    inputSchema: { type: "object", properties: {
+      kind: { type: "string", enum: ["series", "movie"] },
+      service_id: { type: "number", description: "Sonarr series id or Radarr movie id (media_search_now returns it)." },
+      queue_ids: { type: "array", items: { type: "number" } },
+      research: { type: "boolean", description: "Search again afterwards. Default true." },
+    }, required: ["kind", "service_id"] },
+  },
+]
+
+const HANDLERS = {
+  media_search: mediaSearch,
+  media_request: mediaRequest,
+  media_request_status: mediaRequestStatus,
+  media_diagnose_and_fix: mediaDiagnoseAndFix,
+  media_chain_health: mediaChainHealth,
+  media_play_or_resolve: mediaPlayOrResolve,
+  media_search_now: mediaSearchNow,
+  media_blocklist_stalled: mediaBlocklistStalled,
+}
+
+// ------------------------------------------------------------ jsonrpc stdio
+
+function send(msg) { process.stdout.write(JSON.stringify(msg) + "\n") }
+
+async function handle(msg) {
+  const { id, method, params } = msg
+  if (method === "initialize") {
+    return send({ jsonrpc: "2.0", id, result: {
+      protocolVersion: "2024-11-05",
+      capabilities: { tools: {} },
+      serverInfo: { name: "sanctuary-media", version: "1.0.0" },
+    } })
+  }
+  if (method === "initialized" || method === "notifications/initialized") return
+  if (method === "tools/list") return send({ jsonrpc: "2.0", id, result: { tools: TOOLS } })
+  if (method === "tools/call") {
+    const fn = HANDLERS[params?.name]
+    if (!fn) return send({ jsonrpc: "2.0", id, result: { isError: true, content: [{ type: "text", text: `Unknown tool: ${params?.name}` }] } })
+    if (credError) {
+      const payload = { error: "credentials_unavailable", message: credError, human_action_required: true,
+                        human_action_reason: credError }
+      return send({ jsonrpc: "2.0", id, result: { isError: true, content: [{ type: "text", text: JSON.stringify(payload, null, 1) }] } })
+    }
+    try {
+      const out = await fn(params.arguments ?? {})
+      return send({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify(out, null, 1) }] } })
+    } catch (e) {
+      const payload = { error: e.code ?? "tool_failed", message: e.message,
+                        human_action_required: true,
+                        human_action_reason: `The media tool could not complete: ${e.message}. Report this failure rather than guessing the answer.` }
+      return send({ jsonrpc: "2.0", id, result: { isError: true, content: [{ type: "text", text: JSON.stringify(payload, null, 1) }] } })
+    }
+  }
+  if (id !== undefined) send({ jsonrpc: "2.0", id, error: { code: -32601, message: `Method not found: ${method}` } })
+}
+
+let buf = ""
+let inFlight = 0
+let stdinClosed = false
+
+// Exit only when stdin is closed AND nothing is still running. Exiting on 'end'
+// alone drops in-flight tool calls, which silently truncates a slow answer.
+function exitWhenIdle() {
+  if (stdinClosed && inFlight === 0) process.exit(0)
+}
+
+// Only run the stdio server when invoked directly (node media-mcp.mjs, exactly
+// how agent.json launches it). Guarding this lets the test suite import the
+// module for computeDownloadState/diagnose without attaching to stdin or exiting
+// the test process. The launch is a plain node <abs-path>, so argv[1] is the
+// file's own path and this comparison holds.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.stdin.setEncoding("utf8")
+  process.stdin.on("data", (chunk) => {
+    buf += chunk
+    let nl
+    while ((nl = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, nl).trim()
+      buf = buf.slice(nl + 1)
+      if (!line) continue
+      let msg
+      try { msg = JSON.parse(line) } catch { continue }
+      inFlight += 1
+      handle(msg)
+        .catch((e) => {
+          if (msg.id !== undefined) send({ jsonrpc: "2.0", id: msg.id, error: { code: -32603, message: e.message } })
+        })
+        .finally(() => { inFlight -= 1; exitWhenIdle() })
+    }
+  })
+  process.stdin.on("end", () => { stdinClosed = true; exitWhenIdle() })
+}