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

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.865",
+      "changes": [
+        "Added an operator-set replay window: while the host's replay gate holds it open for a replay peer, that peer's delegated-command owner notices and A2A await deliveries go to a local sink instead of the owner's Telegram chat, with every authorization check unchanged, a failed sink write refusing the command, and a nerves event for each notice sunk. The window counts only when its directory is root-owned and not group- or other-writable and the window file, opened once with O_NOFOLLOW and checked by descriptor, is a root-owned regular file nobody else can write, and a sink record satisfies an await's noticed check only for the same friend inside such a window.",
+        "Added the host-side replay gate (sanctuary-replay-gate.mjs) that provisions two replay peers and replays seven real requests over A2A, reading each outcome back from tool traces, the steward policy hash, the books ledger, the Sonarr queue, await archives and Telegram effect records; unreadable evidence now fails a case instead of skipping or passing it.",
+        "Made Sanctuary upgrades hold the new version uncommitted until the replay gate passes: a pass commits, pins the template and prunes images, a failed gate rolls back to the predecessor and exits 1, and the commit is refused unless the held upgrade is still the live one. Added --no-gate, --plant and verify --gate, plus a --hold-commit option on the root lifecycle because a completed upgrade cannot be rolled back."
+      ]
+    },
     {
       "version": "0.1.0-alpha.864",
       "changes": [

package/deploy/unraid/sanctuary-butler-upgrade.mjs

@@ -29,11 +29,21 @@
 // refuses without a rotated incoming-token. Run `upgrade` detached so an SSH drop
 // cannot interrupt it:  setsid nohup node <this> upgrade <version> > /var/log/ouro-upgrade.log 2>&1 &
 //
-// Usage: sanctuary-butler-upgrade.mjs <preflight|prepare|install|verify|upgrade> <version> [--rehearse <step>]
+// An `upgrade` ends with the replay gate (sanctuary-replay-gate.mjs): the new Butler is held UNCOMMITTED (the lifecycle
+// keeps its journal and the predecessor's records, because a committed upgrade cannot be rolled back), the gate replays
+// real requests over A2A and reads the outcome back from machine state, and only a pass commits, pins the template and
+// prunes images. A failed gate runs `upgrade-rollback`, confirms the predecessor is healthy, and exits 1.
+//   --no-gate         skip the gate and commit straight away (emergencies; logged loudly)
+//   --plant <case>    make that gate case fail on purpose, proving the rollback end to end
+//   verify --gate     run the gate against the live version without upgrading
+//
+// Usage: sanctuary-butler-upgrade.mjs <preflight|prepare|install|verify|upgrade> <version> [--rehearse <step>] [--no-gate] [--plant <case>]
+//        sanctuary-butler-upgrade.mjs verify [--gate]
 
-import { execFileSync } from "node:child_process"
+import { execFileSync, spawnSync } from "node:child_process"
 import { createHash } from "node:crypto"
-import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync, statSync, chmodSync } from "node:fs"
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync, statSync, chmodSync, realpathSync } from "node:fs"
+import { fileURLToPath } from "node:url"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 
@@ -61,6 +71,10 @@ const UPGRADE_JOURNAL = `${ROOT}/upgrade.json`
 const MAINTENANCE = "/run/ouro-authority-maintenance"
 // The stop hook's flag: every keeper watchdog version stands down while it exists.
 const SHUTDOWN_FLAG = "/run/ouro-authority-shutdown"
+const GATE_SCRIPT = `${ROOT}/package/deploy/unraid/sanctuary-replay-gate.mjs`
+const GATE_PROVISION = `${BUNDLE}/state/replay-client/provision.json`
+// The whole gate (every case, including the six-minute await wait) must finish well inside this; a hung gate is a failed gate.
+export const GATE_TIMEOUT_MS = 45 * 60 * 1000
 const UPGRADE_STEPS = ["stop", "switch", "resident", "migrate", "start"]
 
 const sh = (file, args, opts = {}) => execFileSync(file, args, { encoding: "utf8", maxBuffer: 64 << 20, ...opts })
@@ -845,9 +859,62 @@ function lifecycleFailure(e) {
   return `${detail || e.message}${last ? `\n   last root failure: ${last}` : ""}`
 }
 
