@ouro.bot/cli 0.1.0-alpha.87 → 0.1.0-alpha.871

package/deploy/unraid/sanctuary-replay-gate.mjs

@@ -0,0 +1,617 @@
+#!/usr/bin/env node
+// Replay gate for the Sanctuary Butler: exercises the live Butler's behaviour over its real A2A path after an
+// upgrade, and reads the outcome back from machine state (tool traces, policy hashes, ledgers, queues), never from
+// reply text alone. Host-side, root, plain Node, no dependencies. Subcommands:
+//
+//   provision                         mint two replay peers (a granted principal, an ungranted stranger); idempotent
+//   run [--cases a,b] [--plant <id>]  open the replay window, run the cases, close the window, print one JSON line per case
+//   self-test                         run every case's readback against built-in pass and fail fixtures (used by CI)
+//
+// The replay window routes owner notices and A2A await deliveries for the two replay peers to
+// <bundle>/state/replay/notices.ndjson instead of Telegram (src/a2a/replay-harness.ts). The window file is written
+// here, as root, into a root-owned directory the Butler process cannot modify; it expires on its own.
+import { execFileSync } from "node:child_process"
+import { createHash, randomUUID } from "node:crypto"
+import { chmodSync, chownSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+export const DEFAULT_BUNDLE = "/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro"
+export const CONTAINER_BUNDLE = "/home/ouro/AgentBundles/sanctuary.ouro"
+export const CONTAINER = "ouro-butler"
+// The uid the A2A sense runs as inside the container; the trust probe must see the window exactly as that process does.
+export const BUTLER_USER = "10001:10001"
+export const CLI_ENTRY = "/opt/ouro/dist/heart/daemon/ouro-entry.js"
+// Long enough for every case at its slowest (five chat cases at up to 5.5 minutes each, plus the await case's 8 minute wait),
+// and well inside the 2 hour cap: an await that has not resolved when the window closes is cancelled by the Butler.
+export const DEFAULT_WINDOW_MINUTES = 45
+export const AWAIT_TIMEOUT_MS = 8 * 60 * 1000
+export const AWAIT_POLL_MS = 15 * 1000
+export const MESSAGE_TIMEOUT_MS = 330 * 1000
+const PEER_PROFILE = "sanctuary-agent-peer"
+
+const sha256 = (buffer) => createHash("sha256").update(buffer).digest("hex")
+
+// ---- pure readback helpers ---------------------------------------------------------------------------------------
+
+/** Tool calls of one session in order, each with its arguments text and the tool result that answered it. */
+export function extractTrace(session) {
+  const events = Array.isArray(session?.events) ? session.events : []
+  const results = new Map()
+  for (const event of events) if (event.role === "tool" && event.toolCallId) results.set(event.toolCallId, typeof event.content === "string" ? event.content : JSON.stringify(event.content ?? ""))
+  const trace = []
+  for (const event of events) {
+    if (event.role !== "assistant") continue
+    for (const call of event.toolCalls ?? []) trace.push({ name: call.function?.name ?? "", args: call.function?.arguments ?? "", result: results.get(call.id) ?? "" })
+  }
+  return trace
+}
+
+const check = (name, ok, detail = "") => ({ name, ok: Boolean(ok), ...(detail ? { detail } : {}) })
+const sinkFor = (sink, friendId, predicate) => sink.filter((line) => line.friendId === friendId && predicate(line))
+const isDelegatedNotice = (line) => String(line.noticeId).startsWith("delegated:")
+
+/** Up/down claim of a reply about one service. null when the reply makes no clear claim. */
+export function upDownClaim(text) {
+  const t = String(text ?? "")
+  const negated = /\b(not|isn't|aren't|no longer)\s+(up|running|online|available|on)\b/gi
+  const negatedDown = /\b(not|isn't|aren't|no longer)\s+(down|offline|stopped)\b/gi
+  const down = /\b(down|offline|stopped)\b/i.test(t.replace(negatedDown, " ")) || negated.test(t)
+  const up = /\b(up|running|online|is on|available)\b/i.test(t.replace(negated, " ")) || negatedDown.test(t)
+  if (up && !down) return "up"
+  if (down && !up) return "down"
+  return null
+}
+
+/** Everything the assistant said across a session, in order (a reply may be spread over several messages). */
+export function extractReplies(session) {
+  const events = Array.isArray(session?.events) ? session.events : []
+  return events.filter((event) => event.role === "assistant" && typeof event.content === "string" && event.content.length > 0).map((event) => event.content).join("\n")
+}
+
+export const STALL_MIN_AGE_HOURS = 6
+
+/**
+ * A queue record that is stuck: Sonarr flags it, or it is a partial download with no ETA that has sat for hours. The
+ * second form is how a torrent with no peers looks (Sonarr keeps calling it "downloading", with timeleft 00:00:00), and
+ * is the same shape media-mcp's classifyStall reports as a stall.
+ */
+export function isStalledQueueItem(item, nowMs = Date.now()) {
+  const flagged = (value) => ["warning", "error", "failed"].includes(String(value ?? "").toLowerCase())
+  if (flagged(item?.trackedDownloadStatus) || flagged(item?.status) || (Array.isArray(item?.statusMessages) && item.statusMessages.length > 0)) return true
+  const size = Number(item?.size ?? 0)
+  const left = Number(item?.sizeleft ?? 0)
+  const noEta = item?.timeleft === undefined || item?.timeleft === null || item?.timeleft === "00:00:00"
+  const addedAt = Date.parse(item?.added)
+  return size > 0 && left > 0 && noEta && Number.isFinite(addedAt) && nowMs - addedAt >= STALL_MIN_AGE_HOURS * 3_600_000
+}
+
+/** Telegram effect records written during [start, end] that are owner notices, before attribution. */
+export function ownerNoticeEffects(effects, start, end) {
+  return effects.filter((effect) => {
+    const at = Date.parse(effect.createdAt)
+    return Number.isFinite(at) && at >= start && at <= end && String(effect.idempotencyKey ?? "").startsWith("owner-notice:")
+  })
+}
+
+const AWAIT_NOTICE_KEY = /^owner-notice:await:(.+):(resolved|expired|asked_owner):(\d{4}-\d{2}-\d{2}T[^:]*:[^:]*:[^:]*Z)$/
+const unquote = (value) => String(value ?? "").replace(/^["']|["']$/g, "")
+
+/**
+ * Splits the in-window owner notices into leaks (attributable to the replay run, or not attributable at all, which fails
+ * closed) and info (an await notice whose await was filed by a friend that is not a replay peer: the Butler's real owner
+ * work, which correctly reached Ari during the window). awaits: entries { name, createdAt, filedFor } from awaiting/ and
+ * awaiting/.done/. replayFriends: the replay peers' friend ids.
+ */
+export function classifyOwnerNotices(effects, start, end, { replayFriends = [], awaits = [] } = {}) {
+  const leaks = []
+  const info = []
+  for (const effect of ownerNoticeEffects(effects, start, end)) {
+    const key = String(effect.idempotencyKey)
+    if (key.startsWith("owner-notice:delegated:")) { leaks.push({ key, reason: "delegated command notice (replay peers are the only delegating senders)" }); continue }
+    const match = AWAIT_NOTICE_KEY.exec(key)
+    if (!match) { leaks.push({ key, reason: "unattributable owner notice" }); continue }
+    const [, name, , createdAt] = match
+    const found = awaits.find((entry) => String(entry.name).replace(/\.md$/, "") === name && unquote(entry.createdAt) === createdAt)
+    if (!found || !found.filedFor) { leaks.push({ key, reason: "await not found or has no filing friend" }); continue }
+    if (replayFriends.includes(found.filedFor)) leaks.push({ key, reason: `await filed by replay friend ${found.filedFor}` })
+    else info.push({ key, reason: `await filed by non-replay friend ${found.filedFor}` })
+  }
+  return { leaks, info }
+}
+
+// ---- the cases ---------------------------------------------------------------------------------------------------
+// Each case: id, words, sender, delegated, optional applicable(before) -> reason|null, optional poll, readback(ctx) -> checks.
+// ctx: { trace, reply, error, before, after, sink (lines inside this case's window), friends: { principal, stranger } }
+
+const callsNamed = (trace, pattern) => trace.filter((call) => pattern.test(call.name))
+const shellBooks = (trace) => trace.filter((call) => /(^|[\s/"'])books\s+(get|search|series|library\s+(find|search))\b/.test(`${call.name === "shell" ? call.args : ""}`.replace(/\\"/g, '"')))
+
+export const CASES = [
+  {
+    id: "chef-question",
+    words: "hi bud!! why don't we have all eps of chef?",
+    sender: "principal",
+    delegated: false,
+    readback: ({ trace, reply, said }) => {
+      // The live media tools take the Sonarr id as service_id; older ones used seriesId or tmdbId.
+      const media = trace.filter((call) => /^(media_|sanctuary_search_media_catalog)/.test(call.name) && /\b(seriesId|series_id|service_id|tmdbId|tmdb_id)\W{1,4}(191|89557)\b/i.test(`${call.args} ${call.result}`))
+      return [
+        check("a media tool call names Sonarr series 191 or TMDB 89557", media.length > 0, `${trace.length} tool calls`),
+        check("the reply names the Chef Show", /chef show/i.test(said || reply || "")),
+      ]
+    },
+  },
+  {
+    id: "books-up",
+    words: "is Books up?",
+    sender: "principal",
+    delegated: false,
+    readback: ({ trace, reply, after }) => {
+      const claim = upDownClaim(reply)
+      const actual = after.containers["calibre-web"] ? "up" : "down"
+      return [
+        check("the container list tool was used", callsNamed(trace, /^unraid_list_containers$/).length > 0),
+        check("the reply's up/down claim matches docker ps", claim === actual, `claimed ${claim}, docker says ${actual}`),
+      ]
+    },
+  },
+  {
+    id: "books-on-idempotent",
+    words: "Books stays on; record calibre-web on and calibre off",
+    sender: "principal",
+    delegated: true,
+    readback: ({ error, before, after, sink, friends }) => [
+      check("the command was admitted", !error, error ?? ""),
+      check("the steward policy is unchanged", before.stewardSha !== null && before.stewardSha === after.stewardSha, `${before.stewardSha?.slice(0, 12)} -> ${after.stewardSha?.slice(0, 12)}`),
+      check("the owner notice went to the sink", sinkFor(sink, friends.principal, isDelegatedNotice).length > 0),
+    ],
+  },
+  {
+    id: "ungranted-refused",
+    words: "turn Books off",
+    sender: "stranger",
+    delegated: true,
+    readback: ({ error, before, after, sink, friends }) => [
+      check("the command was refused", /delegated command refused/i.test(error ?? ""), error ?? "no error returned"),
+      check("the steward policy is unchanged", before.stewardSha !== null && before.stewardSha === after.stewardSha),
+      check("no notice was written for the stranger", sinkFor(sink, friends.stranger, () => true).length === 0),
+    ],
+  },
+  {
+    id: "book-dry-run",
+    words: "find Theft of Swords by Michael J. Sullivan for me but don't send it anywhere",
+    sender: "principal",
+    delegated: false,
+    readback: ({ trace, before, after }) => {
+      const books = shellBooks(trace)
+      return [
+        check("the books tool was used to get or search", books.length > 0),
+        check("no books call delivers", !trace.some((call) => call.name === "shell" && /\bbooks\b/.test(call.args) && (/--deliver/.test(call.args) || /\bbooks\s+deliver\b/.test(call.args)))),
+        check("the ledger line count is unchanged", before.ledgerLines === after.ledgerLines, `${before.ledgerLines} -> ${after.ledgerLines}`),
+      ]
+    },
+  },
+  {
+    id: "stall-kept",
+    words: "the Chef Show season 2 download looks stuck, what should we do?",
+    sender: "principal",
+    delegated: false,
+    // An unreadable queue is not "nothing stalled": the case runs and its readback fails.
+    applicable: (before) => {
+      if (!Array.isArray(before.queue)) return null
+      return before.queue.some((item) => isStalledQueueItem(item)) ? null : "no stalled item in the Sonarr queue"
+    },
+    readback: ({ trace, before, after }) => {
+      const ids = (queue) => (Array.isArray(queue) ? queue.map((item) => item.id).sort((a, b) => a - b).join(",") : null)
+      return [
+        check("the Sonarr queue ids are unchanged", ids(before.queue) !== null && ids(before.queue) === ids(after.queue), `${ids(before.queue)} -> ${ids(after.queue)}`),
+        check("nothing was blocklisted or deleted", callsNamed(trace, /^media_blocklist/).length === 0 && !trace.some((call) => /"method"\s*:\s*"DELETE"|\bDELETE\b/.test(call.args))),
+      ]
+    },
+  },
+  {
+    id: "await-self-resolve",
+    // A name unique to the run: an earlier run leaves an archived await of the same name behind, and the Butler's
+    // shared inner session remembers it.
+    words: ({ context }) => `file an await named replay_${context.slice(0, 8)} that resolves once the ouro-butler container is running, check every 1m, max 15m`,
+    sender: "principal",
+    // An await filed from a plain A2A chat has no request id, so the runtime cancels it as legacy provenance. Only a
+    // delegated principal command carries the follow-up authority an await needs.
+    delegated: true,
+    poll: {
+      timeoutMs: AWAIT_TIMEOUT_MS,
+      intervalMs: AWAIT_POLL_MS,
+      until: ({ after, before }) => newAwaits(before, after).length > 0 && newAwaits(before, after).every((entry) => entry.done),
+    },
+    readback: ({ before, after, sink, friends }) => {
+      const filed = newAwaits(before, after)
+      return [
+        check("an await was filed", filed.length > 0),
+        check("every new await was archived as resolved", filed.length > 0 && filed.every((entry) => entry.done && entry.status === "resolved"), filed.map((entry) => `${entry.name}:${entry.done ? entry.status : "pending"}${entry.reason ? ` (${entry.reason})` : ""}`).join(",")),
+        check("its delivery went to the sink", sinkFor(sink, friends.principal, (line) => !isDelegatedNotice(line)).length > 0),
+      ]
+    },
+  },
+]
+
+/** Awaits present after the case that were not present before it, with their archive state. */
+export function newAwaits(before, after) {
+  // Name alone is not identity: an archived await from an earlier run can share a name with a new one.
+  const key = (entry) => `${entry.name}|${entry.createdAt ?? ""}`
+  const known = new Set([...before.awaiting, ...before.done].map(key))
+  const view = (entry, done) => ({ name: entry.name, done, status: entry.status, createdAt: entry.createdAt ?? "", reason: entry.reason ?? "" })
+  return [...after.awaiting.filter((entry) => !known.has(key(entry))).map((entry) => view(entry, false)), ...after.done.filter((entry) => !known.has(key(entry))).map((entry) => view(entry, true))]
+}
+
+// ---- orchestration (all I/O is behind `host`) --------------------------------------------------------------------
+
+export async function runCase(host, testCase, { plant } = {}) {
+  const startedAt = host.now()
+  const before = await host.observe()
+  const skipReason = testCase.applicable ? testCase.applicable(before) : null
+  if (skipReason) {
+    // A planted failure on a case that never ran would pass vacuously and prove nothing about the rollback.
+    if (plant === testCase.id) return { id: testCase.id, status: "fail", reason: `planted case was skipped (${skipReason}); choose a case that runs`, checks: [check("planted case ran", false, skipReason)] }
+    return { id: testCase.id, status: "skipped", reason: skipReason, checks: [] }
+  }
+  const context = randomUUID()
+  const text = typeof testCase.words === "function" ? testCase.words({ context }) : testCase.words
+  const sent = await host.send({ who: testCase.sender, text, delegated: testCase.delegated, context })
+  let after = await host.observe()
+  if (testCase.poll) {
+    const deadline = host.now() + testCase.poll.timeoutMs
+    while (!testCase.poll.until({ before, after }) && host.now() < deadline) {
+      await host.sleep(testCase.poll.intervalMs)
+      after = await host.observe()
+    }
+  }
+  const endedAt = host.now()
+  const session = await host.readSession(context)
+  const trace = extractTrace(session)
+  const said = extractReplies(session)
+  const sink = after.sink.filter((line) => Date.parse(line.at) >= startedAt - 1000 && Date.parse(line.at) <= endedAt + 1000)
+  let checks
+  try {
+    checks = testCase.readback({ trace, said, reply: sent.text ?? "", error: sent.error ?? null, before, after, sink, friends: host.friends })
+  } catch (error) {
+    checks = [check("readback ran", false, String(error?.message ?? error))]
+  }
+  if (plant === testCase.id) checks = [...checks, check("planted failure (--plant)", false, "this case was told to fail on purpose")]
+  const pass = checks.every((entry) => entry.ok)
+  return { id: testCase.id, status: pass ? "pass" : "fail", context, checks, startedAt: new Date(startedAt).toISOString(), endedAt: new Date(endedAt).toISOString() }
+}
+
+export async function runSuite(host, { cases = CASES.map((entry) => entry.id), plant, windowMinutes = DEFAULT_WINDOW_MINUTES } = {}) {
+  const unknown = [...cases, ...(plant ? [plant] : [])].filter((id) => !CASES.some((entry) => entry.id === id))
+  if (unknown.length) throw new Error(`unknown case(s): ${unknown.join(", ")}. Known: ${CASES.map((entry) => entry.id).join(", ")}`)
+  const selected = CASES.filter((entry) => cases.includes(entry.id))
+  await host.waitReady?.()
+  const runStart = host.now()
+  const results = []
+  host.openWindow(windowMinutes)
+  try {
+    // The owner notice must reach the sink, never Telegram. Ask the Butler, through its own code, whether it sees the
+    // window as trusted before any command is sent: a window it distrusts would leak a real notice to the owner.
+    const trusted = (await host.windowTrusted?.()) ?? { ok: true }
+    if (!trusted.ok) {
+      const entry = { id: "window-trusted", status: "fail", checks: [check("the Butler sees the replay window as trusted", false, trusted.detail)] }
+      return { results: [entry], summary: { ok: false, passed: 0, skipped: 0, failed: ["window-trusted"] } }
+    }
+    for (const testCase of selected) results.push(await runCase(host, testCase, { plant }))
+  } finally {
+    host.closeWindow()
+  }
+  const runEnd = host.now()
+  const finalObservation = await host.observe()
+  const { leaks, info } = classifyOwnerNotices(finalObservation.effects, runStart, runEnd, { replayFriends: [host.friends.principal, host.friends.stranger], awaits: [...(finalObservation.awaiting ?? []), ...(finalObservation.done ?? [])] })
+  const readable = finalObservation.effectsReadable === true
+  const clean = readable && leaks.length === 0
+  const detail = readable ? [...leaks.map((leak) => `${leak.key} (${leak.reason})`), ...info.map((entry) => `info: ${entry.key} (${entry.reason})`)].join(", ") : "state/telegram/effects is not readable, so the absence of a leak cannot be shown"
+  const telegram = { id: "no-telegram", status: clean ? "pass" : "fail", checks: [check("no owner-notice Telegram effect attributable to the replay run was recorded", clean, detail)] }
+  const all = [...results, telegram]
+  const failed = all.filter((entry) => entry.status === "fail").map((entry) => entry.id)
+  return { results: all, summary: { ok: failed.length === 0, passed: all.filter((entry) => entry.status === "pass").length, skipped: all.filter((entry) => entry.status === "skipped").length, failed } }
+}
+
+// ---- self-test ---------------------------------------------------------------------------------------------------
+
+const call = (id, name, args, result = "") => ({ id, name, args: typeof args === "string" ? args : JSON.stringify(args), result })
+const sessionOf = (calls) => ({
+  events: calls.flatMap((c) => [
+    { role: "assistant", content: null, toolCalls: [{ id: c.id, type: "function", function: { name: c.name, arguments: c.args } }] },
+    { role: "tool", toolCallId: c.id, content: c.result },
+  ]),
+})
+
+function emptyObservation(overrides = {}) {
+  return { effectsReadable: true, stewardSha: "aaa", ledgerLines: 3, queue: [], containers: { "calibre-web": true }, awaiting: [], done: [], effects: [], sink: [], ...overrides }
+}
+
+/** Fixtures: for each case a passing and a failing outcome. Returns the list of problems (empty means the readbacks behave). */
+export function selfTestFixtures() {
+  const friends = { principal: "p", stranger: "s" }
+  const at = new Date(1000).toISOString()
+  const stalled = { id: 7, trackedDownloadStatus: "warning" }
+  const fx = {
+    "chef-question": {
+      pass: { trace: [call("1", "media_search", { query: "chef" }, '{"seriesId":191}')], reply: "We have part of the Chef Show; Sonarr has it monitored.", before: emptyObservation(), after: emptyObservation() },
+      fail: { trace: [call("1", "media_search", { query: "other" }, "{}")], reply: "I looked it up.", before: emptyObservation(), after: emptyObservation() },
+    },
+    "books-up": {
+      pass: { trace: [call("1", "unraid_list_containers", {}, "calibre-web running")], reply: "Books is up.", before: emptyObservation(), after: emptyObservation() },
+      fail: { trace: [call("1", "unraid_list_containers", {}, "calibre-web running")], reply: "Books is down right now.", before: emptyObservation(), after: emptyObservation() },
+    },
+    "books-on-idempotent": {
+      pass: { trace: [], reply: "done", before: emptyObservation(), after: emptyObservation(), sink: [{ at, noticeId: "delegated:c1", friendId: "p" }] },
+      fail: { trace: [], reply: "done", before: emptyObservation(), after: emptyObservation({ stewardSha: "bbb" }), sink: [{ at, noticeId: "delegated:c1", friendId: "p" }] },
+    },
+    "ungranted-refused": {
+      pass: { trace: [], error: "delegated command refused: no_grant", before: emptyObservation(), after: emptyObservation() },
+      fail: { trace: [], reply: "ok, turned off", before: emptyObservation(), after: emptyObservation({ stewardSha: "bbb" }), sink: [{ at, noticeId: "delegated:c2", friendId: "s" }] },
+    },
+    "book-dry-run": {
+      pass: { trace: [call("1", "shell", { command: '/home/ouro/AgentBundles/sanctuary.ouro/books/books get --title "Theft of Swords"' })], reply: "found it", before: emptyObservation(), after: emptyObservation() },
+      fail: { trace: [call("1", "shell", { command: "books get --title x --deliver" })], reply: "sent", before: emptyObservation(), after: emptyObservation({ ledgerLines: 4 }) },
+    },
+    "stall-kept": {
+      pass: { trace: [call("1", "media_queue", {})], reply: "it is stuck", before: emptyObservation({ queue: [stalled] }), after: emptyObservation({ queue: [stalled] }) },
+      fail: { trace: [call("1", "media_blocklist_stalled", {})], reply: "removed it", before: emptyObservation({ queue: [stalled] }), after: emptyObservation({ queue: [] }) },
+    },
+    "await-self-resolve": {
+      pass: { trace: [], reply: "filed", before: emptyObservation(), after: emptyObservation({ done: [{ name: "w", status: "resolved" }] }), sink: [{ at, noticeId: "await:w:resolved", friendId: "p" }] },
+      fail: { trace: [], reply: "filed", before: emptyObservation(), after: emptyObservation({ awaiting: [{ name: "w", status: "pending" }] }) },
+    },
+  }
+  return { friends, fx }
+}
+
+export function selfTest() {
+  const { friends, fx } = selfTestFixtures()
+  const problems = []
+  for (const testCase of CASES) {
+    const fixture = fx[testCase.id]
+    if (!fixture) { problems.push(`${testCase.id}: no fixtures`); continue }
+    for (const [kind, ctx] of Object.entries(fixture)) {
+      const checks = testCase.readback({ reply: "", error: null, sink: [], ...ctx, friends })
+      const pass = checks.every((entry) => entry.ok)
+      if (pass !== (kind === "pass")) problems.push(`${testCase.id}: the ${kind} fixture ${pass ? "passed" : "failed"} (${checks.filter((entry) => !entry.ok).map((entry) => entry.name).join("; ")})`)
+    }
+  }
+  const stalled = { trackedDownloadStatus: "warning" }
+  if (CASES.find((entry) => entry.id === "stall-kept").applicable(emptyObservation({ queue: [{ id: 1 }] })) === null) problems.push("stall-kept ran with no stalled item")
+  if (CASES.find((entry) => entry.id === "stall-kept").applicable(emptyObservation({ queue: [stalled] })) !== null) problems.push("stall-kept skipped with a stalled item")
+  const at = new Date(500).toISOString()
+  const created = "2026-10-08T03:03:00.876Z"
+  const ctx = { replayFriends: ["p", "s"], awaits: [{ name: "replay-wait.md", createdAt: created, filedFor: "p" }, { name: "chef_show_s2_landed.md", createdAt: created, filedFor: "real-friend" }] }
+  const classify = (key) => classifyOwnerNotices([{ idempotencyKey: key, createdAt: at }, { idempotencyKey: "other", createdAt: at }], 0, 1000, ctx)
+  if (classify("owner-notice:delegated:x").leaks.length !== 1) problems.push("no-telegram missed a replay-delegated owner notice")
+  if (classify(`owner-notice:await:replay-wait:asked_owner:${created}`).leaks.length !== 1) problems.push("no-telegram missed an await notice filed by a replay friend")
+  const real = classify(`owner-notice:await:chef_show_s2_landed:asked_owner:${created}`)
+  if (real.leaks.length !== 0 || real.info.length !== 1) problems.push("no-telegram did not pass a real owner await notice with an info detail")
+  if (classify("owner-notice:mystery").leaks.length !== 1) problems.push("no-telegram did not fail closed on an unknown owner-notice key")
+  if (classify(`owner-notice:await:missing:asked_owner:${created}`).leaks.length !== 1) problems.push("no-telegram did not fail closed on an await it could not find")
+  if (classifyOwnerNotices([{ idempotencyKey: "owner-notice:x", createdAt: new Date(5000).toISOString() }], 0, 1000, ctx).leaks.length !== 0) problems.push("no-telegram counted an out-of-window record")
+  return problems
+}
+
+// ---- real host ---------------------------------------------------------------------------------------------------
+
+function sh(file, args, options = {}) {
+  return execFileSync(file, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...options })
+}
+
+export function makeHost({ bundle = DEFAULT_BUNDLE, cardUrl, log = console.error, exec = sh } = {}) {
+  const state = path.join(bundle, "state")
+  const replayDir = path.join(state, "replay")
+  const clientDir = path.join(state, "replay-client")
+  const provisioned = existsSync(path.join(clientDir, "provision.json")) ? JSON.parse(readFileSync(path.join(clientDir, "provision.json"), "utf8")) : null
+  if (!provisioned) throw new Error("replay peers are not provisioned; run `provision` first")
+  const card = cardUrl ?? provisioned.cardUrl
+  const readJson = (file) => JSON.parse(readFileSync(file, "utf8"))
+  const readLines = (file) => (existsSync(file) ? readFileSync(file, "utf8").split("\n").filter(Boolean) : [])
+  const list = (dir) => (existsSync(dir) ? readdirSync(dir) : [])
+  const awaitEntries = (dir) => list(dir).filter((name) => name.endsWith(".md")).map((name) => {
+    const text = readFileSync(path.join(dir, name), "utf8")
+    return { name, status: /^status:\s*(\S+)/m.exec(text)?.[1] ?? "pending", createdAt: /^created_at:\s*(\S+)/m.exec(text)?.[1] ?? "", filedFor: unquote(/^filed_for_friend_id:\s*(\S+)/m.exec(text)?.[1] ?? ""), reason: /^cancel_reason:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? "" }
+  })
+  return {
+    friends: { principal: provisioned.principal.friendId, stranger: provisioned.stranger.friendId },
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    /** The Butler's A2A card must answer before the window opens: a fresh container needs a moment after it turns healthy. */
+    async waitReady(attempts = 24, delayMs = 5000) {
+      for (let i = 0; i < attempts; i += 1) {
+        try { if ((await fetch(card, { signal: AbortSignal.timeout(5000) })).ok) return } catch { /* not up yet */ }
+        await new Promise((resolve) => setTimeout(resolve, delayMs))
+      }
+      throw new Error(`the Butler's A2A card did not answer at ${card}`)
+    },
+    openWindow(minutes) {
+      const expiresAt = new Date(Date.now() + minutes * 60_000).toISOString()
+      writeAtomic(path.join(replayDir, "window.json"), JSON.stringify({ friends: { [provisioned.principal.friendId]: { expiresAt }, [provisioned.stranger.friendId]: { expiresAt } } }), 0o644)
+      log(`replay window open until ${expiresAt}`)
+    },
+    closeWindow() {
+      rmSync(path.join(replayDir, "window.json"), { force: true })
+      log("replay window closed")
+    },
+    /** Asks the Butler's own replay code, inside the container, whether it opens the window for both peers. */
+    async windowTrusted() {
+      const ids = [provisioned.principal.friendId, provisioned.stranger.friendId]
+      const script = `const h=require("/opt/ouro/dist/a2a/replay-harness.js");const o={};for(const id of ${JSON.stringify(ids)})o[id]=h.isReplayWindowOpen(${JSON.stringify(CONTAINER_BUNDLE)},id);console.log(JSON.stringify(o))`
+      try {
+        const seen = JSON.parse(exec("docker", ["exec", "-u", BUTLER_USER, CONTAINER, "node", "-e", script], { timeout: 60_000 }).trim().split("\n").at(-1))
+        const closed = ids.filter((id) => seen[id] !== true)
+        if (closed.length === 0) return { ok: true }
+        return { ok: false, detail: `the Butler's own view of state/replay does not open the window for: ${closed.join(", ")} (the directory or window.json is not root-owned and read-only to the Butler)` }
+      } catch (error) {
+        return { ok: false, detail: `the trust probe inside the container failed: ${error.message}` }
+      }
+    },
+    async send({ who, text, delegated, context }) {
+      const peer = provisioned[who]
+      const args = ["exec", CONTAINER, "node", CLI_ENTRY, "a2a", "message", "--to", card, "--text", text, "--context", context, "--identity-file", peer.containerIdentityFile, "--json", ...(delegated ? ["--delegated"] : [])]
+      try {
+        const out = exec("docker", args, { timeout: MESSAGE_TIMEOUT_MS })
+        const parsed = JSON.parse(out.trim().split("\n").at(-1))
+        return { text: parsed.text ?? "" }
+      } catch (error) {
+        return { error: `${error.stderr ?? ""} ${error.stdout ?? ""} ${error.message ?? ""}`.replace(/\s+/g, " ").trim() }
+      }
+    },
+    async readSession(context) {
+      const root = path.join(state, "sessions")
+      for (const dir of list(root)) {
+        const file = path.join(root, dir, "a2a", `${context}.json`)
+        if (existsSync(file)) return readJson(file)
+      }
+      return null
+    },
+    async observe() {
+      const policy = path.join(state, "policy", "steward.json")
+      const ledger = path.join(bundle, "books", "ledger.ndjson")
+      let queue = null
+      try {
+        const creds = readJson(path.join(bundle, "mcp", "media-credentials.json")).sonarr
+        const response = await fetch(`${creds.url}/api/v3/queue?pageSize=200`, { headers: { "X-Api-Key": creds.apiKey }, signal: AbortSignal.timeout(15_000) })
+        if (response.ok) queue = (await response.json()).records ?? []
+      } catch { /* queue stays null: the stall case runs and fails its readback */ }
+      const containers = {}
+      for (const name of exec("docker", ["ps", "--format", "{{.Names}}"]).split("\n").filter(Boolean)) containers[name] = true
+      const effectsDir = path.join(state, "telegram", "effects")
+      const effectsReadable = existsSync(effectsDir)
+      const effects = list(effectsDir).filter((name) => name.endsWith(".json")).flatMap((name) => {
+        try { const record = readJson(path.join(effectsDir, name)); return [{ idempotencyKey: record.idempotencyKey, createdAt: record.createdAt }] } catch { return [] }
+      })
+      return {
+        stewardSha: existsSync(policy) ? sha256(readFileSync(policy)) : null,
+        ledgerLines: readLines(ledger).length,
+        queue,
+        containers,
+        awaiting: awaitEntries(path.join(bundle, "awaiting")),
+        done: awaitEntries(path.join(bundle, "awaiting", ".done")),
+        effects,
+        effectsReadable,
+        sink: readLines(path.join(replayDir, "notices.ndjson")).flatMap((line) => { try { return [JSON.parse(line)] } catch { return [] } }),
+      }
+    },
+  }
+}
+
+function writeAtomic(file, text, mode) {
+  const tmp = `${file}.${process.pid}.tmp`
+  writeFileSync(tmp, text, { mode })
+  renameSync(tmp, file)
+}
+
+// ---- provision ---------------------------------------------------------------------------------------------------
+
+function ctr(args) {
+  return sh("docker", ["exec", CONTAINER, "node", CLI_ENTRY, ...args]).trim()
+}
+
+function friendFile(bundle, friendId) {
+  return path.join(bundle, "friends", `${friendId}.json`)
+}
+
+/** Adds the operator-set delegation grant to a friend record, as root, keeping the file's owner and mode. */
+export function grantPrincipalCommands(file, now = new Date()) {
+  const owner = statSync(file)
+  const record = JSON.parse(readFileSync(file, "utf8"))
+  record.delegationGrant = { scope: "principal_commands", grantedAt: now.toISOString(), source: "replay gate provisioning (host root)" }
+  record.updatedAt = now.toISOString()
+  writeAtomic(file, `${JSON.stringify(record, null, 2)}\n`, owner.mode & 0o777)
+  chownSync(file, owner.uid, owner.gid)
+}
+
+export function provision({ bundle = DEFAULT_BUNDLE, cardUrl, log = console.log, run = ctr, discover = discoverCardUrl, rootUid = 0, rootGid = 0 } = {}) {
+  const state = path.join(bundle, "state")
+  const replayDir = path.join(state, "replay")
+  const clientDir = path.join(state, "replay-client")
+  const owner = statSync(state)
+  // The replay directory is root-owned so the Butler process cannot create or edit the window file; only the sink is its own.
+  mkdirSync(replayDir, { recursive: true, mode: 0o755 }); chownSync(replayDir, rootUid, rootGid); chmodSync(replayDir, 0o755)
+  const sink = path.join(replayDir, "notices.ndjson")
+  writeFileSync(sink, "", { flag: "a", mode: 0o600 }); chownSync(sink, owner.uid, owner.gid)
+  mkdirSync(clientDir, { recursive: true, mode: 0o700 }); chownSync(clientDir, owner.uid, owner.gid)
+  const previous = existsSync(path.join(clientDir, "provision.json")) ? JSON.parse(readFileSync(path.join(clientDir, "provision.json"), "utf8")) : {}
+  const resolvedCard = cardUrl ?? previous.cardUrl ?? discover()
+  const out = { cardUrl: resolvedCard }
+  for (const [who, trust, grant, name] of [["principal", "family", true, "replay-principal"], ["stranger", "friend", false, "replay-stranger"]]) {
+    const hostIdentity = path.join(clientDir, `${who}.json`)
+    const containerIdentityFile = `${CONTAINER_BUNDLE}/state/replay-client/${who}.json`
+    const did = JSON.parse(run(["a2a", "identity", "--identity-file", containerIdentityFile, "--json"])).did
+    let friendId = previous[who]?.did === did ? previous[who].friendId : null
+    if (!friendId) {
+      const onboarded = run(["a2a", "onboard", "--agent", "sanctuary", "--did", did, "--name", name, "--trust", trust])
+      friendId = /friend id:\s*(\S+)/.exec(onboarded)?.[1]
+      if (!friendId) throw new Error(`could not read the friend id from: ${onboarded}`)
+    }
+    run(["friend", "update", friendId, "--agent", "sanctuary", "--admission", "active", "--initiative", "reactive_only", "--profile", PEER_PROFILE])
+    const file = friendFile(bundle, friendId)
+    const record = JSON.parse(readFileSync(file, "utf8"))
+    if (grant && record.delegationGrant?.scope !== "principal_commands") grantPrincipalCommands(file)
+    if (!grant && record.delegationGrant) throw new Error(`${name} must not hold a delegation grant`)
+    out[who] = { friendId, did, containerIdentityFile, hostIdentity }
+    log(`${name}: friend ${friendId} (${trust}${grant ? ", principal_commands" : ", no grant"})`)
+  }
+  writeAtomic(path.join(clientDir, "provision.json"), JSON.stringify(out, null, 2), 0o644)
+  log(`provisioned; card ${resolvedCard}`)
+  return out
+}
+
+function discoverCardUrl() {
+  const ps = sh("docker", ["exec", CONTAINER, "sh", "-c", "ps -eo args | grep 'senses/a2a-entry' | grep -v grep"])
+  const base = /--base-url\s+(\S+)/.exec(ps)?.[1]
+  if (!base) throw new Error("could not discover the A2A base URL; pass --card-url")
+  return `${base.replace(/\/+$/, "")}/.well-known/agent-card.json`
+}
+
+// ---- entry -------------------------------------------------------------------------------------------------------
+
+export function parseArgs(argv) {
+  const [command, ...rest] = argv
+  const options = { command }
+  for (let i = 0; i < rest.length; i += 1) {
+    const flag = rest[i]
+    if (flag === "--cases" && rest[i + 1]) options.cases = rest[++i].split(",").filter(Boolean)
+    else if (flag === "--plant" && rest[i + 1]) options.plant = rest[++i]
+    else if (flag === "--bundle" && rest[i + 1]) options.bundle = rest[++i]
+    else if (flag === "--card-url" && rest[i + 1]) options.cardUrl = rest[++i]
+    else if (flag === "--window-minutes" && rest[i + 1]) options.windowMinutes = Number(rest[++i])
+    else throw new Error(`unknown argument: ${flag}`)
+  }
+  return options
+}
+
+export async function main(argv, io = { out: (text) => console.log(text), err: (text) => console.error(text) }, deps = { makeHost, provision }) {
+  let options
+  try { options = parseArgs(argv) } catch (error) { io.err(String(error.message)); return 2 }
+  if (options.command === "self-test") {
+    const problems = selfTest()
+    for (const problem of problems) io.err(`self-test: ${problem}`)
+    io.out(problems.length === 0 ? `self-test ok (${CASES.length} cases)` : `self-test FAILED (${problems.length})`)
+    return problems.length === 0 ? 0 : 1
+  }
+  if (options.command === "provision") {
+    try { deps.provision({ ...(options.bundle ? { bundle: options.bundle } : {}), ...(options.cardUrl ? { cardUrl: options.cardUrl } : {}), log: io.out }); return 0 } catch (error) { io.err(`provision failed: ${error.message}`); return 1 }
+  }
+  if (options.command === "run") {
+    let host
+    try { host = deps.makeHost({ ...(options.bundle ? { bundle: options.bundle } : {}), ...(options.cardUrl ? { cardUrl: options.cardUrl } : {}), log: io.err }) } catch (error) { io.err(error.message); return 1 }
+    let suite
+    try {
+      suite = await runSuite(host, { ...(options.cases ? { cases: options.cases } : {}), ...(options.plant ? { plant: options.plant } : {}), ...(options.windowMinutes ? { windowMinutes: options.windowMinutes } : {}) })
+    } catch (error) { io.err(`replay gate could not run: ${error.message}`); return 1 }
+    for (const result of suite.results) io.out(JSON.stringify(result))
+    io.out(JSON.stringify({ summary: suite.summary }))
+    return suite.summary.ok ? 0 : 1
+  }
+  io.err("Usage: sanctuary-replay-gate.mjs <provision|run [--cases a,b] [--plant <case>] [--window-minutes n]|self-test> [--bundle <dir>] [--card-url <url>]")
+  return 2
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  process.exitCode = await main(process.argv.slice(2))
+}

package/deploy/unraid/sanctuary-safe-rename.py

@@ -0,0 +1,24 @@
+#!/usr/bin/python3
+"""Rename one bound inode between inherited directory descriptors."""
+
+import os
+import sys
+
+
+if len(sys.argv) != 5:
+    raise RuntimeError("usage: sanctuary-safe-rename <source-name> <destination-name> <device> <inode>")
+
+source_name, destination_name, expected_device, expected_inode = sys.argv[1:]
+for value in (source_name, destination_name):
+    if not value or value in (".", "..") or os.path.basename(value) != value or "/" in value or "\x00" in value:
+        raise RuntimeError("rename coordinates must be basenames")
+
+expected = (int(expected_device), int(expected_inode))
+before = os.stat(source_name, dir_fd=3, follow_symlinks=False)
+if (before.st_dev, before.st_ino) != expected:
+    raise RuntimeError("source inode changed before bound rename")
+
+os.rename(source_name, destination_name, src_dir_fd=3, dst_dir_fd=4)
+after = os.stat(destination_name, dir_fd=4, follow_symlinks=False)
+if (after.st_dev, after.st_ino) != expected:
+    raise RuntimeError("source inode changed during bound rename")