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

package/changelog.json

@@ -1,6 +1,14 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.851",
+      "changes": [
+        "The Butler can fix release-numbering mismatches himself: typed Sonarr/Radarr release search, override grab, blocklist and manual import tools, scene numbering in media_episodes, and a free-text indexer search",
+        "media_blocklist_stalled treats a download unfinished after 72 hours as stuck",
+        "The engine asks once when a settle answer drops the reply written beside it, so Telegram and A2A get the full reply (never on the last provider iteration). When the only matching release has no seeders, the Butler still grabs it with the right mapping and says it may not finish"
+      ]
+    },
     {
       "version": "0.1.0-alpha.850",
       "changes": [
@@ -14,7 +22,8 @@
         "The Butler can start a Sonarr series or Radarr movie search now (media_search_now) and blocklist-and-research stalled queue items (media_blocklist_stalled) without a Jellyseerr request id.",
         "Media title lookup matches partial and misspelled titles across Sonarr, Radarr and Jellyfin, and falls back to the TVDB/TMDB lookup before saying a title is not in the library.",
         "The Butler's always-loaded psyche now says to answer from primary sources rather than memory, re-read live state, label anything unreachable as unverified, and route missing tools to Claude Code instead of asking Ari to click.",
-        "media_blocklist_stalled removes each season pack once, reads the item's whole queue, and reports a failed delete without skipping the re-search; media_search_now no longer searches a lone typo-distance title match."
+        "media_blocklist_stalled removes each season pack once, reads the item's whole queue, and reports a failed delete without skipping the re-search; media_search_now no longer searches a lone typo-distance title match.",
+        "The Butler can fix a release-numbering mismatch itself: media_episodes lists a series' episodes, media_release_search shows what indexers offer and how Sonarr parsed it, media_release_grab grabs a release with an explicit episode mapping, media_blocklist lists and removes blocklist entries, and media_manual_import maps downloaded files to episodes by title."
       ]
     },
     {

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.850",
+  "runtimeVersion": "0.1.0-alpha.851",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

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

@@ -36,10 +36,12 @@ const JELLYFIN_WEB = cred?.jellyfinWebUrl ?? "https://media.mendelow.cloud"
 const JELLYFIN = cred?.jellyfin ?? { url: "", apiKey: "" }
 
 const TIMEOUT_MS = 45_000
+// Interactive release search queries every indexer live and can take minutes.
+const SEARCH_TIMEOUT_MS = 180_000
 
 // ---------------------------------------------------------------- http helpers
 
-async function req(base, path, { key, header = "X-Api-Key", method = "GET", body, query } = {}) {
+async function req(base, path, { key, header = "X-Api-Key", method = "GET", body, query, timeoutMs = TIMEOUT_MS } = {}) {
   let url = `${base}${path}`
   if (query) {
     const parts = Object.entries(query)
@@ -52,7 +54,7 @@ async function req(base, path, { key, header = "X-Api-Key", method = "GET", body
   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) })
+    res = await fetch(url, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs) })
   } catch (e) {
     throw new ServiceError(`${serviceOf(base)}_unreachable`, `${serviceOf(base)} did not respond: ${e.name === "TimeoutError" ? "timeout" : e.message}`)
   }