-function upgrade(version, rehearse) {
+/**
+ * The end of a gated upgrade, with every side effect injected so the decision is testable: a pass commits the held
+ * upgrade, pins the template and prunes; a fail rolls back to the predecessor and confirms it is healthy. Nothing is
+ * committed, pinned or pruned unless the gate passed.
+ */
+export function completeGatedUpgrade({ runGate, commit, rollback, confirmRollback, pin, prune, log = console.log }) {
+  const gate = runGate()
+  if (gate.ok) {
+    commit()
+    pin()
+    prune()
+    log("GATE PASS")
+    return { passed: true }
+  }
+  log(`gate failed: ${gate.detail ?? "see the case lines above"}`)
+  rollback()
+  const restored = confirmRollback()
+  log(`GATE FAIL — ROLLED BACK to ${restored}`)
+  return { passed: false, rolledBackTo: restored }
+}
+
+export function runReplayGate(plant, { spawn = spawnSync, exists = existsSync } = {}) {
+  if (!exists(GATE_SCRIPT)) return { ok: false, detail: `the replay gate is missing from the live package (${GATE_SCRIPT})` }
+  const result = spawn("/usr/local/bin/node", [GATE_SCRIPT, "run", ...(plant ? ["--plant", plant] : [])], { stdio: "inherit", timeout: GATE_TIMEOUT_MS, killSignal: "SIGKILL" })
+  return result.status === 0 ? { ok: true } : { ok: false, detail: `the replay gate exited ${result.status ?? result.signal}` }
+}
+
+/**
+ * The commit step runs the lifecycle's `upgrade` again, which would START A FRESH UNGATED UPGRADE if the keeper had
+ * rolled the held one back mid-gate. So commit only while the journal still exists and the new image is still live.
+ */
+export function heldUpgradeProblem({ journalExists, liveImage, expectedImage }) {
+  if (!journalExists) return "the held upgrade's journal is gone (the keeper or a boot rolled it back mid-gate)"
+  if (liveImage !== expectedImage) return `the live Butler is ${liveImage}, not the held ${expectedImage}`
+  return null
+}
+
+function butlerState() {
+  try { return docker(["inspect", CONTAINER, "--format", "{{.Config.Image}} {{.State.Status}}/{{.State.Health.Status}}"], { stdio: ["ignore", "pipe", "ignore"] }).trim() } catch { return "? ?/?" }
+}
+
+function waitForButler(imageRef, seconds) {
+  for (let waited = 0; waited <= seconds; waited += 10) {
+    const [liveImage, state] = butlerState().split(" ")
+    if (liveImage === imageRef && state === "running/healthy") return true
+    sh("/bin/sleep", ["10"])
+  }
+  return false
+}
+
+function upgrade(version, rehearse, { noGate = false, plant } = {}) {
   say(`in-place upgrade to ${version}${rehearse ? ` — REHEARSAL: stop after "${rehearse}", then roll back` : ""}`)
   if (rehearse && !UPGRADE_STEPS.includes(rehearse)) fail(`--rehearse takes one of: ${UPGRADE_STEPS.join(", ")}`)
+  const gated = !rehearse && !noGate
+  if (noGate && !rehearse) console.log("\n!! --no-gate: this upgrade will NOT be replay-gated or auto-rolled-back on a behavioural regression")
+  if (gated && !existsSync(GATE_PROVISION)) fail(`replay peers are not provisioned (${GATE_PROVISION}); run \`sanctuary-replay-gate.mjs provision\` first, or pass --no-gate`)
   if (!existsSync(`${ROOT}/active.json`) || !existsSync(`${ROOT}/activation.json`)) fail("no installed authority; use prepare + install")
   if (existsSync(JOURNAL)) fail("a template transaction is pending; resolve it first")
   let id = imageId(version)
@@ -867,13 +934,14 @@ function upgrade(version, rehearse) {
     ok("new package staged beside the live one and verified")
   }
   const lifecycle = `${ROOT}/incoming-package/dist/heart/daemon/sanctuary-authority-root-lifecycle.js`
+  const priorImage = butlerState().split(" ")[0]
   const jellyfinBefore = docker(["inspect", "jellyfin", "--format", "{{.Id}}|{{.Image}}|{{.RestartCount}}|{{.State.StartedAt}}"]).trim()
   const policyBefore = existsSync(POLICY) ? sha12(POLICY) : fail("steward policy missing")
   pauseSupervision()
   let failure = null
   try {
-    say("lifecycle upgrade (stop → switch → resident → migrate → start)")
-    ok(sh("/usr/local/bin/node", [lifecycle, "upgrade", id, image(version), ...(rehearse ? ["--fail-after", rehearse] : [])], { stdio: ["ignore", "pipe", "pipe"] }).trim())
+    say(`lifecycle upgrade (stop → switch → resident → migrate → start${gated ? ", held uncommitted for the gate" : ""})`)
+    ok(sh("/usr/local/bin/node", [lifecycle, "upgrade", id, image(version), ...(rehearse ? ["--fail-after", rehearse] : gated ? ["--hold-commit"] : [])], { stdio: ["ignore", "pipe", "pipe"] }).trim())
   } catch (e) { failure = e }
   // Only the lifecycle's own rehearsal stop is planned; anything else is a real failure,
   // even during a rehearsal (the first 830 -> 835 rehearsal was mislabelled "as planned").
@@ -886,20 +954,58 @@ function upgrade(version, rehearse) {
       resumeSupervision()
       fail(`ROLLBACK FAILED: ${lifecycleFailure(e)}\nThe journal is kept; the next authority boot (or \`upgrade-rollback\`) retries it.`)
     }
-  } else { pinTemplate(version); pruneButlerImages() }
+  } else if (!gated) { pinTemplate(version); pruneButlerImages() }
   resumeSupervision()
   say("preservation")
