@ouro.bot/cli 0.1.0-alpha.853 → 0.1.0-alpha.854

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.854",
+      "changes": [
+        "The Butler gets missing episodes in one call: media_fill_missing re-reads Sonarr, matches releases to episodes only on evidence (episode title, season plus air year, or a Sonarr parse that agrees with the TVDB or scene code), grabs, imports by title, replaces a stalled download only after the stall is confirmed and a seeded replacement is grabbed, searches least recently searched seasons first so repeat calls reach every season, and reports what is on the shelf, in flight, deferred and not found with indexer evidence.",
+        "Long tool-heavy turns get more steps while tools make progress (base 8, +4 per extension, ceiling 24); when the budget runs out the agent settles with a progress report instead of saying it ran out of steps.",
+        "Tools refuse invented parameters by name: media tool schemas are closed, and the engine names an unknown parameter and an enum's allowed values. MCP tools can declare a longer call timeout for slow indexer searches."
+      ]
+    },
     {
       "version": "0.1.0-alpha.853",
       "changes": [

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

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

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

@@ -1145,9 +1145,394 @@ export async function mediaManualImport(a) {
   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 } }
 }
 
+// ------------------------------------------------------- tool: fill missing
+//
+// The whole "get the missing episodes" job as one deterministic pass, so a long
+// request no longer depends on the model chaining a dozen calls correctly
+// (2026-10-03: The Chef Show took an owner hint, a wrong pack, an invented
+// parameter and the step cap). Each call re-reads Sonarr, so it is safe to call
+// again: in-flight grabs are never repeated, and once nothing is missing it says
+// stop. Release names follow streaming numbering, so a release is matched to
+// episodes only on evidence: an episode title, a season plus the air year, or a
+// Sonarr parse whose own numbering agrees with the episode's TVDB or scene code.
+
+const FILL_MAX_GRABS = 3
+const FILL_DEADLINE_MS = 150_000
+const FILL_RECENT_GRAB_MS = 15 * 60_000
+const FILL_EVIDENCE_ROWS = 5
+// A torrent with no ETA is called stalled only after its remaining size has not moved for this long.
+const FILL_STALL_CONFIRM_MS = 30 * 60_000
+
+// Years in a release name, ignoring resolutions such as 1920x1080 and 2160p.
+const yearsIn = (title) => new Set((String(title ?? "").match(/(?<![0-9x])(?:19|20)[0-9]{2}(?![0-9px])/gi) ?? []).map(Number))
+const airYear = (e) => (e.airDate ? Number(String(e.airDate).slice(0, 4)) : null)
+const hasWord = (haystack, needle) => needle.length > 0 && ` ${haystack} `.includes(` ${needle} `)
+const rejectionTexts = (r) => (Array.isArray(r.rejections) ? r.rejections.map((x) => (typeof x === "string" ? x : x?.reason ?? String(x))) : [])
+// "Doctor Who (2005)" and "The Office (US)" are named without the suffix in most releases.
+export const seriesBaseTitle = (title) => normalizeTitle(String(title ?? "").replace(/\s*\((?:19|20)[0-9]{2}\)\s*$/, "").replace(/\s*\((?:us|uk|au|nz|ca)\)\s*$/i, ""))
+
+// An episode title is evidence only when it is distinctive enough not to appear by chance:
+// several words, or one long word that is not a generic release term.
+const GENERIC_TITLE_WORDS = new Set(["special", "specials", "episode", "finale", "premiere", "extended", "complete", "unknown", "untitled", "trailer", "preview", "bonus"])
+function episodeTitleIn(releaseNorm, episode) {
+  const t = normalizeTitle(episode.title)
+  const distinctive = t.includes(" ") ? t.length >= 6 : t.length >= 7 && !GENERIC_TITLE_WORDS.has(t) && !/^[0-9]+$/.test(t)
+  return distinctive && hasWord(releaseNorm, t)
+}
+
+// Season named in a release title: "Season 2", "Temporada 2", "S02" (not "S02E01").
+export function seasonInTitle(title) {
+  const s = String(title ?? "")
+  const word = s.match(/\b(?:season|temporada|saison|staffel)\s*0*([0-9]{1,2})\b/i)
+  if (word) return Number(word[1])
+  const code = s.match(/\bS0*([0-9]{1,2})(?![0-9]|\s*E[0-9])\b/i)
+  return code ? Number(code[1]) : null
+}
+
+// Sonarr's mapping is trusted only when the numbering in the name is the episode's own or scene code.
+function parseAgrees(release, episode) {
+  const season = release.seasonNumber
+  const numbers = Array.isArray(release.episodeNumbers) ? release.episodeNumbers : []
+  const codes = [[episode.seasonNumber, episode.episodeNumber], [episode.sceneSeasonNumber, episode.sceneEpisodeNumber]]
+  return codes.some(([s, e]) => Number.isInteger(s) && s === season && (numbers.length ? numbers.includes(e) : Boolean(release.fullSeason)))
+}
+
+// Which wanted episodes one release really holds, and on what evidence; or why it is unusable.
+export function matchReleaseToEpisodes(release, { seriesId, seriesTitle, seriesYear, wanted, have }) {
+  const title = release.title ?? ""
+  const norm = normalizeTitle(title)
+  const base = seriesBaseTitle(seriesTitle)
+  const rejections = rejectionTexts(release)
+  if (!hasWord(norm, base)) return { reject: "other_series" }
+  if (release.mappedSeriesId && seriesId && release.mappedSeriesId !== seriesId) return { reject: "other_series" }
+  if (rejections.some((x) => /blocklist/i.test(x))) return { reject: "blocklisted" }
+  if (rejections.some((x) => /not wanted in profile|below .*minimum|custom format/i.test(x))) return { reject: "quality_not_wanted" }
+  const wantedYears = new Set(wanted.map(airYear).filter(Boolean))
+  // The series' own premiere year ("Show (2019) Season 2") says nothing about which season it is,
+  // unless the missing episodes aired that year too.
+  const years = new Set([...yearsIn(title)].filter((y) => y !== seriesYear || wantedYears.has(y)))
+  if (years.size && ![...years].some((y) => wantedYears.has(y))) return { reject: "year_mismatch", years: [...years] }
+  // Episode titles are looked for in the name with the series name taken out.
+  const rest = ` ${norm} `.replace(` ${base} `, " ").trim()
+  const byTitle = wanted.filter((e) => episodeTitleIn(rest, e))
+  if (byTitle.length) return { episode_ids: byTitle.map((e) => e.id), basis: "episode_title" }
+  if (have.some((e) => episodeTitleIn(rest, e))) return { reject: "holds_episodes_we_have" }
+  const wantedById = new Map(wanted.map((e) => [e.id, e]))
+  const mapped = (release.mappedEpisodeInfo ?? []).map((e) => e.id).filter((id) => id !== undefined && id !== null)
+  const mappedWanted = mapped.filter((id) => wantedById.has(id))
+  if (mappedWanted.length) {
+    if (mappedWanted.every((id) => parseAgrees(release, wantedById.get(id)))) return { episode_ids: mappedWanted, basis: "sonarr_parse" }
+    return { reject: "parse_disagrees_with_numbering" }
+  }
+  // A season pack named with the season and the air year of the missing episodes
+  // ("The Chef Show [Season 2] (2020)"), whatever Sonarr's scene mapping says it holds.
+  const season = seasonInTitle(title) ?? (release.fullSeason ? release.seasonNumber ?? null : null)
+  if (season !== null && years.size && !/\bE[0-9]{1,3}\b/i.test(title)) {
+    const covered = wanted.filter((e) => e.seasonNumber === season && years.has(airYear(e)))
+    if (covered.length) return { episode_ids: covered.map((e) => e.id), basis: "season_and_air_year" }
+  }
+  return { reject: mapped.length ? "holds_episodes_we_have" : "no_episode_match" }
+}
+
+// Why a download is not going to finish on its own, or null while it may still be moving.
+// `confirmed` is false when the only sign is a missing ETA not yet seen to persist; such a
+// download is reported but never replaced.
+export function stallReason(row, nowMs, previous) {
+  if (isStalledRow(row, nowMs)) return { stall: (row.sizeleft ?? 0) >= (row.size ?? 0) ? "never_started" : "unfinished_for_days", confirmed: true }
+  const left = row.sizeleft ?? 0
+  const ageHours = row.added ? (nowMs - Date.parse(row.added)) / 3_600_000 : 0
+  const moving = row.status === "downloading" || row.status === "warning"
+  const noEta = row.timeleft === undefined || row.timeleft === null || row.timeleft === "00:00:00"
+  if (!(moving && left > 0 && noEta && ageHours >= STALL_AFTER_HOURS)) return null
+  const unchanged = previous && previous.sizeleft === left && nowMs - previous.at >= FILL_STALL_CONFIRM_MS
+  return { stall: "no_peers", confirmed: Boolean(unchanged) }
+}
+
+// Remaining size per download, as first seen at that size, so a later call can tell stopped from slow.
+const progressSeen = new Map()
+const PROGRESS_FORGET_MS = 14 * 24 * 3_600_000
+function observeProgress(downloadId, sizeleft, nowMs) {
+  for (const [k, v] of progressSeen) if (nowMs - v.at > PROGRESS_FORGET_MS) progressSeen.delete(k)
+  const previous = progressSeen.get(downloadId)
+  if (!previous || previous.sizeleft !== sizeleft) progressSeen.set(downloadId, { sizeleft, at: nowMs })
+  return previous
+}
+
+const importDone = (row) => (row.sizeleft ?? 0) === 0 || row.status === "completed"
+const importNeeded = (row) => importDone(row) && ["importPending", "importBlocked", "importFailed"].includes(row.trackedDownloadState)
+
+async function seriesGrabHistory(seriesId) {
+  const list = await sonarr("/history/series", { query: { seriesId, eventType: "grabbed" } })
+  return Array.isArray(list) ? list : []
+}
+
+async function runningImportFor(downloadId) {
+  const list = await sonarr("/command")
+  return (Array.isArray(list) ? list : []).some((c) => c.name === "ManualImport" && ["queued", "started"].includes(c.status)
+    && (c.body?.files ?? []).some((f) => String(f.downloadId ?? "").toUpperCase() === String(downloadId).toUpperCase()))
+}
+
+// Map a finished download's files to the wanted episodes by title. Only a file whose name
+// holds exactly one wanted episode title, and the only file holding it, is imported.
+async function importByTitle(seriesId, seriesTitle, downloadId, wantedEps) {
+  if (await runningImportFor(downloadId)) return { action: "import_already_running", download_id: downloadId }
+  const rows = await previewRows(seriesId, downloadId)
+  const base = seriesBaseTitle(seriesTitle)
+  const picks = []
+  const unmatched = []
+  for (const r of rows) {
+    const rest = ` ${normalizeTitle(`${r.name ?? ""} ${r.relativePath ?? ""}`)} `.replace(` ${base} `, " ").trim()
+    const ids = wantedEps.filter((e) => episodeTitleIn(rest, e)).map((e) => e.id)
+    if (ids.length === 1) picks.push({ row: r, ids })
+    else unmatched.push(r.name ?? r.path)
+  }
+  const counts = new Map()
+  for (const p of picks) counts.set(p.ids[0], (counts.get(p.ids[0]) ?? 0) + 1)
+  const unique = picks.filter((p) => counts.get(p.ids[0]) === 1)
+  for (const p of picks) if (!unique.includes(p)) unmatched.push(p.row.name ?? p.row.path)
+  if (!unique.length) {
+    return { action: "import_needs_mapping", download_id: downloadId, unmatched_files: unmatched,
+             note: "No file names an episode title. Map them with media_manual_import (preview, then import by title from media_episodes)." }
+  }
+  const files = unique.map(({ row: r, ids }) => ({ path: r.path, seriesId, episodeIds: ids, quality: r.quality, languages: r.languages, releaseGroup: r.releaseGroup ?? "",
+    indexerFlags: r.indexerFlags ?? 0, releaseType: r.releaseType ?? "unknown", downloadId }))
+  const c = await sonarr("/command", { method: "POST", body: { name: "ManualImport", files, importMode: "auto" } })
+  return { action: "imported_by_title", download_id: downloadId, command_id: c?.id ?? null,
+           files: unique.map(({ row: r, ids }) => ({ file: r.name ?? r.path, episode_ids: ids })), ...(unmatched.length ? { unmatched_files: unmatched } : {}) }
+}
+
+const pct = (row) => ((row.size ?? 0) > 0 ? Math.round((((row.size ?? 0) - (row.sizeleft ?? 0)) / row.size) * 1000) / 10 : null)
+const fillRunning = new Set()
+// When each season or episode of a series was last searched, so repeat calls reach the ones a deadline cut off.
+const lastSearched = new Map()
+const FILL_ACTION_GRACE_MS = 45_000
+
+export async function mediaFillMissing(a, opts = {}) {
+  const found = await resolveLibraryItem({ kind: "series", service_id: a.service_id, title: a.series })
+  if (!found.item) return { result: found.result, candidates: found.candidates, message: "Name the series by its Sonarr service_id or exact title." }
+  const seriesId = found.item.id
+  // One pass per series at a time: a retry after a timeout must not grab beside a pass still running.
+  if (fillRunning.has(seriesId)) return { result: "already_running", series_id: seriesId, message: "A media_fill_missing pass for this series is still working. Wait a minute and call again; do not act by hand." }
+  fillRunning.add(seriesId)
+  try {
+    return await fillPass(a, seriesId, found.item.title, opts)
+  } finally {
+    fillRunning.delete(seriesId)
+  }
+}
+
+async function fillPass(a, seriesId, seriesTitle, { nowMs = Date.now(), deadlineMs = FILL_DEADLINE_MS } = {}) {
+  const startedAt = Date.now()
+  const remainingMs = () => deadlineMs - (Date.now() - startedAt)
+  const timeLeft = () => remainingMs() > 0
+  // Grabs and imports may run a little past the search deadline, never past the harness timeout.
+  const mayAct = () => remainingMs() > -FILL_ACTION_GRACE_MS
+  const errors = []
+  // Each step after the first reads is isolated: one failure is reported, the rest of the pass and its record survive.
+  const attempt = async (step, fn) => {
+    try { return await fn() } catch (e) { errors.push({ step, error: e.code ?? "failed", message: e.message }); return undefined }
+  }
+  const seriesYear = Number((await attempt("read series", () => sonarr(`/series/${seriesId}`)))?.year) || null
+  const season = a.season_number === undefined || a.season_number === null ? null : Number(a.season_number)
+  const scope = (await seriesEpisodes(seriesId, season ?? undefined)).filter((e) => (season === null ? e.seasonNumber > 0 : true))
+  const aired = (e) => Boolean(e.airDateUtc ?? e.airDate) && Date.parse(e.airDateUtc ?? e.airDate) <= nowMs
+  const missing = scope.filter((e) => !e.hasFile && aired(e))
+  const wanted = missing.filter((e) => e.monitored)
+  const have = scope.filter((e) => e.hasFile)
+  const code = (e) => ({ episode_id: e.id, code: sxe(e), title: e.title ?? null, air_date: e.airDate ?? null })
+  const base = { series_id: seriesId, series: seriesTitle, season_number: season, checked_at: new Date(nowMs).toISOString(),
+                 on_shelf: { count: have.length, of: scope.filter(aired).length },
+                 ...(missing.length > wanted.length ? { not_monitored_missing: missing.filter((e) => !e.monitored).map(code) } : {}) }
+  if (!wanted.length) {
+    return { ...base, goal_met: true, in_flight: [], not_found: [], actions: [],
+             summary: `Nothing monitored is missing: ${have.length} of ${base.on_shelf.of} aired episodes are on the shelf.`,
+             next_step: "Goal met. Stop here and tell the owner; do not search or grab anything else." }
+  }
+
+  const actions = []
+  const byId = new Map(wanted.map((e) => [e.id, e]))
+  const queue = await itemQueue("series", seriesId)
+  const history = await seriesGrabHistory(seriesId)
+  const grabbedFor = new Map()
+  for (const h of history) {
+    // A client without download ids (e.g. a blackhole) is tracked by release title instead.
+    const key = h.downloadId ? String(h.downloadId).toUpperCase() : h.sourceTitle ? `TITLE:${normalizeTitle(h.sourceTitle)}` : null
+    if (!key) continue
+    if (!grabbedFor.has(key)) grabbedFor.set(key, { ids: new Set(), date: h.date, title: h.sourceTitle })
+    grabbedFor.get(key).ids.add(h.episodeId)
+  }
+  // Sonarr re-parses a tracked download's name, so its queue rows can point at the
+  // wrong episodes; the grab history keeps the mapping the grab was made with.
+  const downloads = new Map()
+  for (const r of queue) {
+    const key = String(r.downloadId ?? `row:${r.id}`).toUpperCase()
+    if (!downloads.has(key)) downloads.set(key, { key, row: r, ids: new Set(grabbedFor.get(key)?.ids ?? []) })
+    if (!grabbedFor.has(key)) downloads.get(key).ids.add(r.episodeId)
+  }
+  const queuedTitles = new Set(queue.map((r) => normalizeTitle(r.title)))
+  for (const [key, g] of grabbedFor) {
+    const recent = nowMs - Date.parse(g.date) < FILL_RECENT_GRAB_MS
+    if (recent && !downloads.has(key) && !queuedTitles.has(normalizeTitle(g.title))) downloads.set(key, { key, row: null, ids: g.ids, title: g.title })
+  }
+
+  let cutShort = false
+  const covered = new Set()
+  const stalled = []
+  const inFlight = []
+  for (const d of downloads.values()) {
+    const ids = wanted.map((e) => e.id).filter((id) => d.ids.has(id))
+    if (!ids.length) continue
+    const entry = { title: d.row?.title ?? d.title ?? null, download_id: d.row?.downloadId ?? d.key, episodes: ids.map((id) => sxe(byId.get(id))) }
+    if (!d.row) { inFlight.push({ ...entry, state: "just_grabbed" }); ids.forEach((id) => covered.add(id)); continue }
+    if (importNeeded(d.row)) {
+      const done = mayAct() ? await attempt(`import ${d.row.downloadId}`, () => importByTitle(seriesId, seriesTitle, d.row.downloadId, ids.map((id) => byId.get(id)))) : undefined
+      if (done) actions.push(done)
+      inFlight.push({ ...entry, state: done?.action === "import_needs_mapping" ? "downloaded_needs_mapping" : done ? "importing" : mayAct() ? "downloaded_import_failed" : "downloaded_import_next_call" })
+      if (!done) cutShort = true
+      ids.forEach((id) => covered.add(id))
+      continue
+    }
+    const why = stallReason(d.row, nowMs, observeProgress(d.key, d.row.sizeleft ?? 0, nowMs))
+    const info = { ...entry, percent: pct(d.row), queue_id: d.row.id, added: d.row.added ?? null }
+    if (why) stalled.push({ ...info, ids, ...why })
+    else { inFlight.push({ ...info, state: importDone(d.row) ? "importing" : "downloading" }); ids.forEach((id) => covered.add(id)) }
+  }
+
+  // Search for everything not covered by a moving download, stalled ones included.
+  const need = wanted.filter((e) => !covered.has(e.id))
+  const searched = []
+  const searchedSeasons = new Set()
+  const searchedEpisodes = new Set()
+  const candidates = new Map()
+  const rejected = new Map()
+  const inFlightTitles = new Set([...downloads.values()].map((d) => normalizeTitle(d.row?.title ?? d.title)).filter(Boolean))
+  const consider = (raw) => {
+    for (const r of Array.isArray(raw) ? raw : []) {
+      if (!r?.guid || candidates.has(r.guid) || rejected.has(r.guid)) continue
+      const m = matchReleaseToEpisodes(r, { seriesId, seriesTitle, seriesYear, wanted: need, have })
+      const sameAsInFlight = inFlightTitles.has(normalizeTitle(r.title))
+      if (m.reject || sameAsInFlight) { rejected.set(r.guid, { title: r.title ?? null, seeders: r.seeders ?? null, reason: sameAsInFlight ? "same_release_as_stalled_download" : m.reject }); continue }
+      cacheRelease(`series:${r.guid}`, { ...releaseRow("series", r), service_id: seriesId, season_number: null, quality_raw: r.quality ?? null, languages_raw: r.languages ?? null })
+      candidates.set(r.guid, { raw: r, ids: m.episode_ids, basis: m.basis })
+    }
+  }
+  const searchTimeout = () => Math.max(5_000, Math.min(SEARCH_TIMEOUT_MS, remainingMs()))
+  const hasSeededCandidate = (e) => [...candidates.values()].some((c) => (c.raw.seeders ?? 0) > 0 && c.ids.includes(e.id))
+  const searchedAt = (key) => lastSearched.get(`${seriesId}:${key}`) ?? 0
+  const markSearched = (key) => lastSearched.set(`${seriesId}:${key}`, Date.now())
+  // Least recently searched first, so a deadline never starves the same seasons on every call.
+  const seasons = [...new Set(need.map((e) => e.seasonNumber))].sort((x, y) => searchedAt(`s${x}`) - searchedAt(`s${y}`) || x - y)
+  for (const s of seasons) {
+    if (!timeLeft()) break
+    searchedSeasons.add(s)
+    markSearched(`s${s}`)
+    searched.push(`Sonarr season search S${code2(s)}`)
+    consider(await attempt(`season search S${code2(s)}`, () => sonarr("/release", { query: { seriesId, seasonNumber: s }, timeoutMs: searchTimeout() })))
+  }
+  const episodeOrder = need.filter((x) => !hasSeededCandidate(x)).sort((x, y) => searchedAt(`e${x.id}`) - searchedAt(`e${y.id}`))
+  for (const e of episodeOrder.slice(0, MAX_EPISODE_SEARCHES)) {
+    if (!timeLeft()) break
+    searchedEpisodes.add(e.id)
+    markSearched(`e${e.id}`)
+    searched.push(`Sonarr episode search ${sxe(e)}`)
+    consider(await attempt(`episode search ${sxe(e)}`, () => sonarr("/release", { query: { episodeId: e.id }, timeoutMs: searchTimeout() })))
+  }
+
+  // Seeded releases first, then the ones that cover the most, then the best seeded.
+  const ranked = [...candidates.values()].sort((x, y) =>
+    Number((y.raw.seeders ?? 0) > 0) - Number((x.raw.seeders ?? 0) > 0) || y.ids.length - x.ids.length || (y.raw.seeders ?? 0) - (x.raw.seeders ?? 0))
+  const remaining = new Set(need.map((e) => e.id))
+  const stalledIds = new Set(stalled.flatMap((s) => s.ids))
+  // Until a stall is confirmed on a later call, its episodes are not fetched a second time.
+  const unconfirmedIds = new Set(stalled.filter((s) => !s.confirmed).flatMap((s) => s.ids))
+  for (const s of stalled.filter((x) => !x.confirmed)) {
+    s.alternative = ranked.some((c) => (c.raw.seeders ?? 0) > 0 && s.ids.every((id) => c.ids.includes(id)))
+  }
+  const deferred = new Set()
+  let grabs = 0
+  for (const c of ranked) {
+    const seeded = (c.raw.seeders ?? 0) > 0
+    // An unseeded release is no better than a stalled download: never fetch those episodes twice that way.
+    const ids = c.ids.filter((id) => remaining.has(id) && !unconfirmedIds.has(id) && (seeded || !stalledIds.has(id)))
+    if (!ids.length || !c.raw.quality) continue
+    if (grabs >= FILL_MAX_GRABS || !mayAct()) { ids.forEach((id) => deferred.add(id)); cutShort ||= !mayAct(); continue }
+    const body = { guid: c.raw.guid, indexerId: c.raw.indexerId, seriesId, episodeIds: ids, shouldOverride: true, quality: c.raw.quality, languages: Array.isArray(c.raw.languages) ? c.raw.languages : [] }
+    const res = await attempt(`grab ${c.raw.title}`, async () => (await sonarr("/release", { method: "POST", body })) ?? {})
+    if (!res) continue
+    grabs += 1
+    ids.forEach((id) => remaining.delete(id))
+    actions.push({ action: "grabbed", title: c.raw.title ?? null, indexer: c.raw.indexer ?? null, seeders: c.raw.seeders ?? null, matched_by: c.basis,
+                   episodes: ids.map((id) => sxe(byId.get(id))), download_id: res.downloadId ?? null, ...(seeded ? {} : { may_never_finish: true }) })
+    inFlight.push({ title: c.raw.title ?? null, download_id: res.downloadId ?? null, episodes: ids.map((id) => sxe(byId.get(id))), state: "just_grabbed" })
+    // Only after the replacement is grabbed, and only for a confirmed stall it fully covers with a seeded release.
+    if (!seeded) continue
+    for (const s of stalled.filter((x) => !x.replaced && x.confirmed && x.ids.every((id) => ids.includes(id)))) {
+      const removed = await attempt(`blocklist ${s.title}`, async () => { await sonarr(`/queue/${s.queue_id}`, { method: "DELETE", query: { removeFromClient: true, blocklist: true, skipRedownload: true } }); return true })
+      if (!removed) continue
+      s.replaced = true
+      actions.push({ action: "blocklisted_stalled", title: s.title, percent: s.percent, stall: s.stall })
+    }
+  }
+  for (const s of stalled.filter((x) => !x.replaced)) {
+    const alsoGrabbed = s.ids.every((id) => !remaining.has(id))
+    inFlight.push({ title: s.title, download_id: s.download_id, episodes: s.episodes, percent: s.percent, queue_id: s.queue_id, added: s.added, state: "stalled", stall: s.stall,
+                    ...(s.confirmed ? {} : { stall_confirmed: false }),
+                    note: !s.confirmed && s.alternative ? "A seeded alternative exists; a later call replaces this download once the stall is confirmed (no progress for 30 minutes)."
+                      : alsoGrabbed ? "Releases for some of these episodes were grabbed; this download was kept for the rest."
+                      : "No other usable release was found, so this download was kept in case peers return." })
+    s.ids.forEach((id) => remaining.delete(id))
+  }
+
+  const open = need.filter((e) => remaining.has(e.id) && !deferred.has(e.id))
+  const unsearched = open.filter((e) => !searchedSeasons.has(e.seasonNumber) && !searchedEpisodes.has(e.id))
+  const notFound = open.filter((e) => !unsearched.includes(e)).map(code)
+  const stuck = inFlight.filter((x) => x.state === "stalled")
+  let evidence
+  if ((notFound.length || stuck.length) && timeLeft()) {
+    // What exists on the indexers under any name, so a "can't find it" is backed by a listing. Best effort.
+    evidence = []
+    const target = notFound.length ? need.filter((e) => notFound.some((n) => n.episode_id === e.id)) : wanted
+    const ys = [...new Set(target.map((e) => e.airDate?.slice(0, 4)).filter(Boolean))].slice(0, 2)
+    const scene = [...new Set(target.map((e) => e.sceneSeasonNumber).filter((n) => Number.isInteger(n)))].slice(0, 1)
+    const queries = [...(ys.length ? ys : [""]).map((y) => `${seriesTitle} ${y}`.trim()), ...scene.map((n) => `${seriesTitle} S${code2(n)}`)]
+    for (const q of queries) {
+      if (!timeLeft()) break
+      const raw = await attempt(`indexer evidence "${q}"`, () => prowlarr("/search", { query: { query: q, type: "search", limit: 100 }, timeoutMs: searchTimeout() }))
+      if (!Array.isArray(raw)) continue
+      // Indexers answer free text loosely ("Vegas Chef Prizefight"); keep only releases named for this series.
+      const own = raw.filter((r) => hasWord(normalizeTitle(r.title), seriesBaseTitle(seriesTitle)))
+      const rows = own.sort((x, y) => (y.seeders ?? -1) - (x.seeders ?? -1)).slice(0, FILL_EVIDENCE_ROWS)
+      evidence.push({ query: q, results: own.length, top: rows.map((r) => ({ title: r.title ?? null, seeders: r.seeders ?? null, indexer: r.indexer ?? null })) })
+    }
+  }
+  const incomplete = cutShort || deferred.size > 0 || unsearched.length > 0 || !timeLeft() || errors.length > 0
+  const moving = inFlight.filter((x) => x.state !== "stalled").length
+  const summary = [
+    `${have.length} of ${base.on_shelf.of} aired episodes are on the shelf; ${wanted.length} monitored ${wanted.length === 1 ? "episode is" : "episodes are"} missing.`,
+    grabs ? `Grabbed ${grabs} release${grabs === 1 ? "" : "s"} now.` : "",
+    moving ? `${moving} download(s) in progress.` : "",
+    stuck.length ? `${stuck.length} download(s) stalled with no peers and no other usable release (${stuck.map((s) => `${s.title} at ${s.percent}%`).join("; ")}).` : "",
+    notFound.length ? `No usable release found for ${notFound.map((e) => e.code).join(", ")}.` : "",
+    deferred.size || unsearched.length ? `${deferred.size + unsearched.length} episode(s) not handled yet in this pass.` : "",
+    errors.length ? `${errors.length} step(s) failed: ${errors.map((x) => x.step).join("; ")}.` : "",
+  ].filter(Boolean).join(" ")
+  const nextStep = incomplete
+    ? "This pass did not finish everything. Tell the owner what it did, then call media_fill_missing again to continue; do not act by hand."
+    : stuck.length || notFound.length
+      ? "Tell the owner exactly this outcome with the evidence; do not grab, import or blocklist anything by hand. Call media_fill_missing again later to retry."
+      : "Work is in progress. Tell the owner what is downloading; call media_fill_missing again later to import and confirm. Do not search or grab anything else now."
+  return { ...base, goal_met: false, in_flight: inFlight, not_found: notFound, actions,
+           ...(deferred.size ? { deferred: need.filter((e) => deferred.has(e.id)).map(code) } : {}), ...(unsearched.length ? { unsearched: unsearched.map(code) } : {}),
+           searched, ...(rejected.size ? { rejected_releases: [...rejected.values()].slice(0, 12) } : {}), ...(evidence ? { indexer_evidence: evidence } : {}),
+           ...(errors.length ? { errors } : {}), ...(incomplete ? { incomplete: true } : {}), summary, next_step: nextStep }
+}
+
 // ------------------------------------------------------------------- schema
 
