@ouro.bot/cli 0.1.0-alpha.970 → 0.1.0-alpha.971

package/changelog.json

@@ -1,6 +1,12 @@
 {
   "_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.971",
+      "changes": [
+        "Ouro Butler can be installed on a new Unraid 7.2+ server with one script (deploy/unraid/install.sh, attached to every release): it asks a few questions, reads secrets with the echo off, creates the vault, Anthropic access and Unraid API keys, finds the owner's Telegram id, and installs the root authority with no earlier Butler to hand over from. vault config set can now read a secret from --value-file (use /dev/stdin to pipe it) and store the top-level Unraid and SABnzbd machine keys."
+      ]
+    },
     {
       "version": "0.1.0-alpha.970",
       "changes": [

package/deploy/unraid/INSTALL.md

@@ -0,0 +1,64 @@
+# Install Ouro Butler on Unraid
+
+Ouro Butler is an agent that lives on your Unraid server and looks after it with you over Telegram. It answers questions about the array, disks and containers, tells you when something goes wrong, and can update containers when you ask. It is an **alpha**: expect rough edges, and keep your own backups.
+
+## What you need
+
+- Unraid **7.2 or newer**, with Docker enabled and a working internet connection.
+- An **Anthropic API key** from [console.anthropic.com](https://console.anthropic.com/settings/keys), with credit on the account. The Butler uses Claude models.
+- A **Telegram bot** for the Butler: message [@BotFather](https://t.me/BotFather), send `/newbot`, and keep the token it gives you.
+- An **email address** for the Butler's vault account. The vault is a Bitwarden-compatible store at `vault.ouro.bot` (or your own server). Use an address no other Butler uses, such as `you+butler@example.com`; nothing is sent to it.
+- About 10 minutes at the Unraid web terminal.
+
+## Install
+
+Open the Unraid web terminal (the `>_` icon at the top right), then download the installer, read it if you like, and run it:
+
+```bash
+curl -fsSLo /tmp/ouro-butler-install.sh https://github.com/ourostack/ouroboros/releases/latest/download/install.sh
+less /tmp/ouro-butler-install.sh   # optional: read it first
+bash /tmp/ouro-butler-install.sh
+```
+
+The installer asks for your name, the Butler's name, the vault email, the Anthropic key and the bot token. Secrets are read with the terminal's echo off and never appear on a command line. It then:
+
+1. pulls the Butler image `ghcr.io/ourostack/ouroboros-butler` and seeds the Butler's files in `/mnt/user/appdata/ouro-butler`;
+2. creates the Butler's vault, asking you to choose an **unlock phrase** (write it down: it is the only way to recover the Butler's secrets if the server is lost), and stores the Anthropic key in it;
+3. creates two Unraid API keys for the Butler, `Butler RO …` (read-only) and `Butler RW …` (read-only plus Docker update), and stores them in the vault;
+4. asks you to send your bot any message on Telegram, so it learns your Telegram id and answers only you;
+5. installs the root authority, a small service that holds the Telegram token outside the Butler's container, and starts the Butler as the `ouro-butler` container.
+
+When it prints `Ouro Butler … is running`, say hello to your bot on Telegram.
+
+To install a specific release instead of the newest one, pass `--version 0.1.0-alpha.N`. To use your own Vaultwarden server, pass `--vault-server https://vault.example.com`.
+
+## Tell it about your home
+
+The Butler reads two files you own and that updates never overwrite:
+
+- `/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro/house/house.json`: names (`ownerName`, `butlerName`, `householdName`), `publicEndpoints` it should check (each `{ "name", "url" }`), and `requiredContainers` it should treat as must-run.
+- `/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro/house/HOUSE.md`: anything else worth knowing, in plain words: who lives here, what each container is for, what matters most.
+
+Edit them as root and keep the owner and mode (`chown 10001:10001`, `chmod 600`). The Butler picks up changes at its next conversation.
+
+## Updates
+
+Releases ship as new images. The Butler's maintainers upgrade with `deploy/unraid/sanctuary-butler-upgrade.mjs upgrade <version>`, which keeps the same Telegram token and rolls back on any failure. A friendlier update command is planned; until then, follow the release notes.
+
+## Known limits of the alpha
+
+- Unraid only, version 7.2 or newer. No docker compose or other hosts yet.
+- Anthropic is the supported model provider.
+- One owner per Butler; the Butler answers only the Telegram account that messaged it during install.
+- Media (Jellyfin) and book integrations are optional extras that are not set up by the installer yet.
+- The installer is for a first install. If it stops partway, fix the reported problem and run it again; it reuses the files and vault it already made. If it says a Butler is already installed, it will not touch it.
+
+## Stopping and removing
+
+To pause the Butler, stop the `ouro-butler` container on the Docker tab. To cut it off completely at any time, revoke its access at the source: delete the two `Butler RO …`/`Butler RW …` keys under **Settings → Management Access → API Keys**, revoke the bot token with @BotFather (`/revoke`), and delete the Anthropic key in the Anthropic console.
+
+A one-command uninstall that also removes the root authority's boot hook and files is not in this alpha yet. If you need it before then, open an issue and we will walk you through it.
+
+## Help
+
+Open an issue at [github.com/ourostack/ouroboros](https://github.com/ourostack/ouroboros/issues). Please include the installer's output (it never prints your secrets) and, for install failures, `/var/log/ouro-butler-install.log`.

package/deploy/unraid/docker-man-template-transaction.mjs

@@ -32,7 +32,9 @@ function exactKeys(value, expected, label) {
   if (JSON.stringify(keys) !== JSON.stringify([...expected].sort())) throw new Error(`${label} has unexpected fields`)
 }
 
+// A household without Jellyfin checkpoints null: the container must stay absent.
 function validateJellyfinState(raw, label = "Jellyfin checkpoint") {
+  if (raw === null) return null
   const value = object(raw, label)
   exactKeys(value, ["containerId", "imageId", "state", "restartCount"], label)
   if (!CONTAINER_ID.test(value.containerId) || !IMAGE_ID.test(value.imageId) || !JELLYFIN_STATES.has(value.state) || !Number.isSafeInteger(value.restartCount) || value.restartCount < 0) throw new Error(`${label} is invalid`)
@@ -40,6 +42,13 @@ function validateJellyfinState(raw, label = "Jellyfin checkpoint") {
 }
 
 export function inspectCurrentJellyfinState() {
+  let present
+  try {
+    present = execFileSync("/usr/bin/docker", ["container", "ls", "--all", "--quiet", "--filter", "name=^/jellyfin$"], { encoding: "utf8", maxBuffer: 65_536, stdio: ["ignore", "pipe", "ignore"] }).trim() !== ""
+  } catch {
+    throw new Error("Jellyfin container inspection failed")
+  }
+  if (!present) return null
   let inspected
   try {
     inspected = JSON.parse(execFileSync("/usr/bin/docker", ["container", "inspect", "--format", JELLYFIN_FORMAT, "jellyfin"], { encoding: "utf8", maxBuffer: 65_536, stdio: ["ignore", "pipe", "ignore"] }).trim())
@@ -57,6 +66,11 @@ function assertJellyfinUnchanged(expected) {
   if (JSON.stringify(current) !== JSON.stringify(expected)) throw new Error("Jellyfin changed during the Butler transaction")
 }
 
+// A fresh install has no predecessor image; its rollback image is null.
+function validRollbackImage(value) {
+  return value === null || IMAGE_ID.test(value)
+}
+
 function digest(bytes) {
   return `sha256:${createHash("sha256").update(bytes).digest("hex")}`
 }
@@ -217,7 +231,7 @@ function validateJournalRecord(raw, state) {
   } else if (prior.bytesBase64 !== null || prior.metadata !== null || record.priorTemplateDigest !== null) {
     throw new Error("template transaction journal absent prior state is invalid")
   }
-  if (!VERSION_TAG.test(record.canonicalVersionTag) || !IMAGE_ID.test(record.reviewedManifestDigest) || !IMAGE_ID.test(record.rollbackImageId) || !IMAGE_ID.test(record.targetImageId) || record.rollbackImageId === record.targetImageId || !IMAGE_ID.test(record.targetTemplateDigest)) throw new Error("template transaction journal release identity is invalid")
+  if (!VERSION_TAG.test(record.canonicalVersionTag) || !IMAGE_ID.test(record.reviewedManifestDigest) || !validRollbackImage(record.rollbackImageId) || !IMAGE_ID.test(record.targetImageId) || record.rollbackImageId === record.targetImageId || !IMAGE_ID.test(record.targetTemplateDigest)) throw new Error("template transaction journal release identity is invalid")
   const jellyfin = validateJellyfinState(record.jellyfin, "template transaction journal Jellyfin checkpoint")
   if (!IMAGE_ID.test(record.digest) || record.digest !== recordDigest(record)) throw new Error("template transaction journal digest is invalid")
   return { ...record, jellyfin, priorBytes }
@@ -305,7 +319,7 @@ function validateTemplateSource(input, state) {
   if (metadataIfPresent(state.targetPath)) validateRegularFile(state.targetPath, state.expectedUid, state.expectedGid, "DockerMan template")
   validateDirectory(dirname(input.sourceTemplatePath), state.expectedUid, state.expectedGid)
   validateRegularFile(input.sourceTemplatePath, state.expectedUid, state.expectedGid, "source template")
-  if (!VERSION_TAG.test(input.canonicalVersionTag) || !IMAGE_ID.test(input.reviewedManifestDigest) || !IMAGE_ID.test(input.rollbackImageId) || !IMAGE_ID.test(input.targetImageId) || input.rollbackImageId === input.targetImageId) throw new Error("reviewed release identity is invalid")
+  if (!VERSION_TAG.test(input.canonicalVersionTag) || !IMAGE_ID.test(input.reviewedManifestDigest) || !validRollbackImage(input.rollbackImageId) || !IMAGE_ID.test(input.targetImageId) || input.rollbackImageId === input.targetImageId) throw new Error("reviewed release identity is invalid")
   const sourceBytes = readFileSync(input.sourceTemplatePath)
   const identity = templateIdentity(sourceBytes, input.canonicalVersionTag)
   return { sourceBytes, identity }
@@ -434,7 +448,7 @@ function validateAuthorityPlan(raw) {
   exactKeys(plan, ["schemaVersion", "epochId", "packageDigest", "publicKeyDigest", "botId", "ownerUserId", "ownerChatId", "predecessorContract", "targetContract"], "authority handoff plan")
   if (plan.schemaVersion !== 1 || !/^[A-Za-z0-9_-]{1,128}$/u.test(plan.epochId) || !IMAGE_ID.test(plan.packageDigest) || (plan.publicKeyDigest !== null && !IMAGE_ID.test(plan.publicKeyDigest))
     || !["botId", "ownerUserId", "ownerChatId"].every((key) => typeof plan[key] === "string" && /^[1-9][0-9]*$/u.test(plan[key]))
-    || plan.ownerUserId !== plan.ownerChatId || plan.predecessorContract !== "canonical-pre-gateway" || plan.targetContract !== "canonical-gateway") throw new Error("authority handoff plan is invalid")
+    || plan.ownerUserId !== plan.ownerChatId || !["canonical-pre-gateway", "none"].includes(plan.predecessorContract) || plan.targetContract !== "canonical-gateway") throw new Error("authority handoff plan is invalid")
   return plan
 }
 
@@ -446,6 +460,8 @@ function validateAuthorityHandoff(raw, record) {
   const handoff = object(raw, "authority handoff")
   exactKeys(handoff, ["plan", "state", "completed", "rollbackCompleted", "pending", "cancelled"], "authority handoff")
   validateAuthorityPlan(handoff.plan)
+  // Only a fresh install (no predecessor) may lack a rollback image, and it must lack one.
+  if ((handoff.plan.predecessorContract === "none") !== (record.rollbackImageId === null)) throw new Error("authority handoff plan does not match the rollback image")
   if (!["installing", "active", "retiring", "retired"].includes(handoff.state) || !Array.isArray(handoff.completed) || !Array.isArray(handoff.rollbackCompleted) || !Array.isArray(handoff.cancelled)) throw new Error("authority handoff state is invalid")
   const validateEffect = (effect, direction, step) => {
     object(effect, "authority effect")
@@ -627,7 +643,7 @@ export function runDockerManTemplateTransactionCli(argv, options = {}, write = (
       sourceTemplatePath: values.get("--source-template"),
       canonicalVersionTag: values.get("--version-tag"),
       reviewedManifestDigest: values.get("--manifest-digest"),
-      rollbackImageId: values.get("--rollback-image-id"),
+      rollbackImageId: values.get("--rollback-image-id") === "none" ? null : values.get("--rollback-image-id"),
       targetImageId: values.get("--target-image-id"),
     }, options)
   } else if (operation === "mark-committing" && values.size === 0) {

package/deploy/unraid/install.sh

@@ -0,0 +1,274 @@
+#!/bin/bash
+# Ouro Butler installer for Unraid 7.2 or newer.
+#
+# Run it as root in the Unraid web terminal. Download it and read it first if you like:
+#   curl -fsSLo /tmp/ouro-butler-install.sh https://github.com/ourostack/ouroboros/releases/latest/download/install.sh
+#   bash /tmp/ouro-butler-install.sh
+#
+# What it does, in order (each step says what it is doing as it goes):
+#   1. checks this is Unraid 7.2+, as root, with Docker running and no Butler installed yet
+#   2. asks for your name, the Butler's name, a vault email, your Anthropic API key and your Telegram bot token
+#      (secrets are read with the terminal's echo off and never appear in a command line)
+#   3. pulls the Butler image and seeds the Butler's files under /mnt/user/appdata/ouro-butler
+#   4. creates the Butler's vault (you choose its unlock phrase) and stores the Anthropic key in it
+#   5. creates two Unraid API keys for the Butler (read-only, and read plus Docker update) and stores them in the vault
+#   6. finds your Telegram user id when you message the bot, then installs the root authority that holds the bot
+#      token and starts the Butler
+#
+# Options:
+#   --version <0.1.0-alpha.N>   install this release instead of the newest one
+#   --vault-server <url>        use your own Vaultwarden-compatible server instead of https://vault.ouro.bot
+#   --help                      print this header
+set -euo pipefail
+umask 077
+
+IMAGE_REPO=ghcr.io/ourostack/ouroboros-butler
+APPDATA=/mnt/user/appdata/ouro-butler
+RUNTIME=$APPDATA/runtime/.ouro-cli
+BUNDLE=$APPDATA/agent/sanctuary.ouro
+STAGE=$APPDATA/installer
+AUTHORITY=/mnt/user/appdata/ouro-authority
+EVENTS=/boot/config/custom/ouro-events
+CONTAINER=ouro-butler
+AGENT=sanctuary
+TTY=/dev/tty
+VERSION=""
+VAULT_SERVER=""
+
+say() { printf '\n== %s\n' "$*"; }
+ok() { printf '  ok   %s\n' "$*"; }
+die() { printf '\nSTOPPED: %s\n' "$*" >&2; exit 1; }
+
+ask() { # ask <variable> <prompt> [default]
+  local answer
+  printf '%s%s: ' "$2" "${3:+ [$3]}" > "$TTY"
+  IFS= read -r answer < "$TTY" || die "no answer read from the terminal"
+  printf -v "$1" '%s' "${answer:-${3:-}}"
+}
+
+ask_secret() { # ask_secret <variable> <prompt>
+  local answer saved
+  saved=$(stty -g < "$TTY")
+  printf '%s (input is hidden): ' "$2" > "$TTY"
+  stty -echo < "$TTY"
+  IFS= read -r answer < "$TTY" || { stty "$saved" < "$TTY"; die "no answer read from the terminal"; }
+  stty "$saved" < "$TTY"
+  printf '\n' > "$TTY"
+  printf -v "$1" '%s' "$answer"
+}
+
+confirm() { local reply; ask reply "$1 (y/n)" n; case "$reply" in y|Y|yes|YES) return 0 ;; *) return 1 ;; esac; }
+
+while (($# > 0)); do
+  case "$1" in
+    --version) VERSION="${2:?--version needs a value, for example 0.1.0-alpha.970}"; shift 2 ;;
+    --vault-server) VAULT_SERVER="${2:?--vault-server needs a URL}"; shift 2 ;;
+    --help|-h) sed -n '2,/^set -euo/p' "$0" | sed '$d; s/^# \{0,1\}//'; exit 0 ;;
+    *) die "unknown option $1 (see --help)" ;;
+  esac
+done
+
+# The ouro CLI from the Butler image, run against the Butler's own files as the Butler's user.
+ouro() {
+  docker run --rm --pull=never --network host --user 10001:10001 \
+    --mount "type=bind,src=$RUNTIME,dst=/home/ouro/.ouro-cli" \
+    --mount "type=bind,src=$BUNDLE,dst=/home/ouro/AgentBundles/$AGENT.ouro" \
+    --entrypoint node "$IMAGE" /opt/ouro/dist/heart/daemon/ouro-entry.js "$@"
+}
+ouro_stdin() {
+  docker run --rm -i --pull=never --network host --user 10001:10001 \
+    --mount "type=bind,src=$RUNTIME,dst=/home/ouro/.ouro-cli" \
+    --mount "type=bind,src=$BUNDLE,dst=/home/ouro/AgentBundles/$AGENT.ouro" \
+    --entrypoint node "$IMAGE" /opt/ouro/dist/heart/daemon/ouro-entry.js "$@"
+}
+ouro_interactive() {
+  docker run --rm -it --pull=never --network host --user 10001:10001 \
+    --mount "type=bind,src=$RUNTIME,dst=/home/ouro/.ouro-cli" \
+    --mount "type=bind,src=$BUNDLE,dst=/home/ouro/AgentBundles/$AGENT.ouro" \
+    --entrypoint node "$IMAGE" /opt/ouro/dist/heart/daemon/ouro-entry.js "$@" < "$TTY"
+}
+
+# Write a private file owned by the Butler's user from stdin.
+write_butler_file() {
+  local path=$1
+  cat > "$path.tmp.$$"
+  chown 10001:10001 "$path.tmp.$$"
+  chmod 0600 "$path.tmp.$$"
+  mv -f "$path.tmp.$$" "$path"
+}
+
+# ---------------------------------------------------------------------------------------------------------------
+say "1. checking this host"
+test "$(id -u)" = 0 || die "run this as root (the Unraid web terminal is root)"
+test -r "$TTY" || die "this installer needs a terminal for its questions; run it in the Unraid web terminal"
+test -r /etc/unraid-version || die "this is not Unraid (no /etc/unraid-version)"
+UNRAID_VERSION=$(sed -n 's/^version="\([0-9.]*\).*/\1/p' /etc/unraid-version)
+IFS=. read -r UNRAID_MAJOR UNRAID_MINOR _ <<< "$UNRAID_VERSION"
+if ((UNRAID_MAJOR < 7 || (UNRAID_MAJOR == 7 && UNRAID_MINOR < 2))); then die "Unraid $UNRAID_VERSION is too old; the Butler needs Unraid 7.2 or newer"; fi
+ok "Unraid $UNRAID_VERSION"
+command -v node >/dev/null || die "node is missing (Unraid 7.2 ships it at /usr/local/bin/node)"
+command -v unraid-api >/dev/null || die "unraid-api is missing (Unraid 7.2 ships it)"
+docker info >/dev/null 2>&1 || die "Docker is not running; start it in Settings > Docker"
+ok "node, unraid-api and Docker are available"
+! docker container inspect "$CONTAINER" >/dev/null 2>&1 || die "an $CONTAINER container already exists; this installer is for a first install (upgrades use the Butler's own upgrade path)"
+test ! -e "$AUTHORITY/active.json" || die "a Butler authority is already installed on this host"
+ok "no Butler installed yet"
+
+if test -z "$VERSION"; then
+  VERSION=$(node -e 'fetch("https://registry.npmjs.org/-/package/@ouro.bot/cli/dist-tags").then(r => r.json()).then(t => process.stdout.write(t.latest)).catch(() => process.exit(1))') \
+    || die "could not look up the newest Butler release; pass --version"
+fi
+[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9.]+)?$ ]] || die "version $VERSION does not look like a release version"
+IMAGE=$IMAGE_REPO:$VERSION
+ok "installing Ouro Butler $VERSION"
+
+# ---------------------------------------------------------------------------------------------------------------
+say "2. a few questions"
+printf 'The Butler lives on this server and talks to you on Telegram. You can change any name later in\n%s/house/house.json.\n\n' "$BUNDLE" > "$TTY"
+ask OWNER_NAME "Your first name" ""
+test -n "$OWNER_NAME" || die "a name is needed so the Butler knows who it works for"
+ask BUTLER_NAME "What should the Butler call itself" "Butler"
+ask HOUSEHOLD_NAME "A name for this household or server" "$(hostname)"
+printf '\nThe Butler keeps its secrets in a Bitwarden-compatible vault. It gets its own vault account, so use an\nemail address no other Butler uses (for example you+butler@example.com). No mail is sent to it.\n' > "$TTY"
+ask VAULT_EMAIL "Vault account email" ""
+[[ "$VAULT_EMAIL" == *@*.* ]] || die "that does not look like an email address"
+printf '\nThe Butler thinks with Anthropic models. Create an API key at https://console.anthropic.com/settings/keys\n' > "$TTY"
+ask_secret ANTHROPIC_KEY "Anthropic API key"
+[[ "$ANTHROPIC_KEY" == sk-ant-* ]] || die "Anthropic API keys start with sk-ant-"
+printf '\nCreate a Telegram bot for the Butler: message @BotFather, send /newbot, and copy the token it gives you.\n' > "$TTY"
+ask_secret BOT_TOKEN "Telegram bot token"
+[[ "$BOT_TOKEN" =~ ^[0-9]+:[A-Za-z0-9_-]+$ ]] || die "that does not look like a Telegram bot token (digits, a colon, then letters)"
+BOT_INFO=$(TOKEN="$BOT_TOKEN" node -e '
+  fetch(`https://api.telegram.org/bot${process.env.TOKEN}/getMe`).then(r => r.json()).then(b => {
+    if (!b.ok) process.exit(2)
+    process.stdout.write(`${b.result.id}\t${b.result.username}`)
+  }).catch(() => process.exit(1))') || die "Telegram did not accept that bot token"
+BOT_USERNAME=${BOT_INFO#*$'\t'}
+ok "Telegram knows the bot @$BOT_USERNAME"
+
+# ---------------------------------------------------------------------------------------------------------------
+say "3. Butler image and files"
+docker pull "$IMAGE" >/dev/null || die "could not pull $IMAGE"
+ok "pulled $IMAGE"
+install -d -m 0700 -o 10001 -g 10001 "$APPDATA" "$APPDATA/runtime" "$APPDATA/agent" "$RUNTIME" "$BUNDLE"
+install -d -m 0700 -o 0 -g 0 "$AUTHORITY" "$STAGE"
+if test ! -f "$RUNTIME/machine.json"; then
+  NOW=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
+  printf '{\n  "schemaVersion": 1,\n  "machineId": "%s",\n  "createdAt": "%s",\n  "updatedAt": "%s",\n  "hostnameAliases": []\n}\n' "$AGENT" "$NOW" "$NOW" | write_butler_file "$RUNTIME/machine.json"
+fi
+if test ! -f "$BUNDLE/agent.json"; then
+  test -z "$(find "$BUNDLE" -mindepth 1 -print -quit)" || die "$BUNDLE has files but no agent.json; move it aside and run the installer again"
+  docker run --rm --pull=never --network=none --user 10001:10001 \
+    --mount "type=bind,src=$BUNDLE,dst=/home/ouro/AgentBundles/$AGENT.ouro" \
+    --entrypoint /bin/sh "$IMAGE" -ceu '
+      cp -R /opt/ouro/deploy/unraid/sanctuary.ouro/. /home/ouro/AgentBundles/sanctuary.ouro/
+      find /home/ouro/AgentBundles/sanctuary.ouro -type d -exec chmod 0700 {} +
+      find /home/ouro/AgentBundles/sanctuary.ouro -type f -exec chmod 0600 {} +'
+fi
+ok "Butler files seeded in $BUNDLE"
+install -d -m 0700 -o 10001 -g 10001 "$BUNDLE/house"
+OWNER_NAME=$OWNER_NAME BUTLER_NAME=$BUTLER_NAME HOUSEHOLD_NAME=$HOUSEHOLD_NAME node -e '
+  const house = { ownerName: process.env.OWNER_NAME, butlerName: process.env.BUTLER_NAME, householdName: process.env.HOUSEHOLD_NAME, publicEndpoints: [], requiredContainers: [] }
+  process.stdout.write(`${JSON.stringify(house, null, 2)}\n`)' | write_butler_file "$BUNDLE/house/house.json"
+if test ! -f "$BUNDLE/house/HOUSE.md"; then
+  printf '# %s\n\n%s owns this Unraid server and is the person %s works for.\n\nAdd anything the Butler should know about this household here: who lives here, what each container is for, what matters most. The Butler reads this file at the start of every conversation.\n' \
+    "$HOUSEHOLD_NAME" "$OWNER_NAME" "$BUTLER_NAME" | write_butler_file "$BUNDLE/house/HOUSE.md"
+fi
+ok "house description written to $BUNDLE/house"
+
+ASSETS=ouro-butler-installer-assets
+docker rm -f "$ASSETS" >/dev/null 2>&1 || true
+docker create --name "$ASSETS" "$IMAGE" >/dev/null
+docker cp "$ASSETS:/opt/ouro/deploy/unraid/sanctuary-butler-upgrade.mjs" "$STAGE/sanctuary-butler-upgrade.mjs" >/dev/null
+docker cp "$ASSETS:/opt/ouro/deploy/unraid/ouro-events/bootstrap-spool.sh" "$STAGE/bootstrap-spool.sh" >/dev/null
+docker rm -f "$ASSETS" >/dev/null
+chown 0:0 "$STAGE"/*; chmod 0700 "$STAGE"/*
+bash "$STAGE/bootstrap-spool.sh" --install-only
+bash "$EVENTS/bootstrap-spool.sh" --mount
+ok "event spool mounted and registered to mount at boot"
+
+# ---------------------------------------------------------------------------------------------------------------
+say "4. vault and model provider"
+VAULT_STATUS=$(ouro vault status --agent "$AGENT" --store plaintext-file 2>&1 || true)
+if [[ "$VAULT_STATUS" != *"local unlock: available"* ]]; then
+  printf 'Creating the vault. Choose an unlock phrase and keep it somewhere safe: it is the only way to recover\nthe Butler'"'"'s secrets if this server is lost.\n' > "$TTY"
+  ouro_interactive vault create --agent "$AGENT" --email "$VAULT_EMAIL" ${VAULT_SERVER:+--server "$VAULT_SERVER"} --store plaintext-file \
+    || die "vault creation did not finish; run the installer again to retry"
+fi
+ok "vault ready"
+printf '%s' "$ANTHROPIC_KEY" | ouro_stdin auth --agent "$AGENT" --provider anthropic --api-key-file /dev/stdin >/dev/null \
+  || die "storing the Anthropic key failed"
+unset ANTHROPIC_KEY
+for LANE in outward inner; do
+  ouro check --agent "$AGENT" --lane "$LANE" >/dev/null 2>&1 || die "the $LANE model lane did not answer; check the Anthropic key and your account's credit"
+done
+ok "Anthropic key stored in the vault; both model lanes answer"
+
+# ---------------------------------------------------------------------------------------------------------------
+say "5. Unraid API access"
+PORT=$(sed -n 's/^PORT="\{0,1\}\([0-9]*\)"\{0,1\}$/\1/p' /boot/config/ident.cfg 2>/dev/null | head -1)
+GRAPHQL_URL="http://127.0.0.1${PORT:+$( [ "$PORT" = 80 ] || printf ':%s' "$PORT")}/graphql"
+READ_PERMISSIONS="ARRAY:READ_ANY,DASHBOARD:READ_ANY,DISK:READ_ANY,DOCKER:READ_ANY,INFO:READ_ANY,LOGS:READ_ANY,NOTIFICATIONS:READ_ANY,SHARE:READ_ANY,VARS:READ_ANY"
+STAMP=$(date +%Y%m%d%H%M%S)
+create_unraid_key() { # create_unraid_key <name> <permissions> <vault field>
+  # Unraid 7.2's CLI refuses --permissions without a role ("Invalid data structure"); GUEST adds only own-profile access.
+  unraid-api apikey --create --name "$1" --roles GUEST --permissions "$2" --description "Ouro Butler $3" --json 2>/dev/null \
+    | node -e '
+        let text = ""; process.stdin.on("data", (c) => text += c).on("end", () => {
+          const start = text.indexOf("{"); if (start < 0) process.exit(1)
+          const key = JSON.parse(text.slice(start)).key; if (typeof key !== "string" || !key) process.exit(1)
+          process.stdout.write(key) })' \
+    | ouro_stdin vault config set --agent "$AGENT" --key "$3" --scope machine --value-file /dev/stdin >/dev/null \
+    || die "creating the Unraid API key $1 failed"
+}
+create_unraid_key "Butler RO $STAMP" "$READ_PERMISSIONS" unraidReadApiKey
+create_unraid_key "Butler RW $STAMP" "$READ_PERMISSIONS,DOCKER:UPDATE_ANY" unraidWriteApiKey
+ouro vault config set --agent "$AGENT" --key unraidGraphqlUrl --scope machine --value "$GRAPHQL_URL" >/dev/null
+ok "API keys \"Butler RO $STAMP\" and \"Butler RW $STAMP\" created (see Settings > Management Access > API Keys)"
+
+# ---------------------------------------------------------------------------------------------------------------
+say "6. Telegram and the root authority"
+test ! -L "$AUTHORITY/incoming-token" || die "$AUTHORITY/incoming-token is a link; remove it and run again"
+printf '%s' "$BOT_TOKEN" > "$AUTHORITY/incoming-token.tmp.$$"
+chmod 0600 "$AUTHORITY/incoming-token.tmp.$$"
+mv -f "$AUTHORITY/incoming-token.tmp.$$" "$AUTHORITY/incoming-token"
+unset BOT_TOKEN
+printf '\nOpen Telegram, find @%s and send it any message (for example "hello"). Waiting up to 3 minutes...\n' "$BOT_USERNAME" > "$TTY"
+OWNER_INFO=$(node -e '
+  const token = require("node:fs").readFileSync(process.argv[1], "utf8").trim()
+  const api = (method, query) => fetch(`https://api.telegram.org/bot${token}/${method}?${query}`).then((r) => r.json())
+  const deadline = Date.now() + 180000
+  ;(async () => {
+    while (Date.now() < deadline) {
+      const body = await api("getUpdates", "timeout=20&allowed_updates=%5B%22message%22%5D").catch(() => null)
+      const updates = body && body.ok ? body.result : []
+      const latest = updates.filter((u) => u.message && u.message.chat && u.message.chat.type === "private" && u.message.from).pop()
+      if (latest) {
+        await api("getUpdates", `offset=${latest.update_id + 1}&timeout=0`).catch(() => null)
+        const from = latest.message.from
+        process.stdout.write(`${from.id}\t${from.first_name || ""}${from.username ? ` (@${from.username})` : ""}`)
+        return
+      }
+      if (body && body.ok === false) { process.stderr.write(`Telegram: ${body.description}\n`); process.exit(2) }
+    }
+    process.exit(1)
+  })()' "$AUTHORITY/incoming-token") || die "no message reached the bot; run the installer again and message the bot when asked"
+OWNER_ID=${OWNER_INFO%%$'\t'*}
+confirm "The message came from ${OWNER_INFO#*$'\t'}. Is that you" || die "only the owner should message the bot during install; run the installer again"
+ok "owner Telegram id found"
+
+UPGRADE=(node "$STAGE/sanctuary-butler-upgrade.mjs")
+"${UPGRADE[@]}" preflight "$VERSION" --fresh || die "preflight found a problem (above); nothing has been installed yet"
+"${UPGRADE[@]}" prepare "$VERSION" --fresh --owner-id "$OWNER_ID" || die "prepare found a problem (above)"
+LOG=/var/log/ouro-butler-install.log
+printf 'Installing the authority and starting the Butler. This runs on even if this terminal closes; its log is %s.\n' "$LOG" > "$TTY"
+setsid nohup "${UPGRADE[@]}" install "$VERSION" > "$LOG" 2>&1 < /dev/null &
+INSTALL_PID=$!
+tail -n +1 --pid="$INSTALL_PID" -f "$LOG"
+wait "$INSTALL_PID" || die "install did not complete and was rolled back; the log is $LOG"
+"${UPGRADE[@]}" verify || die "the Butler is installed but verify found a problem (above)"
+
+say "done"
+printf 'Ouro Butler %s is running. Say hello to @%s on Telegram.\n' "$VERSION" "$BOT_USERNAME"
+printf 'Tell it about your household in %s/house/HOUSE.md.\n' "$BUNDLE"
+printf 'Keep the vault unlock phrase you chose somewhere safe.\n'

package/deploy/unraid/migrate-sanctuary-bundle.mjs

@@ -2,7 +2,7 @@
 import * as path from "node:path"
 import { pathToFileURL } from "node:url"
 
-const USAGE = "Usage: migrate-sanctuary-bundle.mjs --package-root <path> --agent-root <path> --operation <migrate|rollback|finalize-rollback|commit|status|inspect> [--rollback-image-id <sha256:id> --target-image-id <sha256:id>]"
+const USAGE = "Usage: migrate-sanctuary-bundle.mjs --package-root <path> --agent-root <path> --operation <migrate|seed|rollback|finalize-rollback|commit|status|inspect> [--rollback-image-id <sha256:id> --target-image-id <sha256:id>]"
 const BASE_KEYS = ["--package-root", "--agent-root", "--operation"]
 const MIGRATE_KEYS = [...BASE_KEYS, "--rollback-image-id", "--target-image-id"]
 
@@ -16,7 +16,7 @@ function parseArguments(args) {
     values.set(key, value)
   }
   const operation = values.get("--operation")
-  if (!["migrate", "rollback", "finalize-rollback", "commit", "status", "inspect"].includes(operation)) throw new Error(USAGE)
+  if (!["migrate", "seed", "rollback", "finalize-rollback", "commit", "status", "inspect"].includes(operation)) throw new Error(USAGE)
   const expectedKeys = operation === "migrate" ? MIGRATE_KEYS : BASE_KEYS
   if (values.size !== expectedKeys.length || expectedKeys.some((key) => !values.has(key)) || [...values.keys()].some((key) => !expectedKeys.includes(key))) throw new Error(USAGE)
   return values
@@ -29,6 +29,9 @@ export function runSanctuaryBundleOperation(args, dependencies) {
   const operation = values.get("--operation")
   const result = operation === "migrate"
     ? dependencies.migrate({ packageRoot, agentRoot, retainRollback: true, rollbackImageId: values.get("--rollback-image-id"), targetImageId: values.get("--target-image-id") })
+    // A fresh install has no earlier image to roll back to, so it writes the packaged files without a rollback record.
+    : operation === "seed"
+      ? dependencies.migrate({ packageRoot, agentRoot, retainRollback: false })
     : operation === "rollback"
       ? { rolledBack: dependencies.rollback(agentRoot, { retainRecord: true }) }
       // `rollback` keeps crash-retry evidence; the host uses `finalize-rollback` only after old production is audited, ready, and restored to autostart.

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

@@ -37,7 +37,13 @@
 //   --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
 //
+// A fresh install (a host that never ran a Butler) passes --fresh to preflight and prepare. prepare --fresh takes the
+// bot id from Telegram getMe on the token already at incoming-token and the owner from --owner-id, and writes
+// predecessorContract "none" into request.json; install, upgrade and verify read that contract from there.
+//
 // Usage: sanctuary-butler-upgrade.mjs <preflight|prepare|install|verify|upgrade> <version> [--rehearse <step>] [--no-gate] [--plant <case>]
+//        sanctuary-butler-upgrade.mjs preflight <version> --fresh
+//        sanctuary-butler-upgrade.mjs prepare <version> --fresh --owner-id <telegram user id>
 //        sanctuary-butler-upgrade.mjs verify [--gate]
 
 import { execFileSync, spawn, spawnSync } from "node:child_process"
@@ -124,23 +130,26 @@ function imageId(version) {
 
 // ---- read-only rehearsal --------------------------------------------------
 
-function preflight(version) {
-  say(`preflight for ${version} (read-only; nothing is changed)`)
+function preflight(version, { fresh = false } = {}) {
+  say(`preflight for ${version}${fresh ? " (fresh install)" : ""} (read-only; nothing is changed)`)
 
   say("target image present and pulled")
   let id = imageId(version)
   if (!id) { try { docker(["pull", image(version)]); id = imageId(version) } catch { /* reported below */ } }
   id ? ok(`image ${id.slice(0, 19)}…`) : bad(`image ${image(version)} not present and could not be pulled`)
 
-  say("running Butler and rollback material")
+  say(fresh ? "no Butler on this host yet" : "running Butler and rollback material")
   let runningImage = null
-  try {
+  if (fresh) {
+    containerExists(CONTAINER) ? bad(`an ${CONTAINER} container already exists; a fresh install needs a host without one`) : ok(`no ${CONTAINER} container`)
+    existsSync(`${ROOT}/active.json`) ? bad("an authority is installed; this host is not fresh") : ok("no installed authority")
+  } else try {
     runningImage = docker(["inspect", CONTAINER, "--format", "{{.Image}}"], { stdio: ["ignore", "pipe", "ignore"] }).trim()
     ok(`running image ${runningImage.slice(0, 19)}… (this is the rollback target)`)
   } catch { bad(`the ${CONTAINER} container is absent`) }
   if (id && runningImage && id === runningImage) bad("target and running image are identical — nothing to upgrade")
 
-  const installed = existsSync(`${ROOT}/active.json`)
+  const installed = !fresh && existsSync(`${ROOT}/active.json`)
   if (installed) console.log("  note: an authority is installed, so this is an in-place upgrade (run `upgrade`, no token rotation)")
 
   say("no stale authority runtime state")
@@ -196,6 +205,7 @@ function preflight(version) {
 
   say("D-018: the fenced vault read the install depends on")
   if (installed) ok("not needed: the installed gateway already holds the token in root custody")
+  else if (fresh) ok("not needed: a fresh install hands the new token straight to the root authority")
   else if (id) {
     // Run the read fenced exactly as THIS version's install will fence it, so
     // the rehearsal is faithful: an unfixed image is tested without the fix and
@@ -220,12 +230,12 @@ function preflight(version) {
   } catch { bad("could not read disk free space") }
 
   say("preservation baselines readable")
-  existsSync(POLICY) ? ok(`steward policy present (${sha12(POLICY)})`) : bad(`steward policy missing at ${POLICY}`)
-  try { docker(["inspect", "jellyfin", "--format", "{{.Id}}"], { stdio: ["ignore", "pipe", "ignore"] }); ok("jellyfin inspectable for the unchanged-check") }
-  catch { bad("jellyfin container not inspectable") }
+  existsSync(POLICY) ? ok(`steward policy present (${sha12(POLICY)})`) : fresh ? ok("no steward policy yet (fresh install)") : bad(`steward policy missing at ${POLICY}`)
+  try { ok(jellyfinState() ? "jellyfin inspectable for the unchanged-check" : "no jellyfin container; it must stay absent") }
+  catch { bad("docker could not list or inspect the jellyfin container") }
 
   console.log("")
-  if (RED === 0) console.log(installed ? "PREFLIGHT GREEN — run `upgrade` (detached)." : "PREFLIGHT GREEN — the upgrade can proceed. Next: prepare, rotate the token, install.")
+  if (RED === 0) console.log(installed ? "PREFLIGHT GREEN — run `upgrade` (detached)." : fresh ? "PREFLIGHT GREEN — next: put the bot token at incoming-token, prepare --fresh, install." : "PREFLIGHT GREEN — the upgrade can proceed. Next: prepare, rotate the token, install.")
   else console.log(`PREFLIGHT RED — ${RED} blocker(s) above. Nothing was changed; fix these before rotating the token.`)
   process.exit(RED === 0 ? 0 : 1)
 }
@@ -265,22 +275,69 @@ function fencedVaultRead(version, hasFix) {
 
 function sha12(path) { return digest(readFileSync(path)).slice(7, 19) }
 
+// ---- fresh install helpers (a host with no predecessor Butler) -------------
+
+/** The root request for a fresh install: the bot comes from Telegram getMe on the new token, the owner from the installer. */
+export function freshInstallRequest({ epochId, botId, ownerId, pins }) {
+  if (!/^[1-9][0-9]*$/u.test(String(botId))) throw new Error("the bot id from Telegram is invalid")
+  if (!/^[1-9][0-9]*$/u.test(String(ownerId))) throw new Error("the owner's Telegram id must be a positive number")
+  return { schemaVersion: 1, epochId, botId: String(botId), ownerUserId: String(ownerId), ownerChatId: String(ownerId), ...pins, predecessorContract: "none" }
+}
+/** The bot id a Telegram getMe answer names, checked against the token's own prefix. */
+export function botIdFromGetMe(body, token) {
+  const id = body?.ok === true && Number.isSafeInteger(body.result?.id) ? String(body.result.id) : null
+  if (!id) throw new Error("Telegram did not accept the bot token (getMe failed)")
+  if (String(token).split(":")[0] !== id) throw new Error("the bot token does not belong to the bot Telegram names")
+  return id
+}
+/** The incoming request for an in-place upgrade: the same identity, new pins, and a fresh install's contract carried forward. */
+export function upgradeRequest(current, pins) {
+  return {
+    schemaVersion: 1, epochId: current.epochId, botId: current.botId, ownerUserId: current.ownerUserId, ownerChatId: current.ownerChatId, ...pins,
+    ...(current.predecessorContract === "none" ? { predecessorContract: "none" } : {}),
+  }
+}
+/** Whether a preserved file stayed as it was; one that was absent before had nothing to preserve. */
+export function unchanged(before, after) { return before === null || before === after }
+function containerExists(name) { return docker(["container", "ls", "--all", "--quiet", "--filter", `name=^/${name}$`]).trim() !== "" }
+/** Jellyfin's identity for the unchanged-check, or null on a host without Jellyfin (it must then stay absent). */
+function jellyfinState() {
+  return containerExists("jellyfin") ? docker(["inspect", "jellyfin", "--format", "{{.Id}}|{{.Image}}|{{.RestartCount}}|{{.State.StartedAt}}"]).trim() : null
+}
+function policyState() { return existsSync(POLICY) ? sha12(POLICY) : null }
+function installedRequest() { try { return JSON.parse(readFileSync(`${ROOT}/request.json`, "utf8")) } catch { return null } }
+
 // ---- prepare (idempotent staging; running Butler untouched) ---------------
 
-function prepare(version) {
-  say(`prepare inputs for ${version}`)
+async function prepare(version, { fresh = false, ownerId } = {}) {
+  say(`prepare inputs for ${version}${fresh ? " (fresh install)" : ""}`)
   const id = imageId(version)
   if (!id) fail(`image ${image(version)} is not present; pull it first`)
   if (existsSync(`${ROOT}/active.json`)) fail("an authority is installed; use `upgrade` (in place, no token rotation) instead of prepare/install")
+  let botId = null
+  if (fresh) {
+    if (containerExists(CONTAINER)) fail(`an ${CONTAINER} container already exists; a fresh install needs a host without one`)
+    const tokenPath = `${ROOT}/incoming-token`
+    if (!existsSync(tokenPath) || statSync(tokenPath).size === 0) fail(`no bot token at ${tokenPath}; the installer puts it there first`)
+    const token = readFileSync(tokenPath, "utf8").trim()
+    const body = await fetch(`https://api.telegram.org/bot${token}/getMe`).then((response) => response.json()).catch(() => null)
+    try { botId = botIdFromGetMe(body, token) } catch (error) { fail(error.message) }
+    ok(`Telegram knows the bot (id ${botId})`)
+  }
   const epochId = `${version.replace(/[^A-Za-z0-9_-]/g, "-")}-${new Date().toISOString().slice(0, 10).replace(/-/g, "")}`
   const manifestBytes = stageIncomingPackage(version)
   writePrivate(`${ROOT}/package-manifest.json`, manifestBytes)
-  const creds = JSON.parse(readFileSync(`/mnt/user/appdata/ouro-butler/runtime/container-credentials.json`, "utf8")).credentials[0].runtimeConfig
-  const request = {
-    schemaVersion: 1, epochId,
-    botId: String(creds.telegramBotToken).split(":")[0],
-    ownerUserId: String(creds.telegramAuthorizedUserId), ownerChatId: String(creds.telegramAuthorizedChatId),
-    ...packagePins(manifestBytes),
+  let request
+  if (fresh) {
+    try { request = freshInstallRequest({ epochId, botId, ownerId, pins: packagePins(manifestBytes) }) } catch (error) { fail(error.message) }
+  } else {
+    const creds = JSON.parse(readFileSync(`/mnt/user/appdata/ouro-butler/runtime/container-credentials.json`, "utf8")).credentials[0].runtimeConfig
+    request = {
+      schemaVersion: 1, epochId,
+      botId: String(creds.telegramBotToken).split(":")[0],
+      ownerUserId: String(creds.telegramAuthorizedUserId), ownerChatId: String(creds.telegramAuthorizedChatId),
+      ...packagePins(manifestBytes),
+    }
   }
   if (request.ownerUserId !== request.ownerChatId) fail("owner user and chat must match")
   writePrivate(`${ROOT}/request.json`, Buffer.from(JSON.stringify(request)))
@@ -290,7 +347,7 @@ function prepare(version) {
   verifyPackage(`${ROOT}/incoming-package`, `${ROOT}/package-manifest.json`, `${ROOT}/request.json`)
   ok("package verifies")
 
-  console.log("\nPREPARE done. Next: rotate the bot token into ${ROOT}/incoming-token, then install.".replace("${ROOT}", ROOT))
+  console.log(fresh ? "\nPREPARE done. Next: install." : "\nPREPARE done. Next: rotate the bot token into ${ROOT}/incoming-token, then install.".replace("${ROOT}", ROOT))
 }
 
 // The package digest plus the host primitive pins every request carries.
@@ -573,10 +630,16 @@ function migrateBundle(version, rollbackImage) {
   const pkgBundle = `${ROOT}/incoming-package/deploy/unraid/sanctuary.ouro`
   const migrate = `${ROOT}/incoming-package/deploy/unraid/migrate-sanctuary-bundle.mjs`
   if (!existsSync(`${pkgBundle}/provider-readiness.json`)) fail(`packaged bundle template missing provider-readiness.json at ${pkgBundle}`)
-  sh("/usr/local/bin/node", [migrate, "--package-root", pkgBundle, "--agent-root", BUNDLE, "--operation", "migrate",
-    "--rollback-image-id", rollbackImage, "--target-image-id", imageId(version)])
-  ok("bundle migrated (rollback retained)")
-  sh("/usr/local/bin/node", [migrate, "--package-root", pkgBundle, "--agent-root", BUNDLE, "--operation", "commit"])
+  if (rollbackImage === null) {
+    // A fresh install has no earlier image to roll back to: write the packaged files with no rollback record.
+    sh("/usr/local/bin/node", [migrate, "--package-root", pkgBundle, "--agent-root", BUNDLE, "--operation", "seed"])
+    ok("bundle seeded from the package (fresh install)")
+  } else {
+    sh("/usr/local/bin/node", [migrate, "--package-root", pkgBundle, "--agent-root", BUNDLE, "--operation", "migrate",
+      "--rollback-image-id", rollbackImage, "--target-image-id", imageId(version)])
+    ok("bundle migrated (rollback retained)")
+    sh("/usr/local/bin/node", [migrate, "--package-root", pkgBundle, "--agent-root", BUNDLE, "--operation", "commit"])
+  }
   // migrate/commit ran as root; the resident owns its bundle as uid 10001, so restore ownership
   sh("/bin/chown", ["-R", "10001:10001", BUNDLE])
   restoreReplayRoot()
@@ -760,6 +823,7 @@ function install(version) {
   if (!existsSync(`${ROOT}/incoming-token`) || statSync(`${ROOT}/incoming-token`).size === 0) fail(`no rotated token at ${ROOT}/incoming-token — rotate it in BotFather first`)
   if (existsSync(JOURNAL)) fail("a template transaction is already pending; resolve it first")
   if (targetHasVaultFix(version) === false) fail(`${version} lacks the D-018 fenced-read fix; the install would strand Telegram (run preflight)`)
+  const fresh = installedRequest()?.predecessorContract === "none"
 
   // Clear stale authority runtime dirs from a prior failed attempt so #runtimeDirectories
   // starts clean (it skips a dir that already exists). Safe only when no authority is live
@@ -773,11 +837,12 @@ function install(version) {
     ok("cleared stale authority runtime dirs (cgroup/staging/socket/epochs) and any leaked gateway")
   }
   const targetImage = imageId(version)
-  const rollbackImage = docker(["inspect", CONTAINER, "--format", "{{.Image}}"]).trim()
+  if (fresh && containerExists(CONTAINER)) fail(`an ${CONTAINER} container already exists; a fresh install needs a host without one`)
+  const rollbackImage = fresh ? null : docker(["inspect", CONTAINER, "--format", "{{.Image}}"]).trim()
   if (!targetImage || targetImage === rollbackImage) fail("target/rollback image identity invalid")
-  const jellyfinBefore = docker(["inspect", "jellyfin", "--format", "{{.Id}}|{{.Image}}|{{.RestartCount}}|{{.State.StartedAt}}"]).trim()
-  const policyBefore = existsSync(POLICY) ? sha12(POLICY) : fail(`steward policy missing`)
-  ok(`target ${targetImage.slice(0,19)}… rollback ${rollbackImage.slice(0,19)}… policy ${policyBefore}`)
+  const jellyfinBefore = jellyfinState()
+  const policyBefore = fresh ? policyState() : policyState() ?? fail(`steward policy missing`)
+  ok(`target ${targetImage.slice(0,19)}… rollback ${rollbackImage ? `${rollbackImage.slice(0,19)}…` : "none (fresh install)"} policy ${policyBefore ?? "none yet"}`)
 
   const srcTemplate = `${ROOT}/source-template.xml`
   sh("/usr/bin/install", ["-m", "600", "-o", "0", "-g", "0", `${incoming}/deploy/unraid/sanctuary.xml`, srcTemplate])
@@ -787,7 +852,7 @@ function install(version) {
   try {
     say("transaction: prepare -> authority-install -> authority-activate -> commit")
     tx("prepare", ["--source-template", srcTemplate, "--version-tag", image(version),
-      "--manifest-digest", manifestDigest, "--rollback-image-id", rollbackImage, "--target-image-id", targetImage])
+      "--manifest-digest", manifestDigest, "--rollback-image-id", rollbackImage ?? "none", "--target-image-id", targetImage])
     ok("prepared")
     tx("authority-install"); ok("authority installed (gateway up)")
     recreateResident(version)
@@ -800,14 +865,17 @@ function install(version) {
   } catch (e) {
     resumeCgroupReaper()
     console.log(`\n!! install failed:\n${e.message}\n!! auto-rolling back so the Butler is not left down`)
+    if (fresh) {
+      freshRollback()
+      fail("fresh install rolled back; nothing is left running. Fix the error above, then run prepare --fresh and install again.")
+    }
     autoRollback(rollbackImage, version)
     fail("install rolled back; the Butler is on its prior version. See output above.")
   }
 
   say("preservation")
-  const jellyfinAfter = docker(["inspect", "jellyfin", "--format", "{{.Id}}|{{.Image}}|{{.RestartCount}}|{{.State.StartedAt}}"]).trim()
-  jellyfinBefore === jellyfinAfter ? ok("jellyfin unchanged") : fail("JELLYFIN CHANGED")
-  sha12(POLICY) === policyBefore ? ok("steward policy unchanged") : fail("STEWARD POLICY CHANGED")
+  jellyfinState() === jellyfinBefore ? ok(jellyfinBefore ? "jellyfin unchanged" : "no jellyfin, as before") : fail("JELLYFIN CHANGED")
+  unchanged(policyBefore, policyState()) ? ok(policyBefore ? "steward policy unchanged" : "no steward policy before install") : fail("STEWARD POLICY CHANGED")
   console.log(`\nINSTALL done — ${version} live. Run verify.`)
 }
 
@@ -823,6 +891,17 @@ function killLeakedGateway() {
   } catch { /* best effort */ }
 }
 
+// A fresh install rolls back to nothing: the authority retires and removes the resident it created, the template
+// transaction removes the template it wrote, and nothing is restarted because nothing ran before.
+function freshRollback() {
+  for (const op of ["authority-retire", "authority-restore", "rollback"]) {
+    try { tx(op) } catch (e) { console.log(`   ${op}: ${String(e.message).split("\n")[0]}`) }
+  }
+  killLeakedGateway()
+  try { if (containerExists(CONTAINER)) docker(["rm", "-f", CONTAINER]) } catch (e) { console.log(`   remove ${CONTAINER}: ${String(e.message).split("\n")[0]}`) }
+  console.log(containerExists(CONTAINER) ? `   ${CONTAINER} is still present — remove it by hand before retrying` : "   rollback complete — no Butler container is left behind")
+}
+
 function autoRollback(rollbackImage, version) {
   try { tx("authority-retire") } catch (e) { console.log(`   authority-retire: ${String(e.message).split("\n")[0]}`) }
   try { tx("authority-restore") } catch (e) { console.log(`   authority-restore: ${String(e.message).split("\n")[0]}`) }
@@ -1119,22 +1198,22 @@ async function upgrade(version, rehearse, { noGate = false, plant } = {}) {
   if (!id) { docker(["pull", image(version)]); id = imageId(version) }
   if (!id) fail(`image ${image(version)} could not be pulled`)
   ok(`image ${id.slice(0, 19)}…`)
+  const current = JSON.parse(readFileSync(`${ROOT}/request.json`, "utf8"))
   if (existsSync(UPGRADE_JOURNAL)) console.log("  note: resuming the pending in-place upgrade with its staged package")
   else {
-    const current = JSON.parse(readFileSync(`${ROOT}/request.json`, "utf8"))
     const manifestBytes = stageIncomingPackage(version)
     const pkgVersion = JSON.parse(readFileSync(`${ROOT}/incoming-package/deploy/unraid/sanctuary.ouro/bundle-meta.json`, "utf8")).runtimeVersion
     if (pkgVersion !== version) fail(`staged package is ${pkgVersion}, not ${version}`)
     writePrivate(INCOMING_MANIFEST, manifestBytes)
-    const request = { schemaVersion: 1, epochId: current.epochId, botId: current.botId, ownerUserId: current.ownerUserId, ownerChatId: current.ownerChatId, ...packagePins(manifestBytes) }
+    const request = upgradeRequest(current, packagePins(manifestBytes))
     writePrivate(INCOMING_REQUEST, Buffer.from(JSON.stringify(request)))
     verifyPackage(`${ROOT}/incoming-package`, INCOMING_MANIFEST, INCOMING_REQUEST)
     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")
+  const jellyfinBefore = jellyfinState()
+  const policyBefore = current.predecessorContract === "none" ? policyState() : policyState() ?? fail("steward policy missing")
   const telegram = await checkTelegramBeforePause({ journalExists: existsSync(UPGRADE_JOURNAL) })
   if (!telegram.ok) fail(`api.telegram.org is not reachable from this host (${telegram.detail}); the new gateway could not pass its Telegram identity check. Nothing was paused or changed; fix the network and re-run.`)
   if (telegram.skipped) console.log("  note: resuming a pending upgrade; Telegram reachability not re-checked")
@@ -1158,9 +1237,9 @@ async function upgrade(version, rehearse, { noGate = false, plant } = {}) {
   if (!gated || failure) resumeSupervision()
   say("preservation")
   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 jellyfinNow = jellyfinState()
+  jellyfinNow === jellyfinBefore ? ok(jellyfinBefore ? "jellyfin unchanged" : "no jellyfin, as before") : (gated && !failure ? (bad("JELLYFIN CHANGED"), preserved.push("jellyfin changed")) : fail("JELLYFIN CHANGED"))
+  unchanged(policyBefore, policyState()) ? 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)")
@@ -1212,7 +1291,7 @@ function verify(withGate = false) {
   ok(`butler: ${st}`)
   const auth = docker(["logs", CONTAINER, "--since", "2m"], { stdio: ["ignore","pipe","pipe"] }).split("\n").filter((l) => l.includes("401")).length
   auth === 0 ? ok("no Telegram auth failures in the last 2m") : bad(`${auth} 401s in the last 2m`)
-  existsSync(POLICY) ? ok(`steward policy ${sha12(POLICY)}`) : bad("steward policy missing")
+  existsSync(POLICY) ? ok(`steward policy ${sha12(POLICY)}`) : installedRequest()?.predecessorContract === "none" ? ok("no steward policy yet") : bad("steward policy missing")
   const psycheMount = JSON.parse(docker(["inspect", CONTAINER, "--format", "{{json .Mounts}}"]) || "[]")
   psycheMountIssue(psycheMount) === null ? ok("psyche is mounted read-only in the resident") : bad(psycheMountIssue(psycheMount))
   const trustMount = JSON.parse(docker(["inspect", CONTAINER, "--format", "{{json .Mounts}}"]) || "[]")
@@ -1226,8 +1305,7 @@ function verify(withGate = false) {
     const psycheIssues = psycheProblems(psycheDir)
     psycheIssues.length === 0 ? ok("psyche files are resident-owned 0600 (read-only through the mount)") : bad(`psyche files do not match what the resident boot check requires: ${psycheIssues.slice(0, 3).join("; ")}`)
   } else bad("psyche folder missing from the bundle")
-  const jf = docker(["inspect", "jellyfin", "--format", "{{.State.Status}} restarts={{.RestartCount}}"]).trim()
-  ok(`jellyfin ${jf}`)
+  ok(containerExists("jellyfin") ? `jellyfin ${docker(["inspect", "jellyfin", "--format", "{{.State.Status}} restarts={{.RestartCount}}"]).trim()}` : "no jellyfin container")
   if (withGate) {
     say("replay gate (live version, no upgrade)")
     const gate = runReplayGate(undefined)
@@ -1241,21 +1319,25 @@ function fail(m) { console.error(`\nREFUSING: ${m}`); process.exit(1) }
 // ---- entry ----------------------------------------------------------------
 
 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 usage = "Usage: sanctuary-butler-upgrade.mjs <preflight|prepare|install|upgrade> <version> [--rehearse <step>] [--no-gate] [--plant <case>] | preflight <version> --fresh | prepare <version> --fresh --owner-id <id> | 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 }
+  const parsed = { phase, version: undefined, rehearse: undefined, noGate: false, plant: undefined, gate: false, fresh: false, ownerId: undefined }
   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 === "--fresh" && (phase === "preflight" || phase === "prepare")) parsed.fresh = true
+    else if (arg === "--owner-id" && phase === "prepare" && rest[i + 1]) parsed.ownerId = rest[++i]
     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 === "prepare" && parsed.fresh !== (parsed.ownerId !== undefined)) throw new Error("prepare --fresh needs --owner-id <the owner's Telegram user id>, and --owner-id needs --fresh")
+  if (parsed.ownerId !== undefined && !/^[1-9][0-9]*$/u.test(parsed.ownerId)) throw new Error("--owner-id must be a Telegram user id (a positive number)")
   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
 }
@@ -1264,8 +1346,8 @@ async 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)
+  if (args.phase === "preflight") preflight(args.version, { fresh: args.fresh })
+  else if (args.phase === "prepare") await prepare(args.version, { fresh: args.fresh, ownerId: args.ownerId })
   else if (args.phase === "install") install(args.version)
   else if (args.phase === "verify") verify(args.gate)
   else if (args.phase === "upgrade") await upgrade(args.version, args.rehearse, { noGate: args.noGate, plant: args.plant })

package/deploy/unraid/sanctuary.ouro/agent.json

@@ -2,12 +2,12 @@
   "version": 2,
   "enabled": true,
   "humanFacing": {
-    "provider": "minimax",
-    "model": "MiniMax-M3"
+    "provider": "anthropic",
+    "model": "claude-opus-5-5"
   },
   "agentFacing": {
-    "provider": "minimax",
-    "model": "MiniMax-M3"
+    "provider": "anthropic",
+    "model": "claude-sonnet-5-5"
   },
   "context": {
     "maxTokens": 80000,

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

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.970",
+  "runtimeVersion": "0.1.0-alpha.971",
   "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.970</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.971</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/heart/daemon/cli-exec.js

@@ -2215,10 +2215,13 @@ async function executeVaultStatus(command, deps) {
 }
 const RUNTIME_CONFIG_KEY_SEGMENT = /^[A-Za-z][A-Za-z0-9_-]*$/;
 const FORBIDDEN_RUNTIME_CONFIG_KEY_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+// The Sanctuary runtime reads these machine credentials at the top level of the config (sanctuary-runtime.ts); every
+// other key is a dotted path, so a mistyped key cannot replace a whole section with a string.
+const TOP_LEVEL_RUNTIME_CONFIG_KEYS = new Set(["unraidGraphqlUrl", "unraidReadApiKey", "unraidWriteApiKey", "sabnzbdApiKey"]);
 function parseRuntimeConfigKey(key) {
     const segments = key.split(".").map((segment) => segment.trim()).filter(Boolean);
-    if (segments.length < 2) {
-        throw new Error("runtime config key must be a dotted path such as bluebubbles.password");
+    if (segments.length < 2 && !(segments.length === 1 && TOP_LEVEL_RUNTIME_CONFIG_KEYS.has(segments[0]))) {
+        throw new Error(`runtime config key must be a dotted path such as bluebubbles.password, or one of ${[...TOP_LEVEL_RUNTIME_CONFIG_KEYS].join(", ")}`);
     }
     for (const segment of segments) {
         if (!RUNTIME_CONFIG_KEY_SEGMENT.test(segment) || FORBIDDEN_RUNTIME_CONFIG_KEY_SEGMENTS.has(segment)) {
@@ -2353,6 +2356,9 @@ async function withCliTimeout(timeoutMs, label, run) {
 async function promptRuntimeConfigValue(command, deps) {
     if (command.value !== undefined)
         return command.value;
+    // A file (or /dev/stdin) keeps a secret out of argv, so a script can store one without a terminal.
+    if (command.valueFile !== undefined)
+        return readSecretValueFile("--value-file", command.valueFile);
     if (isSensitiveRuntimeConfigKey(command.key)) {
         if (!deps.promptSecret) {
             throw new Error("secret entry requires an interactive terminal so the value can be hidden. Re-run without --value in a terminal, or pass --value only from a trusted non-logged script.");
@@ -5648,21 +5654,22 @@ async function executeProviderRefresh(command, deps) {
     deps.writeStdout(message);
     return message;
 }
-/** Reads an API key from a file (or /dev/stdin) so it never appears in argv. */
-function readApiKeyFile(filePath) {
+/** Reads a secret from a file (or /dev/stdin) so it never appears in argv. */
+function readSecretValueFile(flag, filePath) {
     let raw;
     try {
         raw = fs.readFileSync(filePath, "utf8");
     }
     catch (error) {
         /* v8 ignore next -- fs.readFileSync only throws Error objects @preserve */
-        throw new Error(`could not read --api-key-file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`could not read ${flag} ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
     }
-    const key = raw.trim();
-    if (!key)
-        throw new Error(`--api-key-file ${filePath} is empty.`);
-    return key;
+    const value = raw.trim();
+    if (!value)
+        throw new Error(`${flag} ${filePath} is empty.`);
+    return value;
 }
+function readApiKeyFile(filePath) { return readSecretValueFile("--api-key-file", filePath); }
 async function executeAuthRun(command, deps) {
     const provider = command.provider ?? (0, auth_flow_1.readAgentConfigForAgent)(command.agent, deps.bundlesRoot).config.humanFacing.provider;
     const apiKey = command.apiKeyFile ? readApiKeyFile(command.apiKeyFile) : undefined;

package/dist/heart/daemon/cli-help.js

@@ -626,7 +626,7 @@ const SUBCOMMAND_HELP = {
     },
     "vault config set": {
         description: "Write runtime configuration into the agent credential vault without printing values",
-        usage: "ouro vault config set [--agent <name>] --key <path> [--value <value>] [--scope agent|machine]",
+        usage: "ouro vault config set [--agent <name>] --key <path> [--value <value> | --value-file <path>] [--scope agent|machine]",
         example: "ouro vault config set --key teams.clientSecret",
     },
     "vault config status": {

package/dist/heart/daemon/cli-parse.js

@@ -265,7 +265,7 @@ function usage() {
         "  ouro vault recover [--agent <name>] --from <json> [--from <json>] [--email <email>] [--server <url>] [--store <store>]",
         "  ouro vault unlock [--agent <name>] [--store auto|macos-keychain|windows-dpapi|linux-secret-service|plaintext-file]",
         "  ouro vault status [--agent <name>] [--store auto|macos-keychain|windows-dpapi|linux-secret-service|plaintext-file]",
-        "  ouro vault config set [--agent <name>] --key <path> [--value <value>] [--scope agent|machine]",
+        "  ouro vault config set [--agent <name>] --key <path> [--value <value> | --value-file <path>] [--scope agent|machine]",
         "  ouro vault config status [--agent <name>] [--scope agent|machine|all]",
         "  ouro vault item set [--agent <name>] --item <path> --secret-field <name> [--public-field <key=value>] [--note <text>]",
         "  ouro vault item status [--agent <name>] --item <path>",
@@ -1173,9 +1173,15 @@ function parseVaultConfigCommand(args) {
     const { agent, rest } = extractAgentFlag(args.slice(1));
     let key;
     let value;
+    let valueFile;
     let scope;
     for (let i = 0; i < rest.length; i += 1) {
         const token = rest[i];
+        if (token === "--value-file") {
+            valueFile = rest[i + 1] ?? "";
+            i += 1;
+            continue;
+        }
         if (token === "--key") {
             key = rest[i + 1];
             i += 1;
@@ -1201,7 +1207,7 @@ function parseVaultConfigCommand(args) {
         throw new Error("Usage: ouro vault config set [--agent <name>] --key <path> [--value <value>] OR ouro vault config status [--agent <name>]");
     }
     if (sub === "status") {
-        if (key || value) {
+        if (key || value || valueFile) {
             throw new Error("Usage: ouro vault config status [--agent <name>]");
         }
         return { kind: "vault.config.status", ...(agent ? { agent } : {}), ...(scope ? { scope } : {}) };
@@ -1209,9 +1215,13 @@ function parseVaultConfigCommand(args) {
     if (scope === "all")
         throw new Error("vault config --scope all is only valid for status");
     if (!key) {
-        throw new Error("Usage: ouro vault config set [--agent <name>] --key <path> [--value <value>]");
+        throw new Error("Usage: ouro vault config set [--agent <name>] --key <path> [--value <value> | --value-file <path>]");
     }
-    return { kind: "vault.config.set", ...(agent ? { agent } : {}), key, ...(value !== undefined ? { value } : {}), ...(scope ? { scope } : {}) };
+    if (value !== undefined && valueFile !== undefined)
+        throw new Error("vault config set takes --value or --value-file, not both");
+    if (valueFile !== undefined && !valueFile)
+        throw new Error("vault config set --value-file needs a path (use /dev/stdin to pipe the value)");
+    return { kind: "vault.config.set", ...(agent ? { agent } : {}), key, ...(value !== undefined ? { value } : {}), ...(valueFile !== undefined ? { valueFile } : {}), ...(scope ? { scope } : {}) };
 }
 function normalizeConnectTarget(value) {
     if (!value)

package/dist/heart/daemon/sanctuary-authority-epoch.js

@@ -81,9 +81,12 @@ function validate(value) {
         || typeof epoch.epochId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/u.test(epoch.epochId)
         || ![epoch.botId, epoch.ownerUserId, epoch.ownerChatId].every((id) => typeof id === "string" && /^[1-9][0-9]*$/u.test(id)) || epoch.ownerUserId !== epoch.ownerChatId
         || !Number.isSafeInteger(epoch.predecessorCursor) || epoch.predecessorCursor < 0
-        || ![epoch.packageDigest, epoch.tokenDigest, epoch.previousTokenDigest, epoch.publicKeyDigest].every((value) => typeof value === "string" && DIGEST.test(value))
+        || ![epoch.packageDigest, epoch.tokenDigest, epoch.publicKeyDigest].every((value) => typeof value === "string" && DIGEST.test(value))
+        || (epoch.previousTokenDigest === null
+            ? epoch.revokedTokenStatus !== null || epoch.predecessorCursor !== 0
+            : typeof epoch.previousTokenDigest !== "string" || !DIGEST.test(epoch.previousTokenDigest) || epoch.revokedTokenStatus !== 401)
         || epoch.tokenDigest === epoch.previousTokenDigest || typeof epoch.tokenPath !== "string" || !path.isAbsolute(epoch.tokenPath)
-        || typeof epoch.publicKeyPem !== "string" || epoch.revokedTokenStatus !== 401
+        || typeof epoch.publicKeyPem !== "string"
         || typeof epoch.createdAt !== "string" || !Number.isFinite(Date.parse(epoch.createdAt)) || new Date(epoch.createdAt).toISOString() !== epoch.createdAt
         || (epoch.state === "prepared" ? epoch.terminalCursor !== null : !Number.isSafeInteger(epoch.terminalCursor) || epoch.terminalCursor < epoch.predecessorCursor))
         throw new Error("Sanctuary authority epoch is invalid");
@@ -154,19 +157,26 @@ async function prepareSanctuaryAuthorityEpoch(input, options) {
         || !Number.isSafeInteger(input.predecessorCursor) || input.predecessorCursor < 0 || !DIGEST.test(input.packageDigest))
         throw new Error("Sanctuary authority epoch input is invalid");
     const token = privateBytes(input.tokenPath, options).toString("utf8").trim();
-    const previousToken = privateBytes(input.previousTokenPath, options).toString("utf8").trim();
-    if (!TOKEN.test(token) || !TOKEN.test(previousToken) || token.split(":")[0] !== input.botId || previousToken.split(":")[0] !== input.botId || token === previousToken)
+    // A fresh install has no predecessor token to prove revoked, and therefore no cursor to carry.
+    const previousToken = input.previousTokenPath === null ? null : privateBytes(input.previousTokenPath, options).toString("utf8").trim();
+    if (previousToken === null && input.predecessorCursor !== 0)
+        throw new Error("Sanctuary authority epoch input is invalid");
+    if (!TOKEN.test(token) || token.split(":")[0] !== input.botId
+        || (previousToken !== null && (!TOKEN.test(previousToken) || previousToken.split(":")[0] !== input.botId || token === previousToken)))
         throw new Error("Sanctuary authority requires a fresh same-bot token");
-    const previous = await options.probe(previousToken);
-    if (previous.status !== 401 || previous.botId !== null)
-        throw new Error("Sanctuary previous Telegram token is not proven revoked");
+    if (previousToken !== null) {
+        const previous = await options.probe(previousToken);
+        if (previous.status !== 401 || previous.botId !== null)
+            throw new Error("Sanctuary previous Telegram token is not proven revoked");
+    }
     const current = await options.probe(token);
     if (current.status !== 200 || current.botId !== input.botId)
         throw new Error("Sanctuary new Telegram token identity is invalid");
     const epochPath = path.join(input.root, "epoch.json");
     const keyPath = path.join(input.root, "issuer.pem");
     const intentPath = path.join(input.root, "issuer-intent.json");
-    const inputDigest = sha(JSON.stringify({ ...input, tokenDigest: sha(token), previousTokenDigest: sha(previousToken) }));
+    const previousTokenDigest = previousToken === null ? null : sha(previousToken);
+    const inputDigest = sha(JSON.stringify({ ...input, tokenDigest: sha(token), previousTokenDigest }));
     return (0, session_transaction_1.withImmediateSessionTurnLease)(epochPath, (lease) => {
         const transaction = (0, session_transaction_1.readSessionTransaction)(epochPath, lease);
         let existing = false;
@@ -186,7 +196,7 @@ async function prepareSanctuaryAuthorityEpoch(input, options) {
                 if (epoch[key] !== input[key])
                     throw new Error("Sanctuary authority epoch input changed");
             }
-            if (epoch.previousTokenDigest !== sha(previousToken))
+            if (epoch.previousTokenDigest !== previousTokenDigest)
                 throw new Error("Sanctuary authority predecessor token changed");
             if (fs.existsSync(intentPath)) {
                 const intent = JSON.parse(privateBytes(intentPath, options).toString("utf8"));
@@ -218,8 +228,8 @@ async function prepareSanctuaryAuthorityEpoch(input, options) {
         }
         const epoch = validate({
             schemaVersion: 1, state: "prepared", epochId: input.epochId, botId: input.botId, ownerUserId: input.ownerUserId, ownerChatId: input.ownerChatId,
-            predecessorCursor: input.predecessorCursor, packageDigest: input.packageDigest, tokenPath: input.tokenPath, tokenDigest: sha(token), previousTokenDigest: sha(previousToken),
-            ...issuer(input.root, options), revokedTokenStatus: 401, createdAt: intent.createdAt, terminalCursor: null,
+            predecessorCursor: input.predecessorCursor, packageDigest: input.packageDigest, tokenPath: input.tokenPath, tokenDigest: sha(token), previousTokenDigest,
+            ...issuer(input.root, options), revokedTokenStatus: previousTokenDigest === null ? null : 401, createdAt: intent.createdAt, terminalCursor: null,
         });
         (0, session_transaction_1.writeSessionTransaction)(epochPath, epoch, { lease, expectedRevision: transaction.revision });
         fs.unlinkSync(intentPath);

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

@@ -103,7 +103,10 @@ const EPOCH_RECORDS = ["migration.json", "stage.json", "configured.json"];
 const digest = (value) => `sha256:${(0, node_crypto_1.createHash)("sha256").update(value).digest("hex")}`;
 function validateRequest(value) {
     const request = value;
-    if (!request || typeof request !== "object" || Object.keys(request).sort().join(",") !== "botId,epochId,nodeDigest,ownerChatId,ownerUserId,packageDigest,prlimitDigest,schemaVersion,setsidDigest,shellDigest"
+    const keys = "botId,epochId,nodeDigest,ownerChatId,ownerUserId,packageDigest,prlimitDigest,schemaVersion,setsidDigest,shellDigest";
+    if (!request || typeof request !== "object"
+        || Object.keys(request).filter((key) => key !== "predecessorContract").sort().join(",") !== keys
+        || (Object.hasOwn(request, "predecessorContract") && request.predecessorContract !== "none")
         || request.schemaVersion !== 1 || !/^[A-Za-z0-9_-]{1,128}$/u.test(request.epochId)
         || ![request.botId, request.ownerUserId, request.ownerChatId].every((id) => typeof id === "string" && /^[1-9][0-9]*$/u.test(id))
         || request.ownerUserId !== request.ownerChatId
@@ -128,17 +131,20 @@ class SanctuaryAuthorityRootLifecycle {
         this.#socketGid = options.socketGroupId ?? 10001;
         if (process.getuid() !== this.#uid || process.getgid() !== this.#gid)
             throw new Error("Sanctuary root lifecycle requires root");
-        if (!DIGEST.test(transaction.targetImageId) || !DIGEST.test(transaction.rollbackImageId) || transaction.targetImageId === transaction.rollbackImageId)
-            throw new Error("Sanctuary root lifecycle image identity is invalid");
-        this.#transaction = { targetImageId: transaction.targetImageId, rollbackImageId: transaction.rollbackImageId };
         this.#directory(ROOT);
         this.#request = validateRequest(JSON.parse(this.#private(`${ROOT}/request.json`)));
+        const rollbackValid = transaction.rollbackImageId === null ? this.#fresh() : DIGEST.test(transaction.rollbackImageId);
+        if (!DIGEST.test(transaction.targetImageId) || !rollbackValid || transaction.targetImageId === transaction.rollbackImageId)
+            throw new Error("Sanctuary root lifecycle image identity is invalid");
+        this.#transaction = { targetImageId: transaction.targetImageId, rollbackImageId: transaction.rollbackImageId };
         (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_root_lifecycle_loaded", message: "Sanctuary root lifecycle identity loaded", meta: { epochId: this.#request.epochId, targetImageId: transaction.targetImageId } });
     }
     plan() {
         const { epochId, botId, ownerUserId, ownerChatId, packageDigest } = this.#request;
-        return { schemaVersion: 1, epochId, botId, ownerUserId, ownerChatId, packageDigest, publicKeyDigest: null, predecessorContract: "canonical-pre-gateway", targetContract: "canonical-gateway" };
+        return { schemaVersion: 1, epochId, botId, ownerUserId, ownerChatId, packageDigest, publicKeyDigest: null, predecessorContract: this.#fresh() ? "none" : "canonical-pre-gateway", targetContract: "canonical-gateway" };
     }
+    /** Whether this is a fresh install, which hands over nothing from a predecessor. */
+    #fresh() { return this.#request.predecessorContract === "none"; }
     async boot() {
         if (!fs.existsSync(this.#p(`${ROOT}/activation.json`)))
             return false;
@@ -212,9 +218,15 @@ class SanctuaryAuthorityRootLifecycle {
             "rollback:reconcile-executions": { read: () => this.#retiredProcess(), apply: () => this.#retireProcess() },
             "rollback:stop-gateway": { read: () => this.#retiredProcess() && this.#pid() === null, apply: () => this.#stopGateway() },
             "rollback:end-epoch": { read: () => this.#epoch().state === "retired", apply: () => this.#endEpoch() },
-            "rollback:restore-token-cursor": { read: () => this.#restoredToken(), apply: () => this.#restoreToken() },
-            "rollback:restore-resident": { read: () => this.#rollback().State.Running, apply: () => this.#restoreResident() },
-            "rollback:verify-rollback": { read: () => this.#rollbackVerified(), apply: () => this.#verifyRollback() },
+            "rollback:restore-token-cursor": this.#fresh()
+                ? { read: () => this.#epoch().state === "retired", apply: () => this.#requireStopped() }
+                : { read: () => this.#restoredToken(), apply: () => this.#restoreToken() },
+            "rollback:restore-resident": this.#fresh()
+                ? { read: () => this.#residentAbsent(), apply: () => this.#removeResident() }
+                : { read: () => this.#rollback().State.Running, apply: () => this.#restoreResident() },
+            "rollback:verify-rollback": this.#fresh()
+                ? { read: () => fs.existsSync(this.#p(`${this.#epochRoot()}/rollback.json`)) && this.#freshRollbackClean(), apply: () => this.#verifyFreshRollback() }
+                : { read: () => this.#rollbackVerified(), apply: () => this.#verifyRollback() },
         };
         const effect = effects[step];
         if (!effect)
@@ -248,6 +260,13 @@ class SanctuaryAuthorityRootLifecycle {
             this.#migration();
             return;
         }
+        if (this.#fresh()) {
+            // A fresh install starts from nothing: an installed authority here means this is not one.
+            if (fs.existsSync(this.#p(`${ROOT}/active.json`)) || fs.existsSync(this.#p(`${ROOT}/activation.json`)))
+                throw new Error("Sanctuary fresh install found an installed authority");
+            this.#write(`${this.#epochRoot()}/migration.json`, JSON.stringify({ ...this.plan(), ...this.#transaction, predecessorCursor: 0 }));
+            return;
+        }
         if (fs.existsSync(this.#p(`${ROOT}/active.json`))) {
             const previous = JSON.parse(this.#private(`${ROOT}/active.json`));
             const epoch = (0, sanctuary_authority_epoch_1.readSanctuaryAuthorityEpoch)(previous.epochRoot, { expectedUid: this.#uid, expectedGid: this.#gid });
@@ -430,7 +449,7 @@ class SanctuaryAuthorityRootLifecycle {
         this.#write(`${this.#epochRoot()}/current-token`, token);
         await (0, sanctuary_authority_epoch_1.prepareSanctuaryAuthorityEpoch)({
             root: this.#p(this.#epochRoot()), epochId: this.#request.epochId, tokenPath: this.#p(`${this.#epochRoot()}/current-token`),
-            previousTokenPath: this.#p(`${this.#epochRoot()}/previous-token`), botId: this.#request.botId,
+            previousTokenPath: this.#fresh() ? null : this.#p(`${this.#epochRoot()}/previous-token`), botId: this.#request.botId,
             ownerUserId: this.#request.ownerUserId, ownerChatId: this.#request.ownerChatId,
             predecessorCursor: this.#migration().predecessorCursor, packageDigest: this.#request.packageDigest,
         }, {
@@ -781,6 +800,29 @@ class SanctuaryAuthorityRootLifecycle {
             this.#docker(["start", "ouro-butler"]);
         await this.#wait(() => this.#rollback().State.Health?.Status === "healthy" && this.#rollback().State.Running);
     }
+    // A fresh install rolls back to nothing: its token stays in root custody for a retry,
+    // and the resident it created is removed rather than restored.
+    #residentAbsent() {
+        return !this.#containers().some((container) => container.Name === "/ouro-butler");
+    }
+    #removeResident() {
+        this.#assertNoForeignPoller();
+        if (this.#epoch().state !== "retired" || this.#pid() !== null)
+            throw new Error("Sanctuary epoch must retire before the fresh resident is removed");
+        const resident = this.#containers().find((container) => container.Name === "/ouro-butler");
+        if (resident && resident.Image !== this.#transaction.targetImageId)
+            throw new Error("Sanctuary resident image changed");
+        if (resident)
+            this.#docker(["rm", "--force", "ouro-butler"]);
+    }
+    #freshRollbackClean() {
+        return this.#epoch().state === "retired" && this.#pid() === null && this.#residentAbsent();
+    }
+    #verifyFreshRollback() {
+        if (!this.#freshRollbackClean())
+            throw new Error("Sanctuary rollback readback failed");
+        this.#write(`${this.#epochRoot()}/rollback.json`, JSON.stringify({ epochId: this.#request.epochId, state: "retired" }));
+    }
     #rollbackVerified() {
         return fs.existsSync(this.#p(`${this.#epochRoot()}/rollback.json`)) && this.#restoredToken() && this.#pid() === null && this.#rollback().State.Running && this.#rollback().State.Health?.Status === "healthy";
     }
@@ -889,7 +931,7 @@ class SanctuaryAuthorityRootLifecycle {
             || !journal.completed.every((step) => exports.SANCTUARY_UPGRADE_STEPS.includes(step))
             || (journal.rollingBack !== undefined && journal.rollingBack !== true)
             || !sides.every((side) => side && DIGEST.test(side.imageId) && DIGEST.test(side.packageDigest) && IMAGE_REFERENCE.test(side.imageReference))
-            || !DIGEST.test(journal.from.rollbackImageId))
+            || !(journal.from.rollbackImageId === null ? this.#fresh() : DIGEST.test(journal.from.rollbackImageId)))
             throw new Error("Sanctuary upgrade journal is invalid");
         return journal;
     }
@@ -901,7 +943,7 @@ class SanctuaryAuthorityRootLifecycle {
         if (this.#docker(["image", "inspect", "--format", "{{.Id}}", input.imageReference]).trim() !== input.targetImageId)
             throw new Error("Sanctuary upgrade image identity does not match its reference");
         const request = validateRequest(JSON.parse(this.#private(INCOMING_REQUEST)));
-        if (["epochId", "botId", "ownerUserId", "ownerChatId"].some((key) => request[key] !== this.#request[key]))
+        if (["epochId", "botId", "ownerUserId", "ownerChatId", "predecessorContract"].some((key) => request[key] !== this.#request[key]))
             throw new Error("Sanctuary upgrade would change the authority identity");
         if (request.packageDigest === this.#request.packageDigest)
             throw new Error("Sanctuary upgrade package is already installed");

package/npm-shrinkwrap.json

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