-  docker(["inspect", "jellyfin", "--format", "{{.Id}}|{{.Image}}|{{.RestartCount}}|{{.State.StartedAt}}"]).trim() === jellyfinBefore ? ok("jellyfin unchanged") : fail("JELLYFIN CHANGED")
-  sha12(POLICY) === policyBefore ? ok("steward policy unchanged") : fail("STEWARD POLICY CHANGED")
+  const preserved = []
+  const jellyfinNow = docker(["inspect", "jellyfin", "--format", "{{.Id}}|{{.Image}}|{{.RestartCount}}|{{.State.StartedAt}}"]).trim()
+  jellyfinNow === jellyfinBefore ? ok("jellyfin unchanged") : (gated && !failure ? (bad("JELLYFIN CHANGED"), preserved.push("jellyfin changed")) : fail("JELLYFIN CHANGED"))
+  sha12(POLICY) === policyBefore ? ok("steward policy unchanged") : (gated && !failure ? (bad("STEWARD POLICY CHANGED"), preserved.push("steward policy changed")) : fail("STEWARD POLICY CHANGED"))
   const live = docker(["inspect", CONTAINER, "--format", "{{.Config.Image}} {{.State.Status}}/{{.State.Health.Status}}"]).trim()
   ok(`butler: ${live}`)
   if (failure && !planned) fail("upgrade rolled back; the Butler is on its prior version (see above)")
-  console.log(rehearse ? "\nREHEARSAL done — the upgrade reached the planned step and the rollback restored the predecessor." : `\nUPGRADE done — ${version} live. Run verify.`)
+  if (gated && !failure) {
+    say(`replay gate${plant ? ` (planted failure: ${plant})` : ""}`)
+    const stillHeld = () => heldUpgradeProblem({ journalExists: existsSync(UPGRADE_JOURNAL), liveImage: butlerState().split(" ")[0], expectedImage: image(version) })
+    const outcome = completeGatedUpgrade({
+      runGate: () => {
+        if (preserved.length) return { ok: false, detail: preserved.join("; ") }
+        if (!waitForButler(image(version), 300)) return { ok: false, detail: `the new Butler did not become healthy on ${image(version)}` }
+        const result = runReplayGate(plant)
+        if (!result.ok) return result
+        const problem = stillHeld()
+        return problem ? { ok: false, detail: problem } : result
+      },
+      commit: () => {
+        const problem = stillHeld()
+        if (problem) throw new Error(`refusing to commit: ${problem}`)
+        pauseSupervision()
+        try { ok(`commit: ${sh("/usr/local/bin/node", [lifecycle, "upgrade", id, image(version)], { stdio: ["ignore", "pipe", "pipe"] }).trim()}`) }
+        finally { resumeSupervision() }
+      },
+      rollback: () => {
+        pauseSupervision()
+        try { ok(`rollback: ${sh("/usr/local/bin/node", [lifecycle, "upgrade-rollback"], { stdio: ["ignore", "pipe", "pipe"] }).trim()}`) }
+        catch (e) { fail(`ROLLBACK FAILED: ${lifecycleFailure(e)}\nThe journal is kept; the next authority boot (or \`upgrade-rollback\`) retries it.`) }
+        finally { resumeSupervision() }
+      },
+      confirmRollback: () => {
+        if (!waitForButler(priorImage, 300)) fail(`rolled back, but ${priorImage} is not running healthy; inspect \`docker logs ${CONTAINER}\``)
+        return priorImage
+      },
+      pin: () => pinTemplate(version),
+      prune: () => pruneButlerImages(),
+    })
+    if (!outcome.passed) process.exit(1)
+    console.log(`\nUPGRADE done — ${version} live and gate-verified. Run verify.`)
+    return
+  }
+  console.log(rehearse ? "\nREHEARSAL done — the upgrade reached the planned step and the rollback restored the predecessor." : `\nUPGRADE done — ${version} live (NOT gate-verified). Run verify.`)
 }
 
 // ---- verify ---------------------------------------------------------------
 