@@ -587,9 +589,16 @@ export async function mediaRequestStatus(a) {
 // 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.
+// A download that never started, or one still unfinished days later (e.g. stuck at
+// 99.85% with no seeders for the last piece), will not finish on its own.
+const STUCK_INCOMPLETE_AFTER_HOURS = 72
+
 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
+  if (!((r.size ?? 0) > 0) || !r.added) return false
+  const ageHours = (nowMs - Date.parse(r.added)) / 3_600_000
+  const left = r.sizeleft ?? 0
+  if (left >= r.size) return ageHours >= STALL_AFTER_HOURS
+  return left > 0 && ageHours >= STUCK_INCOMPLETE_AFTER_HOURS
 }
 
 export function computeDownloadState(queueRecs, nowMs) {
@@ -907,6 +916,223 @@ export async function mediaBlocklistStalled(a) {
   return { removed, ...(failed.length ? { failed } : {}), command, queue: queueReport(await itemQueue(a.kind, serviceId)) }
 }
 
+// ------------------------------- tools: episodes / releases / blocklist / import
+
+// When an automatic search finds nothing, the Butler works the release by hand:
+// list the episodes, read what the indexers offer and how Sonarr parsed it, grab
+// the right one with an explicit episode mapping, and map downloaded files by title.
+// All scoped to series/movies already in the library; nothing here adds one.
+
+const kindOk = (a) => a.kind === "series" || a.kind === "movie"
+const invalidKind = () => ({ result: "invalid_kind", message: "kind must be 'series' or 'movie'." })
+const idKeyOf = (kind) => (kind === "series" ? "seriesId" : "movieId")
+const code2 = (n) => String(n).padStart(2, "0")
+const sxe = (e) => `S${code2(e.seasonNumber)}E${code2(e.episodeNumber)}`
+
+async function seriesEpisodes(seriesId, seasonNumber) {
+  const list = await sonarr("/episode", { query: { seriesId, seasonNumber } })
+  return Array.isArray(list) ? list : []
+}
+
+export async function mediaEpisodes(a) {
+  if (a.service_id === undefined || a.service_id === null) return { result: "service_id_required" }
+  const seriesId = Number(a.service_id)
+  const eps = await seriesEpisodes(seriesId, a.season_number)
+  return {
+    series_id: seriesId,
+    season_number: a.season_number ?? null,
+    count: eps.length,
+    episodes: eps.map((e) => ({ episode_id: e.id, code: sxe(e), season: e.seasonNumber, episode: e.episodeNumber, title: e.title ?? null,
+                                air_date: e.airDate ?? null, has_file: Boolean(e.hasFile), monitored: Boolean(e.monitored),
+                                // Release names follow scene (often streaming) numbering; Sonarr's own mapping, when it has one.
+                                scene_code: Number.isInteger(e.sceneSeasonNumber) && Number.isInteger(e.sceneEpisodeNumber)
+                                  ? `S${String(e.sceneSeasonNumber).padStart(2, "0")}E${String(e.sceneEpisodeNumber).padStart(2, "0")}` : null })),
+  }
+}
+
+// Free-text search across every Prowlarr indexer: discovery only, it grabs nothing.
+// Sonarr's own search only asks for the season/episode codes it expects; this finds
+// what exists under any name (another numbering, a "Season 2 (2020)" pack, an episode title).
+export async function mediaIndexerSearch(a) {
+  const query = typeof a.query === "string" ? a.query.trim() : ""
+  if (!query) return { result: "query_required" }
+  const raw = await prowlarr("/search", { query: { query, type: "search", limit: 100 }, timeoutMs: SEARCH_TIMEOUT_MS })
+  const limit = Math.min(Math.max(Number(a.limit) || 25, 1), 50)
+  const rows = (Array.isArray(raw) ? raw : [])
+    .map((r) => ({ indexer: r.indexer ?? null, title: r.title ?? null, size_bytes: r.size ?? null, seeders: r.seeders ?? null,
+                   age_days: r.age ?? null, protocol: r.protocol ?? null }))
+    .sort((x, y) => (y.seeders ?? -1) - (x.seeders ?? -1))
+  return { query, count: rows.length, releases: rows.slice(0, limit),
+           note: "Discovery only. To grab, run media_release_search for the item so Sonarr/Radarr caches the release, then media_release_grab with an explicit episode mapping." }
+}
+
+// The last search's compact rows, keyed by kind + guid, so a grab can check what Sonarr parsed.
+// Sonarr/Radarr forget a search's releases after about 30 minutes; expire ours a little sooner.
+const releaseCache = new Map()
+const RELEASE_CACHE_TTL_MS = 25 * 60_000
+const RELEASE_CACHE_MAX = 500
+const MAX_EPISODE_SEARCHES = 6
+
+function cacheRelease(key, row, nowMs = Date.now()) {
+  for (const [k, v] of releaseCache) if (nowMs - v.at > RELEASE_CACHE_TTL_MS) releaseCache.delete(k)
+  releaseCache.delete(key)
+  releaseCache.set(key, { ...row, at: nowMs })
+  while (releaseCache.size > RELEASE_CACHE_MAX) releaseCache.delete(releaseCache.keys().next().value)
+}
+
+function releaseRow(kind, r) {
+  const rejections = Array.isArray(r.rejections) ? r.rejections.map((x) => (typeof x === "string" ? x : x?.reason ?? String(x))) : []
+  const row = {
+    guid: r.guid, indexer_id: r.indexerId ?? null, indexer: r.indexer ?? null, title: r.title ?? null, size_bytes: r.size ?? null,
+    seeders: r.seeders ?? null, age_days: r.age ?? null, quality: r.quality?.quality?.name ?? null, protocol: r.protocol ?? null,
+    rejected: Boolean(r.rejected), rejections, blocklisted: rejections.some((x) => /blocklist/i.test(x)),
+  }
+  if (kind === "series") {
+    return { ...row, full_season: Boolean(r.fullSeason), parsed_season: r.seasonNumber ?? null, parsed_episodes: r.episodeNumbers ?? [],
+             mapped_episodes: (r.mappedEpisodeInfo ?? []).map((e) => ({ episode_id: e.id ?? null, code: sxe(e), title: e.title ?? null })),
+             mapped_series_id: r.mappedSeriesId ?? null }
+  }
+  return { ...row, mapped_movie_id: r.mappedMovieId ?? null }
+}
+
+export async function mediaReleaseSearch(a) {
+  if (!kindOk(a)) return invalidKind()
+  if (a.service_id === undefined || a.service_id === null) return { result: "service_id_required" }
+  const serviceId = Number(a.service_id)
+  let raw = []
+  if (a.kind === "movie") {
+    raw = await radarr("/release", { query: { movieId: serviceId }, timeoutMs: SEARCH_TIMEOUT_MS })
+  } else if (Array.isArray(a.episode_ids) && a.episode_ids.length) {
+    // Sonarr searches one episode per call.
+    if (a.episode_ids.length > MAX_EPISODE_SEARCHES) return { result: "too_many_episode_ids", max: MAX_EPISODE_SEARCHES, message: "Search the season instead, or fewer episodes at a time." }
+    for (const id of a.episode_ids) raw.push(...await sonarr("/release", { query: { episodeId: id }, timeoutMs: SEARCH_TIMEOUT_MS }))
+  } else if (a.season_number !== undefined && a.season_number !== null) {
+    raw = await sonarr("/release", { query: { seriesId: serviceId, seasonNumber: a.season_number }, timeoutMs: SEARCH_TIMEOUT_MS })
+  } else return { result: "season_number_or_episode_ids_required" }
+  const seen = new Set()
+  let rows = (Array.isArray(raw) ? raw : []).filter((r) => (seen.has(r.guid) ? false : seen.add(r.guid))).map((r) => releaseRow(a.kind, r))
+  const total = rows.length
+  if (a.query) {
+    const q = String(a.query).toLowerCase()
+    rows = rows.filter((r) => (r.title ?? "").toLowerCase().includes(q))
+  }
+  rows.sort((x, y) => Number(y.seeders ?? 0) - Number(x.seeders ?? 0))
+  const limit = Math.min(Math.max(Number(a.limit) || 40, 1), 100)
+  for (const r of rows) cacheRelease(`${a.kind}:${r.guid}`, { ...r, service_id: serviceId, season_number: a.season_number ?? null })
+  return { kind: a.kind, service_id: serviceId, total_found: total, matched: rows.length, releases: rows.slice(0, limit) }
+}
+
+export async function mediaReleaseGrab(a) {
+  if (!kindOk(a)) return invalidKind()
+  if (!a.guid || a.indexer_id === undefined || a.indexer_id === null) return { result: "guid_and_indexer_id_required" }
+  const cached = releaseCache.get(`${a.kind}:${a.guid}`)
+  if (!cached || Date.now() - cached.at > RELEASE_CACHE_TTL_MS) {
+    return { result: "search_first", message: "Run media_release_search first; a release can only be grabbed from a recent search (within 25 minutes)." }
+  }
+  if (cached.indexer_id !== null && Number(a.indexer_id) !== Number(cached.indexer_id)) return { result: "indexer_mismatch", expected_indexer_id: cached.indexer_id }
+  const body = { guid: a.guid, indexerId: Number(a.indexer_id) }
+  const hasEpisodes = Array.isArray(a.episode_ids) && a.episode_ids.length > 0
+  if (a.kind === "series") {
+    if (!hasEpisodes) {
+      // A pack Sonarr parsed as another season would be mapped to the wrong episodes.
+      const target = a.season_number ?? cached.season_number
+      if (cached.full_season && (target === undefined || target === null || Number(target) !== Number(cached.parsed_season))) {
+        return { result: "season_pack_mismatch", parsed_season: cached.parsed_season, target_season: target ?? null, title: cached.title,
+                 message: "Sonarr parsed this season pack as a different season than the target. Pass series_id and episode_ids to say which episodes it holds." }
+      }
+    } else {
+      if (a.series_id === undefined || a.series_id === null) return { result: "series_id_required_with_episode_ids" }
+      const seriesId = Number(a.series_id)
+      if (seriesId !== Number(cached.service_id)) return { result: "series_mismatch", searched_series_id: cached.service_id, message: "This release came from a search for another series." }
+      const own = new Set((await seriesEpisodes(seriesId)).map((e) => e.id))
+      const foreign = a.episode_ids.filter((id) => !own.has(id))
+      if (foreign.length) return { result: "episode_id_not_for_series", foreign_episode_ids: foreign }
+      Object.assign(body, { seriesId, episodeIds: a.episode_ids.map(Number), shouldOverride: true })
+      if (a.download_client_id !== undefined && a.download_client_id !== null) body.downloadClientId = Number(a.download_client_id)
+    }
+  }
+  const res = await arrFor(a.kind)("/release", { method: "POST", body })
+  return { result: "grabbed", kind: a.kind, title: cached.title, request: body,
+           response: { approved: res?.approved ?? null, rejected: res?.rejected ?? null, rejections: res?.rejections ?? [], download_id: res?.downloadId ?? null } }
+}
+
+const BLOCKLIST_PAGE_SIZE = 100
+const BLOCKLIST_MAX_PAGES = 20
+
+async function itemBlocklist(kind, serviceId) {
+  const idKey = idKeyOf(kind)
+  const filter = kind === "series" ? { seriesIds: serviceId } : { movieIds: serviceId }
+  const rows = []
+  for (let page = 1; page <= BLOCKLIST_MAX_PAGES; page++) {
+    const q = await arrFor(kind)("/blocklist", { query: { ...filter, page, pageSize: BLOCKLIST_PAGE_SIZE } })
+    const records = q?.records ?? []
+    rows.push(...records)
+    if (!records.length || !(Number(q?.totalRecords) > page * BLOCKLIST_PAGE_SIZE)) return rows.filter((r) => r[idKey] === serviceId)
+  }
+  const own = rows.filter((r) => r[idKey] === serviceId)
+  own.truncated = true
+  return own
+}
+
+const blocklistReport = (rows) => rows.map((r) => ({ blocklist_id: r.id, title: r.sourceTitle ?? null, date: r.date ?? null, indexer: r.indexer ?? null,
+  quality: r.quality?.quality?.name ?? null, episode_ids: r.episodeIds ?? [], message: r.message ?? null }))
+
+export async function mediaBlocklist(a) {
+  if (!kindOk(a)) return invalidKind()
+  if (a.service_id === undefined || a.service_id === null) return { result: "service_id_required" }
+  const serviceId = Number(a.service_id)
+  const rows = await itemBlocklist(a.kind, serviceId)
+  if (!Array.isArray(a.remove_ids) || !a.remove_ids.length) {
+    return { kind: a.kind, service_id: serviceId, count: rows.length, ...(rows.truncated ? { truncated: true } : {}), entries: blocklistReport(rows) }
+  }
+  const own = new Set(rows.map((r) => r.id))
+  const foreign = a.remove_ids.filter((id) => !own.has(id))
+  if (foreign.length) return { result: "blocklist_id_not_for_item", foreign_blocklist_ids: foreign, entries: blocklistReport(rows) }
+  await arrFor(a.kind)("/blocklist/bulk", { method: "DELETE", body: { ids: a.remove_ids.map(Number) } })
+  const left = await itemBlocklist(a.kind, serviceId)
+  return { result: "removed", removed: a.remove_ids, count: left.length, entries: blocklistReport(left) }
+}
+
+async function previewRows(seriesId, downloadId) {
+  const rows = await sonarr("/manualimport", { query: { downloadId, seriesId, filterExistingFiles: false } })
+  return Array.isArray(rows) ? rows : []
+}
+
+const previewReport = (rows) => rows.map((r) => ({ path: r.path, name: r.name ?? null, parsed_season: r.seasonNumber ?? null,
+  mapped_episodes: (r.episodes ?? []).map((e) => ({ episode_id: e.id ?? null, code: sxe(e), title: e.title ?? null })),
+  quality: r.quality?.quality?.name ?? null, rejections: (r.rejections ?? []).map((x) => (typeof x === "string" ? x : x?.reason ?? String(x))) }))
+
+export async function mediaManualImport(a) {
+  if (a.service_id === undefined || a.service_id === null) return { result: "service_id_required" }
+  if (!a.download_id) return { result: "download_id_required" }
+  const seriesId = Number(a.service_id)
+  const rows = await previewRows(seriesId, a.download_id)
+  if (a.mode !== "import") return { mode: "preview", series_id: seriesId, download_id: a.download_id, files: previewReport(rows) }
+  if (!Array.isArray(a.files) || !a.files.length || a.files.some((f) => !f || typeof f.path !== "string")) return { result: "files_required" }
+  const paths = a.files.map((f) => f.path)
+  if (new Set(paths).size !== paths.length) return { result: "duplicate_path" }
+  const byPath = new Map(rows.map((r) => [r.path, r]))
+  const unknown = a.files.filter((f) => !byPath.has(f.path)).map((f) => f.path)
+  if (unknown.length) return { result: "path_not_in_preview", paths: unknown, files: previewReport(rows) }
+  const seriesEps = await seriesEpisodes(seriesId)
+  const own = new Set(seriesEps.map((e) => e.id))
+  const foreign = a.files.flatMap((f) => (f.episode_ids ?? []).filter((id) => !own.has(id)))
+  if (foreign.length) return { result: "episode_id_not_for_series", foreign_episode_ids: foreign }
+  const empty = a.files.filter((f) => !Array.isArray(f.episode_ids) || !f.episode_ids.length).map((f) => f.path)
+  if (empty.length) return { result: "episode_ids_required", paths: empty }
+  const targets = a.files.flatMap((f) => f.episode_ids.map(Number))
+  if (new Set(targets).size !== targets.length) return { result: "episode_id_on_two_files" }
+  const files = a.files.map((f) => {
+    const r = byPath.get(f.path)
+    return { path: f.path, seriesId, episodeIds: f.episode_ids.map(Number), quality: r.quality, languages: r.languages, releaseGroup: r.releaseGroup ?? "",
+             indexerFlags: r.indexerFlags ?? 0, releaseType: r.releaseType ?? "unknown", downloadId: a.download_id }
+  })
+  const c = await sonarr("/command", { method: "POST", body: { name: "ManualImport", files, importMode: "auto" } })
+  // Episodes that already had a file: Sonarr treats these imports as replacements.
+  const replacing = seriesEps.filter((e) => e.hasFile && targets.includes(e.id)).map((e) => ({ episode_id: e.id, code: sxe(e) }))
+  return { mode: "import", imported: a.files.map((f) => ({ path: f.path, episode_ids: f.episode_ids })), ...(replacing.length ? { replacing } : {}), command: { id: c?.id ?? null, name: c?.name ?? "ManualImport", status: c?.status ?? null } }
+}
+
 // ------------------------------------------------------------------- schema
 
 const TOOLS = [
@@ -985,6 +1211,66 @@ const TOOLS = [
       research: { type: "boolean", description: "Search again afterwards. Default true." },
     }, required: ["kind", "service_id"] },
   },
