@ouro.bot/cli 0.1.0-alpha.864 → 0.1.0-alpha.866

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

@@ -0,0 +1,533 @@
+#!/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"
+export const CLI_ENTRY = "/opt/ouro/dist/heart/daemon/ouro-entry.js"
+export const DEFAULT_WINDOW_MINUTES = 30
+export const AWAIT_TIMEOUT_MS = 6 * 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
+}
+
+/** A queue record that Sonarr itself flags as stuck or failing. */
+export function isStalledQueueItem(item) {
+  const flagged = (value) => ["warning", "error", "failed"].includes(String(value ?? "").toLowerCase())
+  return flagged(item?.trackedDownloadStatus) || flagged(item?.status) || (Array.isArray(item?.statusMessages) && item.statusMessages.length > 0)
+}
+
+/** Telegram effect records written during [start, end] that would have reached Ari's chat from a replay. */
+export function telegramLeaks(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:")
+  })
+}
+
+// ---- 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)\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 }) => {
+      const media = trace.filter((call) => /^(media_|sanctuary_search_media_catalog)/.test(call.name) && /\b(seriesId|tmdbId)\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(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))),
+        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(isStalledQueueItem) ? 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",
+    words: "file an await that resolves once the ouro-butler container is running, check every 1m, max 15m",
+    sender: "principal",
+    delegated: false,
+    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"}`).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) {
+  const known = new Set([...before.awaiting.map((entry) => entry.name), ...before.done.map((entry) => entry.name)])
+  const pending = after.awaiting.filter((entry) => !known.has(entry.name)).map((entry) => ({ name: entry.name, done: false, status: entry.status }))
+  const archived = after.done.filter((entry) => !known.has(entry.name)).map((entry) => ({ name: entry.name, done: true, status: entry.status }))
+  return [...pending, ...archived]
+}
+
+// ---- 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 sent = await host.send({ who: testCase.sender, text: testCase.words, 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 sink = after.sink.filter((line) => Date.parse(line.at) >= startedAt - 1000 && Date.parse(line.at) <= endedAt + 1000)
+  let checks
+  try {
+    checks = testCase.readback({ trace, 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 {
+    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 = telegramLeaks(finalObservation.effects, runStart, runEnd)
+  const readable = finalObservation.effectsReadable === true
+  const clean = readable && leaks.length === 0
+  const telegram = { id: "no-telegram", status: clean ? "pass" : "fail", checks: [check("no owner-notice Telegram effect was recorded during the run", clean, readable ? leaks.map((leak) => leak.idempotencyKey).join(",") : "state/telegram/effects is not readable, so the absence of a leak cannot be shown")] }
+  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 leaked = telegramLeaks([{ idempotencyKey: "owner-notice:delegated:x", createdAt: new Date(500).toISOString() }, { idempotencyKey: "other", createdAt: new Date(500).toISOString() }], 0, 1000)
+  if (leaked.length !== 1) problems.push("the telegram leak check missed an in-window owner notice")
+  if (telegramLeaks([{ idempotencyKey: "owner-notice:x", createdAt: new Date(5000).toISOString() }], 0, 1000).length !== 0) problems.push("the telegram leak check 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" }
+  })
+  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")
+    },
+    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.ouro/bundle-meta.json

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

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.864</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.866</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/a2a/delegated-command.js

@@ -41,6 +41,7 @@ const crypto_1 = require("crypto");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const runtime_1 = require("../nerves/runtime");
+const replay_harness_1 = require("./replay-harness");
 const relationship_authorization_1 = require("../repertoire/relationship-authorization");
 const NOTICE_EXCERPT_CHARS = 200;
 /** The relationship profile that names the principal a delegated peer acts for. */
@@ -51,7 +52,7 @@ exports.A2A_PRINCIPAL_PROFILE_ID = "sanctuary-owner";
  * command id. A request id with no such record never came through a signed, owner-notified delegated command.
  * A missing record is `false`; an unreadable or malformed one throws, so the caller retries instead of deciding.
  */
-function delegatedCommandWasNoticed(agentRoot, commandId, principalFriendId) {
+function delegatedCommandWasNoticed(agentRoot, commandId, principalFriendId, delegateFriendId) {
     const idempotencyKey = `owner-notice:delegated:${commandId}`;
     const file = path.join(agentRoot, "state", "telegram", "effects", `${(0, crypto_1.createHash)("sha256").update(idempotencyKey).digest("hex")}.json`);
     let raw;
@@ -60,7 +61,7 @@ function delegatedCommandWasNoticed(agentRoot, commandId, principalFriendId) {
     }
     catch (error) {
         if (error.code === "ENOENT")
-            return false;
+            return delegateFriendId !== undefined && (0, replay_harness_1.isReplayWindowOpen)(agentRoot, delegateFriendId) && (0, replay_harness_1.replayNoticeRecorded)(agentRoot, `delegated:${commandId}`, delegateFriendId);
         throw error;
     }
     const artifact = JSON.parse(raw);
@@ -107,7 +108,12 @@ async function admitDelegatedCommand(input) {
         return refuse("principal_unresolved");
     const noticeId = `delegated:${input.commandId}`;
     try {
-        await input.options.notifyPrincipal({ noticeId, text: delegatedCommandNotice({ delegateName: input.friend.name, text: input.text }) });
+        const text = delegatedCommandNotice({ delegateName: input.friend.name, text: input.text });
+        const agentRoot = input.options.agentRoot;
+        if (agentRoot && (0, replay_harness_1.isReplayWindowOpen)(agentRoot, input.friend.id))
+            (0, replay_harness_1.appendReplayNotice)(agentRoot, { noticeId, text, friendId: input.friend.id });
+        else
+            await input.options.notifyPrincipal({ noticeId, text });
     }
     catch {
         return refuse("notice_failed");