-function verify() {
+function verify(withGate = false) {
   say("verify")
   const st = docker(["inspect", CONTAINER, "--format", "{{.Config.Image}} {{.State.Status}}/{{.State.Health.Status}} restarts={{.RestartCount}}"]).trim()
   ok(`butler: ${st}`)
@@ -908,6 +1014,11 @@ function verify() {
   existsSync(POLICY) ? ok(`steward policy ${sha12(POLICY)}`) : bad("steward policy missing")
   const jf = docker(["inspect", "jellyfin", "--format", "{{.State.Status}} restarts={{.RestartCount}}"]).trim()
   ok(`jellyfin ${jf}`)
+  if (withGate) {
+    say("replay gate (live version, no upgrade)")
+    const gate = runReplayGate(undefined)
+    gate.ok ? ok("replay gate passed") : bad(`replay gate failed: ${gate.detail}`)
+  }
   process.exit(RED === 0 ? 0 : 1)
 }
 
@@ -915,19 +1026,35 @@ function fail(m) { console.error(`\nREFUSING: ${m}`); process.exit(1) }
 
 // ---- entry ----------------------------------------------------------------
 
-const [phase, version, flag, rehearse] = process.argv.slice(2)
-if (!phase || !["preflight", "prepare", "install", "verify", "upgrade"].includes(phase) || (flag !== undefined && !(phase === "upgrade" && flag === "--rehearse" && rehearse))) {
-  console.error("Usage: sanctuary-butler-upgrade.mjs <preflight|prepare|install|verify|upgrade> <version> [--rehearse <step>]")
-  process.exit(2)
+export function parseUpgradeArgs(argv) {
+  const usage = "Usage: sanctuary-butler-upgrade.mjs <preflight|prepare|install|upgrade> <version> [--rehearse <step>] [--no-gate] [--plant <case>] | verify [--gate]"
+  const [phase, ...rest] = argv
+  if (!phase || !["preflight", "prepare", "install", "verify", "upgrade"].includes(phase)) throw new Error(usage)
+  const parsed = { phase, version: undefined, rehearse: undefined, noGate: false, plant: undefined, gate: false }
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i]
+    if (arg === "--rehearse" && phase === "upgrade" && rest[i + 1]) parsed.rehearse = rest[++i]
+    else if (arg === "--no-gate" && phase === "upgrade") parsed.noGate = true
+    else if (arg === "--plant" && phase === "upgrade" && rest[i + 1]) parsed.plant = rest[++i]
+    else if (arg === "--gate" && phase === "verify") parsed.gate = true
+    else if (!arg.startsWith("--") && parsed.version === undefined && phase !== "verify") parsed.version = arg
+    else throw new Error(usage)
+  }
+  if (parsed.noGate && parsed.plant) throw new Error("--plant needs the gate; it cannot be combined with --no-gate")
+  if (parsed.rehearse && (parsed.noGate || parsed.plant)) throw new Error("--rehearse does not use the gate; do not combine it with --no-gate or --plant")
+  if (phase !== "verify" && !/^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$/.test(parsed.version || "")) throw new Error("a semver version is required, e.g. 0.1.0-alpha.829")
+  return parsed
 }
-if (phase !== "verify" && !/^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$/.test(version || "")) {
-  console.error("a semver version is required, e.g. 0.1.0-alpha.829")
-  process.exit(2)
+
+function run(argv) {
+  let args
+  try { args = parseUpgradeArgs(argv) } catch (error) { console.error(error.message); process.exit(2) }
+  requireRoot()
+  if (args.phase === "preflight") preflight(args.version)
+  else if (args.phase === "prepare") prepare(args.version)
+  else if (args.phase === "install") install(args.version)
+  else if (args.phase === "verify") verify(args.gate)
+  else if (args.phase === "upgrade") upgrade(args.version, args.rehearse, { noGate: args.noGate, plant: args.plant })
 }
-requireRoot()
 
-if (phase === "preflight") preflight(version)
-else if (phase === "prepare") prepare(version)
-else if (phase === "install") install(version)
-else if (phase === "verify") verify()
-else if (phase === "upgrade") upgrade(version, rehearse)
+if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) run(process.argv.slice(2))

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.865",
   "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.865</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");