+  {
+    name: "media_episodes",
+    description: "List a Sonarr series' episodes (optionally one season): episode_id, SxxEyy code, scene_code (the numbering release names use, when Sonarr has a mapping), title, air date, has_file. Use it to see what the TVDB numbering calls each episode before searching for releases by hand.",
+    inputSchema: { type: "object", properties: {
+      service_id: { type: "number", description: "Sonarr series id." },
+      season_number: { type: "number" },
+    }, required: ["service_id"] },
+  },
+  {
+    name: "media_indexer_search",
+    description: "Free-text search across every indexer (Prowlarr), sorted by seeders. Discovery only, it grabs nothing. Use it when Sonarr/Radarr's own search finds nothing: try the scene code from media_episodes, 'Season N', the year, or an episode title, to learn whether any release exists and how it is named. Zero seeders means it cannot download right now.",
+    inputSchema: { type: "object", properties: {
+      query: { type: "string" },
+      limit: { type: "number", description: "1-50, default 25." },
+    }, required: ["query"] },
+  },
+  {
+    name: "media_release_search",
+    description: "Interactive release search for a series or movie already in the library: what the indexers offer and how Sonarr/Radarr parsed each release (full_season, parsed_season, parsed_episodes, mapped_episodes), whether it is rejected and why, and whether it is blocklisted. Series: give season_number or episode_ids. Can take a minute or more. `query` filters returned titles. Use it when the automatic search found nothing, then grab with media_release_grab.",
+    inputSchema: { type: "object", properties: {
+      kind: { type: "string", enum: ["series", "movie"] },
+      service_id: { type: "number", description: "Sonarr series id or Radarr movie id." },
+      season_number: { type: "number" },
+      episode_ids: { type: "array", items: { type: "number" } },
+      query: { type: "string", description: "Case-insensitive text the release title must contain." },
+      limit: { type: "number", description: "1-100, default 40." },
+    }, required: ["kind", "service_id"] },
+  },
+  {
+    name: "media_release_grab",
+    description: "Grab one release from the last media_release_search by guid and indexer_id. For a release Sonarr mis-parsed (streaming numbering vs TVDB), pass series_id plus episode_ids to override the mapping; episode_ids must belong to the series. Without episode_ids, a season pack that Sonarr parsed as a different season than season_number is refused ('season_pack_mismatch'). Returns the exact request sent and Sonarr's answer.",
+    inputSchema: { type: "object", properties: {
+      kind: { type: "string", enum: ["series", "movie"] },
+      guid: { type: "string" },
+      indexer_id: { type: "number" },
+      series_id: { type: "number", description: "Required with episode_ids." },
+      episode_ids: { type: "array", items: { type: "number" }, description: "Episodes this release really holds." },
+      season_number: { type: "number", description: "Target season, checked against a season pack's parsed season when episode_ids is omitted." },
+      download_client_id: { type: "number" },
+    }, required: ["kind", "guid", "indexer_id"] },
+  },
+  {
+    name: "media_blocklist",
+    description: "List the blocklist for a series or movie in Sonarr/Radarr, and optionally remove entries (remove_ids) so the release can be grabbed again. Each id must belong to the item; a foreign id removes nothing.",
+    inputSchema: { type: "object", properties: {
+      kind: { type: "string", enum: ["series", "movie"] },
+      service_id: { type: "number" },
+      remove_ids: { type: "array", items: { type: "number" } },
+    }, required: ["kind", "service_id"] },
+  },
+  {
+    name: "media_manual_import",
+    description: "Map downloaded files to episodes by hand when their names carry the wrong numbering (Sonarr only). mode 'preview' lists the files of a download with the parsed and mapped episodes and rejections. mode 'import' takes files [{path, episode_ids}]: paths must come from that download's preview and episode_ids must belong to the series; quality and languages come from the preview. Match files to episodes by title using media_episodes.",
+    inputSchema: { type: "object", properties: {
+      mode: { type: "string", enum: ["preview", "import"], description: "Default preview." },
+      service_id: { type: "number", description: "Sonarr series id." },
+      download_id: { type: "string", description: "Download client id of the completed download (queue row downloadId)." },
+      files: { type: "array", items: { type: "object", properties: { path: { type: "string" }, episode_ids: { type: "array", items: { type: "number" } } }, required: ["path", "episode_ids"] } },
+    }, required: ["service_id", "download_id"] },
+  },
 ]
 
 const HANDLERS = {
@@ -996,6 +1282,12 @@ const HANDLERS = {
   media_play_or_resolve: mediaPlayOrResolve,
   media_search_now: mediaSearchNow,
   media_blocklist_stalled: mediaBlocklistStalled,
+  media_episodes: mediaEpisodes,
+  media_indexer_search: mediaIndexerSearch,
+  media_release_search: mediaReleaseSearch,
+  media_release_grab: mediaReleaseGrab,
+  media_blocklist: mediaBlocklist,
+  media_manual_import: mediaManualImport,
 }
 
 // ------------------------------------------------------------ jsonrpc stdio

package/deploy/unraid/sanctuary.ouro/psyche/TACIT.md

@@ -15,3 +15,4 @@
 - When state is ambiguous, investigate safely, say what is known, and ask only if the answer changes the next safe move.
 - When a tool for the job is missing, say so in one line and route the work: ask Claude Code over A2A or record it as a follow-up. Never ask Ari to click through a web UI for work the house is meant to do.
 - Answer from primary sources, never from memory. For any factual claim about the world or the house (whether a title or series exists, what is on the shelf, a container's state, a version, a download's progress, a book's metadata, what Ari said before), look it up with the tools first (Sonarr/Radarr/Jellyfin and their TVDB/TMDB lookup, the Unraid tools, calibre-web, libgen, HEY, web_search, your own state files) and answer from what they return. Re-read live state instead of repeating a status from an earlier reply. When no tool can reach the source, say it is unverified rather than asserting it. Never say a title does not exist without a catalog lookup, and when the library holds a strong partial match, offer it first.
+- When an automatic search finds nothing for episodes that exist, suspect numbering (streaming vs TVDB order, specials, absolute numbers). Read `media_episodes` (its `scene_code` is the numbering release names use), compare its titles with the `media_release_search` results (how Sonarr parsed each release) and with what `media_blocklist` holds, grab the right pack with `media_release_grab` and an explicit episode mapping, and after it downloads, map the files to episodes by title with `media_manual_import`. When Sonarr's search finds nothing, use `media_indexer_search` with the scene code, 'Season N', the year or an episode title to learn whether any release exists at all; if the only matching release has no seeders, still grab it with the right mapping (peers can reappear) and say plainly it may never finish instead of promising it will arrive. Report each step with what Sonarr returned.

package/deploy/unraid/sanctuary.ouro/tool-profiles.json

@@ -2,7 +2,7 @@
   "version": 2,
   "profiles": {
     "sanctuary-owner": {
-      "version": 11,
+      "version": 12,
       "contextScopes": [
         "household.status",
         "household.policy",
@@ -66,7 +66,13 @@
         "media_chain_health",
         "media_play_or_resolve",
         "media_search_now",
-        "media_blocklist_stalled"
+        "media_blocklist_stalled",
+        "media_episodes",
+        "media_indexer_search",
+        "media_release_search",
+        "media_release_grab",
+        "media_blocklist",
+        "media_manual_import"
       ],
       "effectScopes": [
         "telegram.proactive",
@@ -134,7 +140,7 @@
       ]
     },
     "sanctuary-agent-peer": {
-      "version": 2,
+      "version": 3,
       "toolNames": [
         "external_event_disposition",
         "query_active_work",
@@ -191,7 +197,13 @@
         "media_chain_health",
         "media_play_or_resolve",
         "media_search_now",
-        "media_blocklist_stalled"
+        "media_blocklist_stalled",
+        "media_episodes",
+        "media_indexer_search",
+        "media_release_search",
+        "media_release_grab",
+        "media_blocklist",
+        "media_manual_import"
       ],
       "contextScopes": [
         "household.status",

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.850</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.851</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/heart/core.js

@@ -14,6 +14,7 @@ exports.resumeApprovalContinuation = resumeApprovalContinuation;
 exports.isChatStyleChannel = isChatStyleChannel;
 exports.buildPonderResult = buildPonderResult;
 exports.isExternalStateQuery = isExternalStateQuery;
+exports.settleContentMismatchError = settleContentMismatchError;
 exports.getSettleRetryError = getSettleRetryError;
 exports.stripLastToolCalls = stripLastToolCalls;
 exports.repairOrphanedToolCalls = repairOrphanedToolCalls;
@@ -754,6 +755,27 @@ function isExternalStateQuery(toolName, args) {
     const cmd = String(args.command ?? "");
     return /\bgh\s+(pr|run|api|issue)\b/.test(cmd) || /\bnpm\s+(view|info|show)\b/.test(cmd);
 }
+const SETTLE_CONTENT_MISMATCH_MIN_CHARS = 40;
+// Markdown markers and smart punctuation differ between a reply and its settle copy without changing it.
+const normalizeForSettleComparison = (text) => text.replace(/[*_`>#~]/g, "").replace(/[\u2018\u2019]/g, "'").replace(/[\u201c\u201d]/g, '"').replace(/[\u2013\u2014]/g, "-").replace(/\s+/g, " ").trim().toLowerCase();
+/**
+ * Only `settle.answer` reaches the friend; assistant message text in the same
+ * message does not. When a model writes its real reply as message text and puts
+ * something else (often a third-person recap) in the answer, the friend gets the
+ * recap. Ask once for the reply to be resent as the answer. Short preambles and
+ * text the answer already contains (or that contains the answer) pass.
+ */
+function settleContentMismatchError(content, answer) {
+    if (typeof content !== "string")
+        return null;
+    const text = normalizeForSettleComparison(content);
+    if (text.length < SETTLE_CONTENT_MISMATCH_MIN_CHARS)
+        return null;
+    const reply = normalizeForSettleComparison(answer);
+    if (reply.includes(text) || text.includes(reply))
+        return null;
+    return "only settle.answer reaches the person; the message text you wrote alongside it does not. if that text is your reply, call settle again with the complete reply, in your own voice, as answer. if it was only working notes, call settle again with the same answer.";
+}
 function getSettleRetryError(mustResolveBeforeHandoff, intent, sawSteeringFollowUp, _delegationDecision, sawSendMessageSelf, sawPonder, _sawQuerySession, currentObligation, innerJob, _sawExternalStateQuery) {
     // Delegation adherence removed: the delegation decision is surfaced in the
     // system prompt as a suggestion. Hard-gating settle caused infinite
@@ -1120,6 +1142,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
     let currentReasoningEffort = "medium";
     let sawSendMessageSelf = false;
     let sawPonder = false;
+    let sawSettleContentMismatch = false;
     let sawQuerySession = false;
     let sawBridgeManage = false;
     let sawExternalStateQuery = false;
@@ -1884,7 +1907,14 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         // The provider finalizer has already established a top-level string
                         // answer before ordinary settle handling reaches this point.
                         const deliveredAnswer = answer;
-                        const retryError = privateReturnAckLeakError(deliveredAnswer, privateReturnHeldTokens)
+                        // Never spend the last provider iteration on this optional retry: delivering the recap beats delivering nothing.
+                        const contentMismatch = sawSettleContentMismatch || providerIterations >= exports.MAX_PROVIDER_ITERATIONS - 1 ? null : settleContentMismatchError(msg.content, deliveredAnswer);
+                        if (contentMismatch) {
+                            sawSettleContentMismatch = true;
+                            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "engine", event: "engine.settle_content_mismatch", message: "settle answer differs from the reply text written beside it; asking once for the reply as the answer", meta: { answerLength: deliveredAnswer.length, contentLength: msg.content.length } });
+                        }
+                        const retryError = contentMismatch
+                            ?? privateReturnAckLeakError(deliveredAnswer, privateReturnHeldTokens)
                             ?? privateReturnMissingPonderError({
                                 latestUserRequest: latestUserMessageText(messages),
                                 answer: deliveredAnswer,

package/dist/heart/daemon/sanctuary-acceptance-harness.js

@@ -60,7 +60,7 @@ function exactSanctuaryContainmentProfileBoundaries(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
     const boundaries = value;
-    const versions = { "sanctuary-owner": 11, "sanctuary-household": 5, "sanctuary-event": 4 };
+    const versions = { "sanctuary-owner": 12, "sanctuary-household": 5, "sanctuary-event": 4 };
     if (!(0, node_util_1.isDeepStrictEqual)(Object.keys(boundaries).sort(), Object.keys(versions).sort()))
         return false;
     const packageRoot = path.resolve(__dirname, "../../../deploy/unraid/sanctuary.ouro");

package/dist/repertoire/tools.js

@@ -73,7 +73,7 @@ const SANCTUARY_RELATIONSHIP_BASE_TOOLS = new Set([
 exports.SANCTUARY_MCP_PROVIDED_TOOLS = new Set([
     "media_search", "media_request", "media_request_status",
     "media_diagnose_and_fix", "media_chain_health", "media_play_or_resolve",
-    "media_search_now", "media_blocklist_stalled",
+    "media_search_now", "media_blocklist_stalled", "media_episodes", "media_indexer_search", "media_release_search", "media_release_grab", "media_blocklist", "media_manual_import",
 ]);
 /** Channels a Sanctuary turn can arrive on from the host itself, not from a remote party. */
 const SANCTUARY_LOCAL_CHANNELS = new Set(["inner", "cli", "mcp"]);

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.850",
+  "version": "0.1.0-alpha.851",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.850",
+      "version": "0.1.0-alpha.851",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.78.0",
         "@azure/identity": "^4.13.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.850",
+  "version": "0.1.0-alpha.851",
   "engines": {
     "node": ">=22"
   },