-export const TOOLS = [
+// The harness waits 30 s for a tool call unless the tool declares longer; indexer searches can take minutes.
+const TIMEOUT_META_KEY = "ouro.bot/timeoutMs"
+
+const TOOL_LIST = [
   {
     name: "media_search",
     annotations: { readOnlyHint: true },
@@ -1226,6 +1611,16 @@ export const TOOLS = [
       research: { type: "boolean", description: "Search again afterwards. Default true." },
     }, required: ["kind", "service_id"] },
   },
+  {
+    name: "media_fill_missing",
+    _meta: { [TIMEOUT_META_KEY]: 240_000 },
+    description: "Get a series' missing episodes, start to finish, in one call. Use this first whenever the owner asks why episodes are missing or asks to get them. It re-reads Sonarr, finds the monitored aired episodes without files, searches the indexers, matches releases to episodes by episode title and air year as well as Sonarr's parse (so streaming-volume numbering cannot fool it), prefers seeded releases, skips packs of episodes already on the shelf, grabs with the right episode mapping, imports finished downloads by title, and replaces a stalled download when a usable alternative exists. Returns on_shelf, in_flight, not_found, actions, indexer_evidence, summary and next_step. Safe to call again: it never grabs what is already in flight. When goal_met is true, stop. Report summary and next_step as they are; do not redo its steps by hand.",
+    inputSchema: { type: "object", properties: {
+      series: { type: "string", description: "Series title as the owner said it." },
+      service_id: { type: "number", description: "Sonarr series id, when known." },
+      season_number: { type: "number", description: "Limit to one season. Omit for the whole series (specials excluded)." },
+    } },
+  },
   {
     name: "media_episodes",
     annotations: { readOnlyHint: true },
@@ -1238,6 +1633,7 @@ export const TOOLS = [
   {
     name: "media_indexer_search",
     annotations: { readOnlyHint: true },
+    _meta: { [TIMEOUT_META_KEY]: 200_000 },
     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" },
@@ -1247,6 +1643,7 @@ export const TOOLS = [
   {
     name: "media_release_search",
     annotations: { readOnlyHint: true },
+    _meta: { [TIMEOUT_META_KEY]: 240_000 },
     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"] },
@@ -1291,6 +1688,25 @@ export const TOOLS = [
   },
 ]
 
+// Every schema is closed: an argument the tool does not define (an invented dry_run,
+// a misspelled id) is refused with its name, never silently ignored.
+function closeSchema(schema) {
+  if (!schema || typeof schema !== "object" || schema.type !== "object") return schema
+  const properties = Object.fromEntries(Object.entries(schema.properties ?? {}).map(([k, v]) => [k, v?.type === "array" && v.items ? { ...v, items: closeSchema(v.items) } : closeSchema(v)]))
+  return { ...schema, properties, additionalProperties: false }
+}
+
+export const TOOLS = TOOL_LIST.map((t) => ({ ...t, inputSchema: closeSchema(t.inputSchema) }))
+
+// The same check inside the server, for any caller that does not validate against the schema.
+export function unknownArguments(toolName, args) {
+  const tool = TOOLS.find((t) => t.name === toolName)
+  const allowed = Object.keys(tool?.inputSchema?.properties ?? {})
+  const unknown = Object.keys(args ?? {}).filter((k) => !allowed.includes(k))
+  return unknown.length ? { error: "unknown_parameter", unknown, allowed,
+    message: `${toolName} does not take ${unknown.map((k) => `'${k}'`).join(", ")}. It accepts only: ${allowed.join(", ") || "no parameters"}. Call it again without the unknown parameter.` } : null
+}
+
 const HANDLERS = {
   media_search: mediaSearch,
   media_request: mediaRequest,
@@ -1301,6 +1717,7 @@ const HANDLERS = {
   media_search_now: mediaSearchNow,
   media_blocklist_stalled: mediaBlocklistStalled,
   media_episodes: mediaEpisodes,
+  media_fill_missing: mediaFillMissing,
   media_indexer_search: mediaIndexerSearch,
   media_release_search: mediaReleaseSearch,
   media_release_grab: mediaReleaseGrab,
@@ -1331,6 +1748,8 @@ async function handle(msg) {
                         human_action_reason: credError }
       return send({ jsonrpc: "2.0", id, result: { isError: true, content: [{ type: "text", text: JSON.stringify(payload, null, 1) }] } })
     }
+    const unknown = unknownArguments(params.name, params.arguments)
+    if (unknown) return send({ jsonrpc: "2.0", id, result: { isError: true, content: [{ type: "text", text: JSON.stringify(unknown, 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) }] } })

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

@@ -15,4 +15,7 @@
 - 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.
+- When episodes are missing, or Ari asks to get them, call `media_fill_missing` first. It re-reads Sonarr, matches releases by episode title and air year, grabs, imports by title and replaces stalled downloads in one call, and it is safe to call again. Relay its `summary` with the evidence it returns and follow its `next_step`; do not redo its steps by hand. When it reports `goal_met`, or an episode Ari asked for is imported, stop: say so and end the turn without further probing.
+- Before stating whether an episode is monitored, missing, downloading or on disk, read it from a tool in this turn (`media_fill_missing` or `media_episodes`). Never infer it from an earlier reply or from a tool that did not report it.
+- Use only the parameters a tool lists. If a call is refused for an unknown parameter or a wrong value, read the allowed ones from the refusal and call again correctly; never invent flags such as `dry_run`.
+- When an automatic search finds nothing for episodes that exist and `media_fill_missing` cannot place them, 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": 12,
+      "version": 13,
       "contextScopes": [
         "household.status",
         "household.policy",
@@ -72,7 +72,8 @@
         "media_release_search",
         "media_release_grab",
         "media_blocklist",
-        "media_manual_import"
+        "media_manual_import",
+        "media_fill_missing"
       ],
       "effectScopes": [
         "telegram.proactive",
@@ -140,7 +141,7 @@
       ]
     },
     "sanctuary-agent-peer": {
-      "version": 3,
+      "version": 4,
       "toolNames": [
         "external_event_disposition",
         "query_active_work",
@@ -203,7 +204,8 @@
         "media_release_search",
         "media_release_grab",
         "media_blocklist",
-        "media_manual_import"
+        "media_manual_import",
+        "media_fill_missing"
       ],
       "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.853</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.854</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/heart/core.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_PROVIDER_ITERATIONS = void 0;
+exports.MAX_PROVIDER_ITERATIONS_CEILING = exports.STEP_BUDGET_EXTENSION = exports.MAX_PROVIDER_ITERATIONS = void 0;
 exports.validateToolCallBatchAtProductionBoundary = validateToolCallBatchAtProductionBoundary;
 exports.createProviderRegistry = createProviderRegistry;
 exports.getProviderRuntime = getProviderRuntime;
@@ -274,7 +274,13 @@ function createHabitCallbackBuffer(callbacks) {
 function createFinalOnlyTextBuffer(callbacks) {
     return createCallbackBuffer(callbacks, "text-only");
 }
+/** Base per-turn provider-call budget. Grows while tool calls keep making progress. */
 exports.MAX_PROVIDER_ITERATIONS = 8;
+/** How many provider calls each progress-earned extension adds. */
+exports.STEP_BUDGET_EXTENSION = 4;
+/** Hard ceiling on the per-turn provider-call budget, however much progress is made. */
+exports.MAX_PROVIDER_ITERATIONS_CEILING = 24;
+const STEP_BUDGET_REPORT_INSTRUCTION = "the step budget for this turn is used up. do not call any more work tools; none of the tool calls in your last message were executed. call settle now with a short progress report: what is done (with evidence from tool results above), what is still in flight, and what you will do next. say you can continue where you left off when the conversation resumes.";
 function continuationCallbacks(callbacks, text) {
     const noop = () => undefined;
     return {
@@ -1164,6 +1170,20 @@ async function runAgent(messages, callbacks, channel, signal, options) {
     let unresolvedHistoricalEffects = [];
     let historicalToolFailureRetries = 0;
     let providerIterations = 0;
+    // Adaptive step budget: starts at the base, grows while tool calls make progress.
+    let stepBudget = exports.MAX_PROVIDER_ITERATIONS;
+    let lastIterationMadeProgress = false;
+    let stepReportIteration = null;
+    const budgetExhausted = () => {
+        if (providerIterations < stepBudget)
+            return false;
+        if (lastIterationMadeProgress && stepBudget < exports.MAX_PROVIDER_ITERATIONS_CEILING) {
+            stepBudget = Math.min(exports.MAX_PROVIDER_ITERATIONS_CEILING, stepBudget + exports.STEP_BUDGET_EXTENSION);
+            (0, runtime_1.emitNervesEvent)({ component: "engine", event: "engine.step_budget_extended", message: "tool progress extended the per-turn step budget", meta: { stepBudget } });
+            return providerIterations >= stepBudget;
+        }
+        return true;
+    };
     const requiredToolCallNames = [...new Set(options?.requiredToolCalls?.names ?? [])];
     const dispatchedRequiredToolCalls = new Set();
     const rejectAttempt = (assistant, controls) => {
@@ -1182,8 +1202,8 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             : null;
     };
     const queueRequiredCorrection = (assistant, message, limitContext) => {
-        if (providerIterations >= exports.MAX_PROVIDER_ITERATIONS)
-            throw new Error(`provider iteration limit exhausted at response ${exports.MAX_PROVIDER_ITERATIONS} ${limitContext}`);
+        if (budgetExhausted())
+            throw new Error(`provider iteration limit exhausted at response ${stepBudget} ${limitContext}`);
         rejectAttempt(assistant, [{ role: "user", content: message }]);
     };
     const toolLoopState = (0, tool_loop_1.createToolLoopState)();
@@ -1323,9 +1343,11 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 .map((effect) => effect.name)
                 .filter((name) => candidateToolNames.has(name)));
             const forcingHistoricalEffect = forcedHistoricalToolNames.size > 0;
-            const activeTools = forcingHistoricalEffect
-                ? candidateActiveTools.filter((tool) => forcedHistoricalToolNames.has(tool.function.name))
-                : candidateActiveTools;
+            const activeTools = stepReportIteration !== null
+                ? candidateActiveTools.filter((tool) => tool.function.name === "settle")
+                : forcingHistoricalEffect
+                    ? candidateActiveTools.filter((tool) => forcedHistoricalToolNames.has(tool.function.name))
+                    : candidateActiveTools;
             const activeToolNames = new Set(activeTools.map((tool) => tool.function.name));
             const steeringFollowUps = options?.drainSteeringFollowUps?.() ?? [];
             if (steeringFollowUps.length > 0) {
@@ -1482,8 +1504,12 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 const result = attempt.value;
                 nextAttemptControls = [];
                 providerIterations += 1;
-                if (providerIterations === exports.MAX_PROVIDER_ITERATIONS && result.toolCalls.length > 0) {
-                    throw new Error(`provider iteration limit exhausted at response ${exports.MAX_PROVIDER_ITERATIONS} before tool execution`);
+                if (stepReportIteration !== null) {
+                    // The progress-report call is the last one: it must settle, or the turn errors.
+                    const settledReport = result.toolCalls.length === 1 && result.toolCalls[0].name === "settle";
+                    if (providerIterations > stepReportIteration || (result.toolCalls.length > 0 && !settledReport)) {
+                        throw new Error(`provider iteration limit exhausted at response ${providerIterations} before the progress report settled`);
+                    }
                 }
                 const streamCallbackBuffer = turnCallbackBufferRef.current;
                 turnCallbackBufferRef.current = null;
@@ -1550,6 +1576,24 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 if (thinkingItems.length > 0) {
                     msg._thinking_blocks = thinkingItems;
                 }
+                const settlingNow = result.toolCalls.length === 1 && result.toolCalls[0].name === "settle";
+                if (stepReportIteration === null && result.toolCalls.length > 0 && !settlingNow && budgetExhausted()) {
+                    if (!candidateToolNames.has("settle")) {
+                        throw new Error(`provider iteration limit exhausted at response ${stepBudget} before tool execution`);
+                    }
+                    // Do not error into the reply: give the model one settle-only call to report progress.
+                    streamCallbackBuffer?.discard();
+                    stepReportIteration = providerIterations + 1;
+                    rejectAttempt(msg, [
+                        ...result.toolCalls.map((tc) => ({ role: "tool", tool_call_id: tc.id, content: "not executed: the step budget for this turn is used up." })),
+                        { role: "user", content: STEP_BUDGET_REPORT_INSTRUCTION },
+                    ]);
+                    callbacks.onClearText?.();
+                    (0, runtime_1.emitNervesEvent)({ level: "warn", component: "engine", event: "engine.step_budget_exhausted", message: "step budget used up; requesting a settle-only progress report", meta: { stepBudget, providerIterations } });
+                    continue;
+                }
+                if (result.toolCalls.length > 0)
+                    lastIterationMadeProgress = false;
                 // Phase annotation for Codex provider
                 const hasPhaseAnnotation = providerRuntime.capabilities.has("phase-annotation");
                 const isSoleSettle = result.toolCalls.length === 1 && result.toolCalls[0].name === "settle";
@@ -1908,7 +1952,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         // answer before ordinary settle handling reaches this point.
                         const deliveredAnswer = answer;
                         // 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);
+                        const contentMismatch = sawSettleContentMismatch || providerIterations >= stepBudget - 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 } });
@@ -2446,6 +2490,8 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                             invoked,
                             sideEffect: success && toolRiskProfile?.mutates !== "none",
                         });
+                        if (success && !(0, tool_loop_1.hasRecordedToolCall)(toolLoopState, tc.name, args))
+                            lastIterationMadeProgress = true;
                         (0, tool_loop_1.recordToolOutcome)(toolLoopState, tc.name, args, modelResult, success);
                         callbacks.onToolEnd(tc.name, (0, tools_1.buildToolResultSummary)(tc.name, args, modelResult, success, toolSelection), success);
                         callbacks.onToolResult?.(messages);

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": 12, "sanctuary-household": 5, "sanctuary-event": 4 };
+    const versions = { "sanctuary-owner": 13, "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/heart/tool-loop.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GLOBAL_CIRCUIT_BREAKER_LIMIT = exports.PING_PONG_WINDOW = exports.GENERIC_REPEAT_LIMIT = exports.POLL_NO_PROGRESS_LIMIT = exports.TOOL_LOOP_HISTORY_LIMIT = void 0;
 exports.createToolLoopState = createToolLoopState;
 exports.recordToolOutcome = recordToolOutcome;
+exports.hasRecordedToolCall = hasRecordedToolCall;
 exports.detectToolLoop = detectToolLoop;
 const crypto = __importStar(require("crypto"));
 const runtime_1 = require("../nerves/runtime");
@@ -178,6 +179,11 @@ function recordToolOutcome(state, toolName, args, result, success) {
         state.history.splice(0, state.history.length - exports.TOOL_LOOP_HISTORY_LIMIT);
     }
 }
+/** True when this exact call (tool name + canonicalized arguments) was already recorded this turn. */
+function hasRecordedToolCall(state, toolName, args) {
+    const callHash = digest(normalizeArgs(toolName, args));
+    return state.history.some((record) => record.toolName === toolName && record.callHash === callHash);
+}
 // Tools that must never be blocked by the circuit breaker.
 // settle = end the turn, surface = deliver results outward.
 // ponder = continue thinking (private runtime) or hand off to private runtime (outer).

package/dist/repertoire/mcp-client.js

@@ -1,14 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.McpClient = void 0;
+exports.McpClient = exports.MCP_TOOL_TIMEOUT_META_KEY = void 0;
 exports.isMcpTransportError = isMcpTransportError;
 const child_process_1 = require("child_process");
 const readline_1 = require("readline");
 const runtime_1 = require("../nerves/runtime");
 const runtime_cwd_1 = require("../heart/runtime-cwd");
+/** Metadata key a server uses to declare how long one call to a tool may take. */
+exports.MCP_TOOL_TIMEOUT_META_KEY = "ouro.bot/timeoutMs";
+const MAX_TOOL_CALL_TIMEOUT = 600_000;
 const MCP_PROTOCOL_VERSION = "2024-11-05";
 const DEFAULT_REQUEST_TIMEOUT = 10_000;
 const DEFAULT_TOOL_CALL_TIMEOUT = 30_000;
+const MIN_TOOL_CALL_TIMEOUT = 1_000;
 function isMcpTransportError(error) {
     const message = error instanceof Error ? error.message : String(error);
     const normalized = message.toLowerCase();
@@ -97,11 +101,19 @@ class McpClient {
         this.cachedTools = allTools;
         return allTools;
     }
+    /** A tool that searches slow services may declare a longer timeout; it is clamped to 1 s .. 10 min. */
+    declaredToolTimeout(name) {
+        const declared = this.cachedTools?.find((tool) => tool.name === name)?._meta?.[exports.MCP_TOOL_TIMEOUT_META_KEY];
+        if (typeof declared !== "number" || !Number.isFinite(declared))
+            return DEFAULT_TOOL_CALL_TIMEOUT;
+        return Math.min(Math.max(Math.round(declared), MIN_TOOL_CALL_TIMEOUT), MAX_TOOL_CALL_TIMEOUT);
+    }
     async refreshTools() {
         this.cachedTools = null;
         return this.listTools();
     }
-    async callTool(name, args, timeout = DEFAULT_TOOL_CALL_TIMEOUT) {
+    async callTool(name, args, timeoutOverride) {
+        const timeout = timeoutOverride ?? this.declaredToolTimeout(name);
         (0, runtime_1.emitNervesEvent)({
             event: "mcp.tool_call_start",
             component: "repertoire",

package/dist/repertoire/tool-arguments.js

@@ -66,8 +66,20 @@ function canonicalize(value) {
 function digest(value) {
     return (0, node_crypto_1.createHash)("sha256").update(value, "utf8").digest("hex");
 }
+// The model reads these: name the offending parameter and the allowed values so it
+// can correct the call instead of guessing again (e.g. an invented dry_run flag).
+function renderError(error) {
+    const where = error.instancePath || "/";
+    if (error.keyword === "additionalProperties") {
+        return `${where} has unknown parameter '${String(error.params.additionalProperty)}': this tool does not accept it; use only the parameters in its schema`;
+    }
+    if (error.keyword === "enum" && Array.isArray(error.params.allowedValues)) {
+        return `${where} must be one of: ${error.params.allowedValues.map((value) => JSON.stringify(value)).join(", ")}`;
+    }
+    return `${where} ${error.message}`;
+}
 function renderErrors(errors) {
-    return errors.map((error) => `${error.instancePath || "/"} ${error.message}`).join("; ");
+    return errors.map(renderError).join("; ");
 }
 function digestJson(value) {
     return digest(canonicalize(value));

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_episodes", "media_indexer_search", "media_release_search", "media_release_grab", "media_blocklist", "media_manual_import",
+    "media_search_now", "media_blocklist_stalled", "media_episodes", "media_indexer_search", "media_release_search", "media_release_grab", "media_blocklist", "media_manual_import", "media_fill_missing",
 ]);
 /** 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/dist/senses/shared-turn.js

@@ -342,7 +342,7 @@ function getSenseSessionPath(agentName, friendId, channel, sessionKey, agentRoot
  */
 function erroredTurnReply(errorMessage) {
     return /iteration limit exhausted/u.test(errorMessage ?? "")
-        ? "I couldn't finish that one: I ran out of steps before I had an answer I could stand behind. Ask me again, or ask something narrower, and I'll take another run at it."
+        ? "I hit my step limit in the middle of that job and couldn't finish it. Tell me to continue and I'll pick up from where I stopped."
         : "I couldn't finish that one: something went wrong before I had an answer. Ask me again and I'll retry.";
 }
 async function runSenseTurn(options) {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.853",
+  "version": "0.1.0-alpha.854",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.853",
+      "version": "0.1.0-alpha.854",
       "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.853",
+  "version": "0.1.0-alpha.854",
   "engines": {
     "node": ">=22"
   },