package/dist/a2a/replay-harness.js

@@ -0,0 +1,147 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPLAY_WINDOW_MAX_MS = void 0;
+exports.replayWindowPath = replayWindowPath;
+exports.replaySinkPath = replaySinkPath;
+exports.isReplayWindowOpen = isReplayWindowOpen;
+exports.appendReplayNotice = appendReplayNotice;
+exports.replayNoticeRecorded = replayNoticeRecorded;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("path"));
+const runtime_1 = require("../nerves/runtime");
+/**
+ * The replay gate drives the Butler over its real A2A path to check its behaviour after an upgrade. Every delegated
+ * command and every A2A-filed await would otherwise post to the owner's Telegram chat. While the host's gate holds a
+ * replay window open for a peer, those notices are appended to a local sink instead.
+ *
+ * The window narrows where a notice goes, never whether a command is authorized: the grant, family trust, sole owner
+ * and notify-before-run checks are unchanged, and "notify" means "the sink write succeeded". The window file lives
+ * under the bundle's state directory, is written by the host's gate and cleared when its run ends, and every entry
+ * expires on its own (and is ignored if it claims to last longer than the cap).
+ */
+exports.REPLAY_WINDOW_MAX_MS = 2 * 60 * 60 * 1000;
+function replayDir(agentRoot) {
+    return path.join(agentRoot, "state", "replay");
+}
+function replayWindowPath(agentRoot) {
+    return path.join(replayDir(agentRoot), "window.json");
+}
+function replaySinkPath(agentRoot) {
+    return path.join(replayDir(agentRoot), "notices.ndjson");
+}
+/** A root-controlled directory: a real directory (no symlink), owned by the trusted uid, writable by neither group nor other. */
+function isTrustedDirectory(target, trustedUid) {
+    try {
+        const stat = fs.lstatSync(target);
+        return stat.isDirectory() && !stat.isSymbolicLink() && stat.uid === trustedUid && (stat.mode & 0o022) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reads the window file only if the file actually opened is trusted. The path is opened once with O_NOFOLLOW, then the
+ * descriptor itself is checked (regular file, trusted owner, not group- or other-writable) and read, so a rename loop on
+ * the Butler's own state directory cannot swap a different file in between the check and the read. Any error is "no window".
+ */
+function readTrustedWindow(file, trustedUid) {
+    let fd;
+    try {
+        fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.uid !== trustedUid || (stat.mode & 0o022) !== 0)
+            return undefined;
+        return JSON.parse(fs.readFileSync(fd, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+/**
+ * True only when the window file lists `friendId` with an expiry that is in the future and within the cap. Any unreadable or malformed file means "closed".
+ * The state directory is the Butler's own, so it could swap in a directory and window of its own making: only a replay
+ * directory and window file that root owns, and nobody else can write, count; anything else fails toward Telegram.
+ */
+function isReplayWindowOpen(agentRoot, friendId, now = Date.now(), trustedUid = 0) {
+    if (!isTrustedDirectory(replayDir(agentRoot), trustedUid))
+        return false;
+    const parsed = readTrustedWindow(replayWindowPath(agentRoot), trustedUid);
+    const friends = parsed?.friends;
+    if (!friends || typeof friends !== "object")
+        return false;
+    const entry = friends[friendId];
+    const expiresAt = typeof entry?.expiresAt === "string"
+        ? Date.parse(entry.expiresAt)
+        : Number.NaN;
+    return Number.isFinite(expiresAt) && expiresAt > now && expiresAt <= now + exports.REPLAY_WINDOW_MAX_MS;
+}
+/** Appends one notice to the sink; throws when it cannot be written, so the caller refuses exactly as a failed Telegram send does. */
+function appendReplayNotice(agentRoot, notice, now = Date.now()) {
+    fs.mkdirSync(replayDir(agentRoot), { recursive: true });
+    const line = JSON.stringify({ at: new Date(now).toISOString(), ...notice });
+    fs.appendFileSync(replaySinkPath(agentRoot), `${line}\n`, { mode: 0o600 });
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.a2a_replay_notice_sunk",
+        message: "wrote an owner notice to the replay sink instead of Telegram",
+        meta: { noticeId: notice.noticeId, friendId: notice.friendId },
+    });
+}
+/** True when the sink holds a notice with this id for this friend (a missing sink is "no"). The sink is Butler-writable: callers must also require a trusted window. */
+function replayNoticeRecorded(agentRoot, noticeId, friendId) {
+    let raw;
+    try {
+        raw = fs.readFileSync(replaySinkPath(agentRoot), "utf8");
+    }
+    catch {
+        return false;
+    }
+    return raw.split("\n").some((line) => {
+        if (!line)
+            return false;
+        try {
+            const entry = JSON.parse(line);
+            return entry.noticeId === noticeId && entry.friendId === friendId;
+        }
+        catch {
+            return false;
+        }
+    });
+}

package/dist/heart/awaiting/a2a-await-delivery.js

@@ -37,6 +37,7 @@ exports.createA2AAwaitOwnerDeliverer = createA2AAwaitOwnerDeliverer;
 const path = __importStar(require("path"));
 const friends_1 = require("@ouro.bot/friends");
 const identity_1 = require("../identity");
+const replay_harness_1 = require("../../a2a/replay-harness");
 const runtime_1 = require("../../nerves/runtime");
 /**
  * An A2A peer is a client that calls this agent's server; there is no channel back to it. When an await filed from
@@ -52,6 +53,11 @@ function createA2AAwaitOwnerDeliverer(agentName, notifyOwner = defaultNotifyOwne
         }
         try {
             const peer = await new friends_1.FileFriendStore(path.join((0, identity_1.getAgentRoot)(agentName), "friends")).get(request.friendId);
+            const agentRoot = (0, identity_1.getAgentRoot)(agentName);
+            if ((0, replay_harness_1.isReplayWindowOpen)(agentRoot, request.friendId)) {
+                (0, replay_harness_1.appendReplayNotice)(agentRoot, { noticeId: request.deliveryId, text: request.content, friendId: request.friendId });
+                return { status: "delivered_now", detail: "written to the replay sink (replay window open for this peer)" };
+            }
             const from = peer?.name ?? "a connected agent";
             await notifyOwner({ noticeId: request.deliveryId, text: `Follow-up on a request from ${from}: ${request.content}` });
             return { status: "delivered_now", detail: "sent to the owner's Telegram chat as the agent" };

package/dist/heart/daemon/sanctuary-authority-root-lifecycle.js

@@ -765,6 +765,10 @@ class SanctuaryAuthorityRootLifecycle {
             if (input.failAfter === step)
                 throw new Error(`Sanctuary upgrade rehearsal stopped after ${step}`);
         }
+        // A held upgrade is live but uncommitted: its journal and the predecessor's records stay, so `upgrade-rollback`
+        // still undoes it exactly. Running `upgrade` again without the hold commits it. A completed upgrade cannot be rolled back.
+        if (input.holdCommit)
+            return;
         target().#bundle(["--operation", "commit"]);
         // A copy of the live token must not linger as if it were a fresh rotation (D-044).
         this.#remove(`${ROOT}/incoming-token`);
@@ -1128,10 +1132,11 @@ async function runSanctuaryAuthorityRootCli(argv, write = (text) => process.stdo
         return;
     }
     const repin = argv.length === 3 && argv[0] === "repin-execution";
-    const upgrade = argv[0] === "upgrade" && (argv.length === 3 || (argv.length === 5 && argv[3] === "--fail-after"));
+    const holdCommit = argv[0] === "upgrade" && argv.length === 4 && argv[3] === "--hold-commit";
+    const upgrade = argv[0] === "upgrade" && (argv.length === 3 || holdCommit || (argv.length === 5 && argv[3] === "--fail-after"));
     const rollback = argv.length === 1 && argv[0] === "upgrade-rollback";
     if (!repin && !upgrade && !rollback && (argv.length !== 1 || argv[0] !== "boot"))
-        throw new Error("Usage: sanctuary-authority-root-lifecycle <boot|repin-execution <prlimit-sha256> <setsid-sha256>|upgrade <target-image-id> <image-reference> [--fail-after <step>]|upgrade-rollback|vault snapshot|vault presence|vault remove|vault restore>");
+        throw new Error("Usage: sanctuary-authority-root-lifecycle <boot|repin-execution <prlimit-sha256> <setsid-sha256>|upgrade <target-image-id> <image-reference> [--fail-after <step>|--hold-commit]|upgrade-rollback|vault snapshot|vault presence|vault remove|vault restore>");
     // Boot never waits: the host keeper retries it. An operator upgrade waits out a boot in flight.
     await (0, session_transaction_1.withSessionTurnLease)(TEMPLATE_JOURNAL, async () => {
         const activationPath = `${ROOT}/activation.json`;
@@ -1147,8 +1152,8 @@ async function runSanctuaryAuthorityRootCli(argv, write = (text) => process.stdo
             write('{"repinned":true,"gatewayRestartRequired":true}\n');
         }
         else if (upgrade) {
-            await lifecycle.upgrade({ targetImageId: argv[1], imageReference: argv[2], ...(argv[4] ? { failAfter: argv[4] } : {}) });
-            write(`${JSON.stringify({ upgraded: argv[2] })}\n`);
+            await lifecycle.upgrade({ targetImageId: argv[1], imageReference: argv[2], ...(argv[4] ? { failAfter: argv[4] } : {}), ...(holdCommit ? { holdCommit: true } : {}) });
+            write(`${JSON.stringify({ upgraded: argv[2], ...(holdCommit ? { held: true } : {}) })}\n`);
         }
         else if (rollback) {
             write(`${JSON.stringify({ rolledBack: await lifecycle.rollbackUpgrade() })}\n`);

package/dist/senses/a2a-entry.js

@@ -47,6 +47,7 @@ function argValue(name) {
 const runtime_logging_1 = require("../heart/daemon/runtime-logging");
 const runtime_1 = require("../nerves/runtime");
 const delegated_command_1 = require("../a2a/delegated-command");
+const identity_1 = require("../heart/identity");
 (0, runtime_logging_1.configureDaemonRuntimeLogger)("a2a");
 (0, runtime_1.emitNervesEvent)({
     component: "senses",
@@ -101,6 +102,7 @@ Promise.all([
         ...(agentName === "sanctuary" ? {
             delegation: {
                 principalProfileId: delegated_command_1.A2A_PRINCIPAL_PROFILE_ID,
+                agentRoot: (0, identity_1.getAgentRoot)(agentName),
                 notifyPrincipal: async (notice) => {
                     const { sendTelegramOwnerNotice } = await Promise.resolve().then(() => __importStar(require("./telegram")));
                     await sendTelegramOwnerNotice(agentName, { ...notice, signal: AbortSignal.timeout(30_000) });

package/dist/senses/private-runtime.js

@@ -166,7 +166,7 @@ async function resolveA2APrincipal(agentRoot, store, peer, requestId) {
     if (owners.length !== 1 || owners[0].id === peer.id)
         throw new StaleRelationshipAwaitError("delegating owner cannot be resolved");
     const owner = owners[0];
-    if (!(0, delegated_command_1.delegatedCommandWasNoticed)(agentRoot, requestId, owner.id))
+    if (!(0, delegated_command_1.delegatedCommandWasNoticed)(agentRoot, requestId, owner.id, peer.id))
         throw new StaleRelationshipAwaitError("request was not a delegated command the owner was notified of");
     return owner;
 }

package/npm-shrinkwrap.json

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