@ouro.bot/cli 0.1.0-alpha.815 → 0.1.0-alpha.817

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

@@ -19,6 +19,8 @@ const CONTAINER_ID = /^[0-9a-f]{64}$/u
 const VERSION_TAG = /^ghcr\.io\/ourostack\/ouroboros-butler:[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/u
 const JELLYFIN_STATES = new Set(["created", "running", "paused", "restarting", "removing", "exited", "dead"])
 const JELLYFIN_FORMAT = '{"name":{{json .Name}},"containerId":{{json .Id}},"imageId":{{json .Image}},"state":{{json .State.Status}},"restartCount":{{json .RestartCount}}}'
+const AUTHORITY_INSTALL_STEPS = ["freeze-resident", "stage-authority", "verify-token-rotation", "transfer-cursor", "remove-resident-token", "start-gateway", "configure-resident", "start-resident", "verify-install"]
+const AUTHORITY_ROLLBACK_STEPS = ["freeze-resident", "retire-registrations", "reconcile-executions", "stop-gateway", "end-epoch", "restore-token-cursor", "restore-resident", "verify-rollback"]
 
 function object(value, label) {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`)
@@ -171,12 +173,12 @@ function syncDirectory(path) {
   try { fsyncSync(fd) } finally { closeSync(fd) }
 }
 
-function atomicWrite(path, temporaryPath, bytes, metadata, expectedUid, expectedGid) {
+function atomicWrite(path, temporaryPath, bytes, metadata) {
   const fd = openSync(temporaryPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, metadata.mode)
   try {
     writeFileSync(fd, bytes)
     fchmodSync(fd, metadata.mode)
-    fchownSync(fd, metadata.uid ?? expectedUid, metadata.gid ?? expectedGid)
+    fchownSync(fd, metadata.uid, metadata.gid)
     fsyncSync(fd)
   } finally {
     closeSync(fd)
@@ -197,7 +199,8 @@ function decodeCanonicalBase64(value) {
 
 function validateJournalRecord(raw, state) {
   const record = object(raw, "template transaction journal")
-  exactKeys(record, ["schemaVersion", "state", "target", "priorTemplate", "priorTemplateDigest", "targetTemplateDigest", "canonicalVersionTag", "reviewedManifestDigest", "rollbackImageId", "targetImageId", "jellyfin", "digest"], "template transaction journal")
+  exactKeys(record, ["schemaVersion", "state", "target", "priorTemplate", "priorTemplateDigest", "targetTemplateDigest", "canonicalVersionTag", "reviewedManifestDigest", "rollbackImageId", "targetImageId", "jellyfin", "digest", ...(Object.hasOwn(record, "authority") ? ["authority"] : [])], "template transaction journal")
+  if (Object.hasOwn(record, "authority")) validateAuthorityHandoff(record.authority, record)
   if (record.schemaVersion !== 1 || !["rollback", "committing"].includes(record.state)) throw new Error("template transaction journal state is invalid")
   const target = object(record.target, "template transaction journal target")
   exactKeys(target, ["path", "name", "templateUrl", "icon"], "template transaction journal target")
@@ -230,7 +233,7 @@ function readJournal(state) {
 
 function writeJournal(record, state) {
   const complete = { ...record, digest: recordDigest(record) }
-  atomicWrite(state.journalPath, state.journalTemporary, Buffer.from(`${JSON.stringify(complete)}\n`), { uid: state.expectedUid, gid: state.expectedGid, mode: 0o600 }, state.expectedUid, state.expectedGid)
+  atomicWrite(state.journalPath, state.journalTemporary, Buffer.from(`${JSON.stringify(complete)}\n`), { uid: state.expectedUid, gid: state.expectedGid, mode: 0o600 })
   return complete
 }
 
@@ -344,7 +347,7 @@ export function prepareDockerManTemplateTransaction(input, options = {}) {
   }
   const record = writeJournal(unsigned, state)
   options.checkpoint?.("after-template-journal")
-  atomicWrite(state.targetPath, state.targetTemporary, sourceBytes, { uid: state.expectedUid, gid: state.expectedGid, mode: 0o600 }, state.expectedUid, state.expectedGid)
+  atomicWrite(state.targetPath, state.targetTemporary, sourceBytes, { uid: state.expectedUid, gid: state.expectedGid, mode: 0o600 })
   options.checkpoint?.("after-template-replacement")
   return record
 }
@@ -354,6 +357,7 @@ export function markDockerManTemplateTransactionCommitting(options = {}) {
   validateParents(state)
   const current = readJournal(state)
   if (!current) throw new Error("template transaction journal is absent")
+  requireActiveAuthority(current, state)
   if (currentTargetDigest(state) !== current.targetTemplateDigest) throw new Error("installed DockerMan template does not match the transaction")
   assertJellyfinUnchanged(current.jellyfin)
   if (current.state === "committing") {
@@ -371,11 +375,12 @@ export function rollbackDockerManTemplateTransaction(options = {}) {
   validateParents(state)
   const current = readJournal(state)
   if (!current) return false
+  if (current.authority && current.authority.state !== "retired") throw new Error("authority epoch must be retired before template rollback")
   const installedDigest = currentTargetDigest(state)
   assertJellyfinUnchanged(current.jellyfin)
   if (current.priorTemplate.present) {
     if (installedDigest !== current.targetTemplateDigest && installedDigest !== current.priorTemplateDigest) throw new Error("installed DockerMan template cannot be safely restored")
-    if (installedDigest !== current.priorTemplateDigest) atomicWrite(state.targetPath, state.targetTemporary, current.priorBytes, current.priorTemplate.metadata, state.expectedUid, state.expectedGid)
+    if (installedDigest !== current.priorTemplateDigest) atomicWrite(state.targetPath, state.targetTemporary, current.priorBytes, current.priorTemplate.metadata)
   } else if (installedDigest !== null) {
     if (installedDigest !== current.targetTemplateDigest) throw new Error("installed DockerMan template cannot be safely removed")
     deleteDurably(state.targetPath)
@@ -410,6 +415,7 @@ export function commitDockerManTemplateTransaction(proof, options = {}) {
   validateParents(state)
   const current = readJournal(state)
   if (!current) return false
+  requireActiveAuthority(current, state)
   if (current.state !== "committing" || currentTargetDigest(state) !== current.targetTemplateDigest) throw new Error("template transaction is not ready to commit")
   validateFinalProof(proof, current, state)
   assertJellyfinUnchanged(current.jellyfin)
@@ -417,6 +423,146 @@ export function commitDockerManTemplateTransaction(proof, options = {}) {
   return true
 }
 
+function requireActiveAuthority(current, state) {
+  const document = xmlValidator.parseDockerManTemplateXml(readFileSync(state.targetPath))
+  const gateway = document?.children.some((child) => child.name === "Config" && child.attributes.Target === "/run/ouro-authority")
+  if ((gateway || current.authority) && current.authority?.state !== "active") throw new Error("authority handoff is not verified")
+}
+
+function validateAuthorityPlan(raw) {
+  const plan = object(raw, "authority handoff plan")
+  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")
+  return plan
+}
+
+function authorityEffectIdentity(record, effect) {
+  return digest(Buffer.from(JSON.stringify([record.targetImageId, record.rollbackImageId, record.reviewedManifestDigest, record.authority.plan, effect.direction, effect.step, effect.beforeDigest, effect.afterDigest])))
+}
+
+function validateAuthorityHandoff(raw, record) {
+  const handoff = object(raw, "authority handoff")
+  exactKeys(handoff, ["plan", "state", "completed", "rollbackCompleted", "pending", "cancelled"], "authority handoff")
+  validateAuthorityPlan(handoff.plan)
+  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")
+    exactKeys(effect, ["direction", "step", "effectId", "beforeDigest", "afterDigest"], "authority effect")
+    if (effect.direction !== direction || effect.step !== step || !IMAGE_ID.test(effect.beforeDigest) || !IMAGE_ID.test(effect.afterDigest) || effect.beforeDigest === effect.afterDigest
+      || effect.effectId !== authorityEffectIdentity(record, effect)) throw new Error("authority effect identity is invalid")
+  }
+  for (const [direction, entries, steps] of [["install", handoff.completed, AUTHORITY_INSTALL_STEPS], ["rollback", handoff.rollbackCompleted, AUTHORITY_ROLLBACK_STEPS]]) {
+    if (entries.length > steps.length) throw new Error("authority effect order is invalid")
+    entries.forEach((effect, index) => validateEffect(effect, direction, steps[index]))
+  }
+  const rollback = handoff.state === "retiring" || handoff.state === "retired"
+  if (handoff.cancelled.length > 1 || (handoff.cancelled.length !== 0 && !rollback)) throw new Error("authority cancelled effect is invalid")
+  for (const effect of handoff.cancelled) validateEffect(effect, "install", AUTHORITY_INSTALL_STEPS[handoff.completed.length])
+  if ((!rollback && handoff.rollbackCompleted.length !== 0) || (handoff.state === "active" && handoff.completed.length !== AUTHORITY_INSTALL_STEPS.length)
+    || (handoff.state === "retired" && handoff.rollbackCompleted.length !== AUTHORITY_ROLLBACK_STEPS.length)) throw new Error("authority terminal handoff is invalid")
+  if (handoff.pending !== null) {
+    if (handoff.state === "active" || handoff.state === "retired") throw new Error("authority terminal handoff has a pending effect")
+    const steps = rollback ? AUTHORITY_ROLLBACK_STEPS : AUTHORITY_INSTALL_STEPS
+    const completed = rollback ? handoff.rollbackCompleted : handoff.completed
+    validateEffect(handoff.pending, rollback ? "rollback" : "install", steps[completed.length])
+  }
+  return handoff
+}
+
+function writeAuthorityHandoff(record, authority, state) {
+  const { priorBytes: _bytes, digest: _digest, ...unsigned } = record
+  const next = { ...unsigned, authority }
+  validateAuthorityHandoff(authority, next)
+  return writeJournal(next, state)
+}
+
+export function beginDockerManAuthorityHandoff(plan, options = {}) {
+  validateAuthorityPlan(plan)
+  const state = paths(options)
+  validateParents(state)
+  const current = readJournal(state)
+  if (!current || (!current.authority && current.state !== "rollback")) throw new Error("authority handoff requires the prepared deployment transaction")
+  assertJellyfinUnchanged(current.jellyfin)
+  if (current.authority) {
+    if (JSON.stringify(current.authority.plan) !== JSON.stringify(plan)) throw new Error("authority handoff plan changed")
+    return current.authority
+  }
+  return writeAuthorityHandoff(current, { plan, state: "installing", completed: [], rollbackCompleted: [], cancelled: [], pending: null }, state).authority
+}
+
+async function withAuthorityLease(options, work) {
+  const state = paths(options)
+  validateParents(state)
+  const withLease = options.withLease ?? (await import("../../dist/mind/session-transaction.js")).withSessionTurnLease
+  return withLease(state.journalPath, () => work(state), { timeoutMs: 0, confinementRoot: state.journalParent })
+}
+
+export async function runDockerManAuthorityEffect(name, effect, options = {}) {
+  return withAuthorityLease(options, (state) => runAuthorityEffectLocked(name, effect, state))
+}
+
+export async function beginDockerManAuthorityRollback(readback, options = {}) {
+  return withAuthorityLease(options, (state) => beginAuthorityRollbackLocked(readback, state))
+}
+
+async function beginAuthorityRollbackLocked(readback, state) {
+    const current = readJournal(state)
+    if (!current?.authority) throw new Error("authority handoff is absent")
+    const handoff = current.authority
+    if (handoff.state === "retired" || handoff.state === "retiring") return handoff
+    const pending = handoff.pending
+    const observed = pending ? await readback() : null
+    if (pending && observed !== pending.beforeDigest && observed !== pending.afterDigest) throw new Error("authority pending effect is ambiguous")
+    if (readJournal(state).digest !== current.digest) throw new Error("authority transaction changed during recovery")
+    assertJellyfinUnchanged(current.jellyfin)
+    return writeAuthorityHandoff(current, {
+      ...handoff, state: "retiring", pending: null,
+      completed: pending && observed === pending.afterDigest ? [...handoff.completed, pending] : handoff.completed,
+      cancelled: pending && observed === pending.beforeDigest ? [...handoff.cancelled, pending] : handoff.cancelled,
+    }, state).authority
+}
+
+async function runAuthorityEffectLocked(name, effect, state) {
+  let current = readJournal(state)
+  if (!current?.authority) throw new Error("authority handoff is absent")
+  assertJellyfinUnchanged(current.jellyfin)
+  const direction = name.startsWith("rollback:") ? "rollback" : "install"
+  const step = direction === "rollback" ? name.slice("rollback:".length) : name
+  const steps = direction === "rollback" ? AUTHORITY_ROLLBACK_STEPS : AUTHORITY_INSTALL_STEPS
+  if (!steps.includes(step)) throw new Error("authority handoff step is invalid")
+  if (!IMAGE_ID.test(effect.beforeDigest) || !IMAGE_ID.test(effect.afterDigest) || effect.beforeDigest === effect.afterDigest) throw new Error("authority effect identity is invalid")
+  let handoff = current.authority
+  if (direction === "install" && ["retiring", "retired"].includes(handoff.state)) throw new Error("authority handoff is retiring")
+  const expected = { direction, step, beforeDigest: effect.beforeDigest, afterDigest: effect.afterDigest }
+  const intent = { ...expected, effectId: authorityEffectIdentity(current, expected) }
+  const completedKey = direction === "install" ? "completed" : "rollbackCompleted"
+  const completed = handoff[completedKey]
+  const prior = completed.find((entry) => entry.step === step)
+  if (prior) {
+    if (prior.effectId !== intent.effectId || await effect.readback() !== prior.afterDigest) throw new Error("authority completed effect changed")
+    return prior
+  }
+  if (steps[completed.length] !== step) throw new Error("authority handoff effect order is invalid")
+  if (handoff.pending && handoff.pending.effectId !== intent.effectId) throw new Error("authority pending effect changed; recovery is required before rollback")
+  if (!handoff.pending) {
+    handoff = { ...handoff, state: direction === "rollback" ? "retiring" : "installing", pending: intent }
+    current = writeAuthorityHandoff(current, handoff, state)
+  }
+  const observed = await effect.readback()
+  if (observed !== intent.beforeDigest && observed !== intent.afterDigest) throw new Error("authority handoff effect is ambiguous")
+  if (observed === intent.beforeDigest) await effect.apply(intent.effectId)
+  if (await effect.readback() !== intent.afterDigest) throw new Error("authority handoff effect readback failed")
+  const latest = readJournal(state)
+  if (latest.digest !== current.digest) throw new Error("authority transaction changed during effect")
+  assertJellyfinUnchanged(latest.jellyfin)
+  const entries = [...completed, intent]
+  handoff = { ...handoff, [completedKey]: entries, pending: null, state: entries.length === steps.length ? direction === "install" ? "active" : "retired" : direction === "install" ? "installing" : "retiring" }
+  writeAuthorityHandoff(latest, handoff, state)
+  return intent
+}
+
 export function verifyDockerManTemplateTransactionJellyfin(options = {}) {
   const state = paths(options)
   validateParents(state)
@@ -472,6 +618,9 @@ function readRootJson(path, label) {
 
 export function runDockerManTemplateTransactionCli(argv, options = {}, write = (text) => process.stdout.write(text)) {
   const { operation, values } = parseArguments(argv)
+  if (operation?.startsWith("authority-") && values.size === 0) {
+    return runRootLifecycle(operation, options).then((result) => write(`${JSON.stringify(result)}\n`))
+  }
   let result
   if (operation === "prepare" && values.size === 5) {
     result = prepareDockerManTemplateTransaction({
@@ -523,4 +672,40 @@ export function runDockerManTemplateTransactionCli(argv, options = {}, write = (
   write(`${JSON.stringify(result)}\n`)
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) runDockerManTemplateTransactionCli(process.argv.slice(2))
+async function runRootLifecycle(operation, options) {
+  const selected = {
+    "authority-install": AUTHORITY_INSTALL_STEPS.slice(0, 6),
+    "authority-activate": AUTHORITY_INSTALL_STEPS.slice(6),
+    "authority-retire": AUTHORITY_ROLLBACK_STEPS.slice(0, 6).map((step) => `rollback:${step}`),
+    "authority-restore": AUTHORITY_ROLLBACK_STEPS.slice(6).map((step) => `rollback:${step}`),
+  }[operation]
+  if (!selected) throw new Error("authority lifecycle operation is invalid")
+  return withAuthorityLease(options, async (state) => {
+  let record = readJournal(state)
+  if (!record) throw new Error("authority lifecycle requires the prepared deployment transaction")
+  const RootLifecycle = options.RootLifecycle ?? (await import("../../dist/heart/daemon/sanctuary-authority-root-lifecycle.js")).SanctuaryAuthorityRootLifecycle
+  const lifecycle = new RootLifecycle(record, options.rootLifecycleOptions)
+  beginDockerManAuthorityHandoff(lifecycle.plan(), options)
+  record = readJournal(state)
+  if (["authority-install", "authority-activate"].includes(operation) && ["retiring", "retired"].includes(record.authority.state)) throw new Error("authority epoch is retiring or retired")
+  if (operation === "authority-activate" && record.authority.completed.length < 6) throw new Error("gateway installation must finish before resident activation")
+  if (operation === "authority-restore" && record.authority.rollbackCompleted.length < 6) throw new Error("authority retirement must finish before resident restoration")
+  if (operation === "authority-retire") {
+    const pending = record.authority.pending
+    await beginAuthorityRollbackLocked(pending ? lifecycle.effect(pending.step).readback : null, state)
+  }
+  for (const name of selected) {
+    const rollback = name.startsWith("rollback:")
+    const step = rollback ? name.slice("rollback:".length) : name
+    const current = readJournal(state).authority
+    // Completed historical effects may have intentionally changed at later
+    // steps (a frozen resident becomes running). Recheck the next real boundary,
+    // never replay earlier physical work merely to reproduce a historical hash.
+    if (current[rollback ? "rollbackCompleted" : "completed"].some((entry) => entry.step === step)) continue
+    await runAuthorityEffectLocked(name, lifecycle.effect(name), state)
+  }
+  return readJournal(state).authority
+  })
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await runDockerManTemplateTransactionCli(process.argv.slice(2))

package/deploy/unraid/sanctuary-acceptance-adapter.sh

@@ -6,7 +6,7 @@ VAULT_ENTRY='import("/opt/ouro/dist/heart/daemon/sanctuary-acceptance-adapter.js
 REVOKED_ENTRY='import fs from "node:fs"; import("/opt/ouro/dist/heart/daemon/sanctuary-acceptance-adapter.js").then(async (module) => { const result = await module.executeSanctuaryAcceptanceRevokedProbe(process.argv[1], process.argv[2], fs.readFileSync(3, "utf8")); process.stdout.write(JSON.stringify(result)); }).catch(() => { process.exitCode = 1; });'
 CALLBACK_ENTRY='import fs from "node:fs"; import("/opt/ouro/dist/heart/daemon/sanctuary-acceptance-adapter.js").then(async (module) => { const result = await module.executeSanctuaryAcceptanceCallbackProbe(JSON.parse(fs.readFileSync(0, "utf8")), process.argv[1] === "replay"); process.stdout.write(JSON.stringify(result)); }).catch(() => { process.exitCode = 1; });'
 MATERIALIZE_ENTRY='import("/opt/ouro/dist/heart/daemon/sanctuary-acceptance-adapter.js").then(async (module) => { const payload = { operation: "materialize_config", command: process.argv[1] }; if (process.argv[2]) payload.phase = process.argv[2]; const result = await module.executeSanctuaryAcceptanceAdapter(payload); process.stdout.write(JSON.stringify(result)); }).catch(() => { process.exitCode = 1; });'
-TELEGRAM_READINESS_ENTRY='import("/opt/ouro/dist/heart/daemon/sanctuary-acceptance-adapter.js").then(async (module) => { const result = await module.executeSanctuaryAcceptanceAdapter({ operation: "telegram_readiness" }); process.stdout.write(JSON.stringify(result)); }).catch((error) => { const categories = new Set(["Telegram runtime credentials are unavailable; actor: human-required; unlock or repair vault runtime/config", "Telegram runtime credentials are invalid; actor: human-required; repair vault runtime/config", "Telegram client initialization failed; actor: agent-runnable; retry Telegram readiness", "Telegram getMe failed; actor: agent-runnable; retry Telegram readiness", "Telegram client cleanup failed; actor: agent-runnable; retry Telegram readiness", "Telegram bot identity mismatch; actor: human-required; repair vault runtime/config"]); const message = String(error?.message ?? ""); const category = categories.has(message) ? message : "Telegram readiness failed; actor: agent-runnable; inspect packaged readiness"; process.stderr.write(`${category}\n`); process.exitCode = 1; });'
+TELEGRAM_READINESS_ENTRY='import("/opt/ouro/dist/heart/daemon/sanctuary-acceptance-adapter.js").then(async (module) => { const result = await module.executeSanctuaryAcceptanceAdapter({ operation: "telegram_readiness" }); process.stdout.write(JSON.stringify(result)); }).catch((error) => { const categories = new Set(["Telegram gateway inventory or pins are unavailable; actor: agent-runnable; inspect root migration", "Telegram gateway health or identity probe failed; actor: agent-runnable; inspect root authority", "Telegram client cleanup failed; actor: agent-runnable; retry Telegram readiness", "Telegram bot identity mismatch; actor: human-required; repair root gateway identity"]); const message = String(error?.message ?? ""); const category = categories.has(message) ? message : "Telegram readiness failed; actor: agent-runnable; inspect packaged readiness"; process.stderr.write(`${category}\n`); process.exitCode = 1; });'
 
 if test "${1:-}" = vault-probe; then
   test "$#" -eq 3 || exit 2

package/deploy/unraid/sanctuary-acceptance-contract.json

@@ -3,7 +3,7 @@
   "harnessExecutable": "/opt/ouro/deploy/unraid/sanctuary-acceptance-harness.sh",
   "adapterExecutable": "/opt/ouro/deploy/unraid/sanctuary-acceptance-adapter.sh",
   "adapterTimeoutMs": 240000,
-  "telegramTimeoutMs": 10000,
+  "telegramTimeoutMs": 65000,
   "deploymentTargetProfiles": {
     "staging": { "command": "sanctuary-unit16-run.sh", "acceptanceInvocation": "sanctuary-unit16-run.sh <image-id> ...", "containerName": "ouro-butler-staging", "requiredRunning": 1, "restartPolicy": "unless-stopped", "networkMode": "host", "inboundTcpListeners": 0, "inboundUdpListeners": 0, "loopbackTcpControls": [6876] },
     "final": { "command": "sanctuary-unit18-target-audit.sh", "acceptanceInvocation": "sanctuary-unit16-run.sh <image-id> --profile final ...", "containerName": "ouro-butler", "requiredRunning": 1, "optionalStopped": "ouro-butler-rollback", "restartPolicy": "unless-stopped", "networkMode": "host", "inboundTcpListeners": 0, "inboundUdpListeners": 0, "loopbackTcpControls": [6876] }
@@ -11,9 +11,9 @@
   "configMaterializer": {
     "invocation": "sanctuary-acceptance-adapter.sh materialize-config <command> [before|after]",
     "output": "complete harness config JSON on stdout",
-    "authority": "fixed-contract-offset-inventory-evidence-read",
+    "authority": "fixed-contract-signed-gateway-cursor-inventory-evidence-read",
     "modelReachable": false,
-    "timeoutMs": 15000
+    "timeoutMs": 90000
   },
   "commands": {
     "telegram-bootstrap": { "invocation": "sanctuary-acceptance-harness.sh telegram-bootstrap --config <private-json>" },
@@ -28,7 +28,7 @@
     "evidence-bundle-verify": { "invocation": "sanctuary-acceptance-harness.sh evidence-bundle-verify --config <private-json>" }
   },
   "adapters": {
-    "telegram-poller-quiescence": { "operation": "quiesce_telegram_poller", "authority": "fixed-managed-telegram-poller-stop-and-count", "modelReachable": false, "timeoutMs": 15000 },
+    "telegram-poller-quiescence": { "operation": "quiesce_telegram_poller", "authority": "fresh-pinned-gateway-health-and-root-lock-process-with-stopped-resident", "modelReachable": false, "timeoutMs": 120000 },
     "cursor-snapshot": { "operation": "snapshot", "authority": "fixed-telegram-state-read", "modelReachable": false, "timeoutMs": 15000 },
     "callback-live": { "operation": "callback_playback_preflight|inject_callbacks_concurrently|inject_callback_replay", "authority": "fixed-live-telegram-callback-probe", "modelReachable": false, "timeoutMs": 15000 },
     "key-inventory": { "operation": "inventory_keys", "authority": "fixed-unraid-key-directory-read", "modelReachable": false, "timeoutMs": 15000 },
@@ -50,7 +50,7 @@
     "callback-inject": { "operation": "callback-inject", "authority": "fixed-harness-orchestration", "modelReachable": false, "timeoutMs": 120000 },
     "reboot-request": { "operation": "reboot-request", "authority": "fixed-harness-orchestration", "modelReachable": false, "timeoutMs": 120000 },
     "unraid-key-rotate": { "operation": "unraid-key-rotate", "authority": "fixed-harness-orchestration", "modelReachable": false, "timeoutMs": 120000 },
-    "config-materializer": { "operation": "materialize_config", "authority": "fixed-contract-offset-inventory-evidence-read", "modelReachable": false, "timeoutMs": 120000 },
+    "config-materializer": { "operation": "materialize_config", "authority": "fixed-contract-signed-gateway-cursor-inventory-evidence-read", "modelReachable": false, "timeoutMs": 120000 },
     "scenario-capture": { "operation": "capture_acceptance_scenario", "authority": "fixed-runtime-audit-telegram-container-scenario", "modelReachable": false, "timeoutMs": 210000, "phases": ["begin", "poll"], "publicGateStatus": "/evidence/current-scenario-gate.json contains only label,gate,phase,startedAt", "response": "waiting:{state,checkpointDigest}|complete:{state,checkpointDigest,sourceDigests,assertions}" },
     "scenario-finalize": { "operation": "finalize_acceptance_scenarios", "authority": "fixed-public-gate-private-marker-receipt-cleanup", "modelReachable": false, "timeoutMs": 120000, "response": "{finalized:true}" },
     "health-probe-start": { "operation": "start_health_probe", "authority": "fixed-owner-bound-packaged-health-probe-start", "modelReachable": false, "timeoutMs": 170000, "response": "{state:started,operationDigest}" },
@@ -64,7 +64,7 @@
     "identity-key": { "kind": "fixed-file", "path": "/home/ouro/AgentBundles/sanctuary.ouro/state/senses/telegram/identity.key", "redaction": "sha256-only" },
     "identity-surface-audit": { "kind": "bounded-bundle-surface-audit", "path": "/home/ouro/AgentBundles/sanctuary.ouro", "redaction": "record-match-raw-leak-counts-and-surface-digest-only" },
     "telegram-audit": { "kind": "fixed-mac-chain", "path": "/home/ouro/AgentBundles/sanctuary.ouro/state/acceptance/telegram-audit-chain.ndjson", "headPath": "/home/ouro/AgentBundles/sanctuary.ouro/state/acceptance/telegram-audit-chain.head.json", "redaction": "canonical-redacted-rows-with-hmac-chain" },
-    "telegram-offset": { "kind": "fixed-json", "path": "/home/ouro/AgentBundles/sanctuary.ouro/state/senses/telegram/offset.json", "redaction": "sha256-only" },
+    "telegram-offset": { "kind": "signed-gateway-cursor", "operation": "telegram.cursor.snapshot", "redaction": "stable-logical-progress-digest-only" },
     "approval-journal": { "kind": "fixed-sqlite", "path": "/home/ouro/AgentBundles/sanctuary.ouro/state/approvals/approvals.sqlite", "redaction": "typed-state-counters-and-digests-only" },
     "approval-checkpoints": { "kind": "fixed-json", "path": "/home/ouro/AgentBundles/sanctuary.ouro/state/approvals/checkpoints.json", "redaction": "typed-state-counters-and-digests-only" },
     "restart-attempt-ledger": { "kind": "fixed-ndjson", "path": "/home/ouro/AgentBundles/sanctuary.ouro/state/acceptance/restart-attempts.ndjson", "redaction": "scenario-action-target-digests-and-state-only" },
@@ -93,7 +93,7 @@
         "deadlineMs": 600000,
         "pollTimeoutSeconds": 20
       },
-      "dynamic": ["expectedBotId:getMe.id", "expectedUsername:getMe.username", "currentOffset:fixed-cursor-read"]
+      "dynamic": ["expectedBotId:pinned-gateway-getMe.id", "expectedUsername:pinned-gateway-getMe.username", "currentOffset:signed-gateway-cursor"]
     },
     "cursor-snapshot": {
       "fixed": {

package/deploy/unraid/sanctuary-authority-installation.json

@@ -0,0 +1,36 @@
+{
+  "schemaVersion": 1,
+  "rootUid": 0,
+  "rootGid": 0,
+  "residentUid": 10001,
+  "residentGid": 10001,
+  "stateRoot": "/mnt/user/appdata/ouro-authority",
+  "stateMode": 448,
+  "secretMode": 384,
+  "packageRoot": "/mnt/user/appdata/ouro-authority/package",
+  "activeConfigPath": "/mnt/user/appdata/ouro-authority/active.json",
+  "requestPath": "/mnt/user/appdata/ouro-authority/request.json",
+  "incomingTokenPath": "/mnt/user/appdata/ouro-authority/incoming-token",
+  "incomingPackagePath": "/mnt/user/appdata/ouro-authority/incoming-package",
+  "packageManifestPath": "/mnt/user/appdata/ouro-authority/package-manifest.json",
+  "bootPath": "/boot/config/custom/ouro-authority/start.sh",
+  "socketRoot": "/run/ouro-authority",
+  "socketDirectoryMode": 488,
+  "socketMode": 432,
+  "residentPinsMode": 416,
+  "socketPath": "/run/ouro-authority/authority.sock",
+  "residentPinsPath": "/run/ouro-authority/resident.json",
+  "stagingRoot": "/var/lib/ouro-authority/staging",
+  "cgroupRoot": "/sys/fs/cgroup/ouro-authority",
+  "controllers": ["cpu", "memory", "pids"],
+  "sourceMountContract": "canonical-pre-gateway",
+  "targetMountContract": "canonical-gateway",
+  "servicePath": "/mnt/user/appdata/ouro-authority/package/deploy/unraid/sanctuary-authority-service.sh",
+  "serviceMode": 448,
+  "nodePath": "/usr/local/bin/node",
+  "prlimitPath": "/usr/bin/prlimit",
+  "setsidPath": "/usr/bin/setsid",
+  "shellPath": "/bin/sh",
+  "transactionOwner": "docker-man-template-transaction.mjs",
+  "epochRetirementRequiredBeforeRollback": true
+}

package/deploy/unraid/sanctuary-authority-service.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+set -eu
+umask 077
+test "$(id -u):$(id -g)" = 0:0
+cd /
+case "${1-}" in
+  --boot)
+    test "$#" -eq 1
+    # Unraid's go hook can run before the array and Docker are available.
+    attempt=0
+    while test ! -f /mnt/user/appdata/ouro-authority/active.json || test ! -S /var/run/docker.sock || ! /usr/bin/docker info >/dev/null 2>&1; do
+      attempt=$((attempt + 1))
+      test "$attempt" -le 300
+      sleep 1
+    done
+    exec /usr/bin/env -i PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
+      /usr/local/bin/node /mnt/user/appdata/ouro-authority/package/dist/heart/daemon/sanctuary-authority-root-lifecycle.js boot </dev/null
+    ;;
+  "") test "$#" -eq 0 ;;
+  *) exit 2 ;;
+esac
+test -d /mnt/user/appdata/ouro-authority
+test ! -L /mnt/user/appdata/ouro-authority
+test "$(stat -c '%u:%g:%a' /mnt/user/appdata/ouro-authority)" = 0:0:700
+test -f /mnt/user/appdata/ouro-authority/active.json
+test ! -L /mnt/user/appdata/ouro-authority/active.json
+test "$(stat -c '%u:%g:%a' /mnt/user/appdata/ouro-authority/active.json)" = 0:0:600
+exec /usr/bin/env -i PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
+  /usr/local/bin/node /mnt/user/appdata/ouro-authority/package/dist/heart/daemon/sanctuary-telegram-authority-entry.js \
+  --config /mnt/user/appdata/ouro-authority/active.json </dev/null

package/deploy/unraid/sanctuary-unit16-host-broker.mjs

@@ -2,7 +2,7 @@
 
 import { spawn, spawnSync } from "node:child_process"
 import { createHash, createHmac, timingSafeEqual } from "node:crypto"
-import { chmodSync, chownSync, closeSync, constants, fstatSync, fsyncSync, mkdirSync, openSync, opendirSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+import { chmodSync, chownSync, closeSync, constants, fstatSync, fsyncSync, mkdirSync, openSync, opendirSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs"
 import { createServer } from "node:net"
 import { targetProfile } from "./sanctuary-deployment-target.mjs"
 
@@ -18,6 +18,7 @@ const RUNTIME_POLICY_FILE = "/opt/ouro/container-runtime.json"
 const PRODUCTION_RUNTIME_SOURCE = "/mnt/user/appdata/ouro-butler/runtime/.ouro-cli"
 const PRODUCTION_BUNDLE_SOURCE = "/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro"
 const PRODUCTION_EVENT_SPOOL_SOURCE = "/boot/config/custom/ouro-events/spool"
+const AUTHORITY_ROOT = "/mnt/user/appdata/ouro-authority"
 const GRAPHQL_ENDPOINT = "http://127.0.0.1/graphql"
 const BOOT_ID = "/proc/sys/kernel/random/boot_id"
 const MDCMD = "/usr/local/sbin/mdcmd"
@@ -361,8 +362,8 @@ function parseVaultStatus(output, succeeded) {
     return match[1].split(", ").includes("apiKey") && match[2].split(", ").includes("baseUrl")
   }
   const unlocked = succeeded && /^local unlock: available$/mu.test(output)
-    && ["telegramBotToken", "telegramAuthorizedUserId", "telegramAuthorizedChatId"].every((field) => runtimeFields.includes(field))
-    && providerReady("openai-compatible") && providerReady("openai-compatible-gemini")
+    && runtimeMatch !== null && !runtimeFields.includes("telegramBotToken")
+    && providerReady("minimax")
   return { vaultUnlocked: unlocked, manualAuthRequired: !unlocked }
 }
 
@@ -503,6 +504,7 @@ async function containerSnapshot(expectedImage) {
     { destination: "/home/ouro/.ouro-cli", source: PRODUCTION_RUNTIME_SOURCE, propagation: "rprivate", rw: true, type: "bind" },
     { destination: "/home/ouro/AgentBundles/sanctuary.ouro", source: PRODUCTION_BUNDLE_SOURCE, propagation: "rprivate", rw: true, type: "bind" },
     { destination: "/run/ouro-events", source: PRODUCTION_EVENT_SPOOL_SOURCE, propagation: "rprivate", rw: false, type: "bind" },
+    { destination: "/run/ouro-authority", source: "/run/ouro-authority", propagation: "rprivate", rw: false, type: "bind" },
   ]
   const mountsExact = mounts.length === expectedMounts.length && expectedMounts.every((expected) => mounts.some((mount) => mount.destination === expected.destination && mount.source === expected.source && mount.propagation === expected.propagation && mount.rw === expected.rw && mount.type === expected.type))
   const securityExact = value.privileged === false && (value.capAdd === null || (Array.isArray(value.capAdd) && value.capAdd.length === 0))
@@ -552,7 +554,7 @@ async function containerSnapshot(expectedImage) {
   }
 }
 
-function inspectRebootOwner(containerId = PRODUCTION_CONTAINER) {
+function inspectRebootOwner(containerId = activeContainerId) {
   const template = '{"containerId":{{json .Id}},"name":{{json .Name}},"imageId":{{json .Image}},"running":{{json .State.Running}},"pid":{{json .State.Pid}},"startedAt":{{json .State.StartedAt}},"health":{{json .State.Health.Status}},"restartCount":{{json .RestartCount}}}'
   const result = spawnSync(DOCKER, ["inspect", "--format", template, containerId], {
     cwd: "/", encoding: "utf8", timeout: 20_000, maxBuffer: 64 * 1024,
@@ -562,9 +564,55 @@ function inspectRebootOwner(containerId = PRODUCTION_CONTAINER) {
   return object(JSON.parse(result.stdout ?? ""), "reboot owner inspection")
 }
 
+function readAuthorityText(file) {
+  if (!file.startsWith(`${AUTHORITY_ROOT}/`) || realpathSync(file) !== file) throw new Error("root authority path is unsafe")
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    const stat = fstatSync(fd)
+    if (!stat.isFile() || stat.uid !== 0 || stat.gid !== 0 || stat.nlink !== 1 || (stat.mode & 0o7777) !== 0o600 || stat.size < 1 || stat.size > 65536) throw new Error("root authority metadata is unsafe")
+    return readFileSync(fd, "utf8")
+  } finally { closeSync(fd) }
+}
+
+function telegramGatewayQuiescence() {
+  const observe = () => {
+    const config = object(JSON.parse(readAuthorityText(`${AUTHORITY_ROOT}/active.json`)), "root authority configuration")
+    const keyId = text(config.keyId, "root issuer", /^[A-Za-z0-9_-]{1,128}$/u)
+    const botId = text(config.botId, "root bot identity", /^[1-9][0-9]*$/u)
+    const publicKeyDigest = text(config.publicKeyDigest, "root issuer digest", /^sha256:[a-f0-9]{64}$/u)
+    const epochRoot = `${AUTHORITY_ROOT}/epochs/${keyId}`
+    if (config.lockPath !== `${epochRoot}/authority.lock`) throw new Error("root authority lock path changed")
+    const epoch = object(JSON.parse(readAuthorityText(`${epochRoot}/epoch.json`)), "root authority epoch")
+    if (epoch.schemaVersion !== 1 || epoch.state !== "prepared" || epoch.epochId !== keyId || epoch.botId !== botId || epoch.publicKeyDigest !== publicKeyDigest
+      || epoch.revokedTokenStatus !== 401 || !/^sha256:[a-f0-9]{64}$/u.test(epoch.tokenDigest) || !/^sha256:[a-f0-9]{64}$/u.test(epoch.previousTokenDigest)
+      || epoch.tokenDigest === epoch.previousTokenDigest) throw new Error("root authority token epoch is invalid")
+    const pid = Number(readAuthorityText(config.lockPath))
+    if (!Number.isSafeInteger(pid) || pid <= 0 || pid > 4_194_304) throw new Error("root authority lock PID is invalid")
+    const processes = spawnSync(PGREP, ["-f", "sanctuary-telegram-authority-entry[.]js"], {
+      cwd: "/", encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024, stdio: ["ignore", "pipe", "ignore"],
+    })
+    if (processes.error || processes.status !== 0 || processes.stdout.trim() !== String(pid)) throw new Error("root authority does not have exactly one live poller")
+    const status = readBoundedProcStatus(`/proc/${pid}/status`)
+    if (!status.split("\n").includes("Uid:\t0\t0\t0\t0") || !status.split("\n").includes("Gid:\t0\t0\t0\t0")) throw new Error("root authority process identity is invalid")
+    const command = readBoundedProcStatus(`/proc/${pid}/cmdline`)
+    if (command !== ["/usr/local/bin/node", `${AUTHORITY_ROOT}/package/dist/heart/daemon/sanctuary-telegram-authority-entry.js`, "--config", `${AUTHORITY_ROOT}/active.json`, ""].join("\0")) throw new Error("root authority process command changed")
+    const processStartTime = parseProcStartTime(readBoundedProcStatus(`/proc/${pid}/stat`))
+    const resident = inspectRebootOwner(activeContainerId)
+    if (resident.containerId !== activeContainerId || resident.name !== `/${activeContainer}` || resident.imageId !== expectedImageId || resident.running !== false || resident.pid !== 0) throw new Error("resident Telegram owner is not stopped")
+    return { keyId, botId, publicKeyDigest, pid, processStartTime, bootId: readFileSync(BOOT_ID, "utf8"), resident }
+  }
+  const before = observe()
+  const after = observe()
+  if (JSON.stringify(before) !== JSON.stringify(after)) throw new Error("root authority process generation changed")
+  return {
+    schemaVersion: 1, activePollers: 1, residentStopped: true, keyId: after.keyId, botId: after.botId, publicKeyDigest: after.publicKeyDigest,
+    processBindingDigest: createHash("sha256").update(JSON.stringify(after)).digest("hex"), observedAt: new Date().toISOString(),
+  }
+}
+
 function runningRebootOwnerGeneration() {
   const before = inspectRebootOwner()
-  if (before.name !== `/${PRODUCTION_CONTAINER}` || before.imageId !== expectedImageId || before.running !== true || before.health !== "healthy"
+  if (before.name !== `/${activeContainer}` || before.imageId !== expectedImageId || before.running !== true || before.health !== "healthy"
     || !Number.isSafeInteger(before.pid) || before.pid <= 0 || !Number.isSafeInteger(before.restartCount) || before.restartCount < 0) {
     throw new Error("reboot owner generation is invalid")
   }
@@ -591,7 +639,7 @@ function stopExactRebootOwner(expectedBinding) {
 
 function verifyStoppedRebootOwner(proof) {
   const value = inspectRebootOwner(text(proof.containerId, "stopped owner container id", SHA256))
-  if (value.containerId !== proof.containerId || value.name !== `/${PRODUCTION_CONTAINER}` || value.imageId !== proof.imageId
+  if (value.containerId !== proof.containerId || value.name !== `/${activeContainer}` || value.imageId !== proof.imageId
     || value.restartCount !== proof.restartCount || value.startedAt !== proof.startedAt || value.running !== false || value.pid !== 0) {
     throw new Error("exact stopped production owner generation changed")
   }
@@ -1280,7 +1328,7 @@ function createOwnerMutationCoordinator() {
   const enqueue = (operation) => {
     if (rebootReservation !== null) return Promise.reject(new Error("owner mutation refused by reboot reservation"))
     pendingOperations += 1
-    const task = ownerTail.catch(() => {}).then(async () => {
+    const task = ownerTail.then(async () => {
       try { return await operation() } finally { pendingOperations -= 1 }
     })
     ownerTail = task.then(() => {}, () => {})
@@ -1294,7 +1342,7 @@ function createOwnerMutationCoordinator() {
       if (rebootReservation !== null) throw new Error("reboot reservation already exists")
       rebootReservation = { id: reservationId, processBindingDigest, stoppedProof: null, attempted: false }
       try {
-        await ownerTail.catch(() => {})
+        await ownerTail
         if (pendingOperations !== 0 || activeHealth.size !== 0) throw new Error("reboot reservation could not drain owner mutations")
         return await operation()
       } catch (error) {
@@ -1376,7 +1424,7 @@ function createInteractiveRestartDriver() {
           (error) => { records.set(key, { state: "failed", errorDigest: createHash("sha256").update(interactiveFailureCategory(error)).digest("hex") }) },
       )
       tasks.add(task)
-      void task.finally(() => tasks.delete(task)).catch(() => {})
+      void task.finally(() => tasks.delete(task))
     },
     async stopAndDrain() { await Promise.allSettled([...tasks]) },
   }
@@ -1747,6 +1795,11 @@ async function dispatch(request, dependencies = {
 }) {
   const payload = object(request, "broker request")
   const operation = text(payload.operation, "operation")
+  if (operation === "telegram_gateway_quiescence") {
+    exactKeys(payload, ["operation", "targetId"], operation)
+    if (payload.targetId !== TARGET_HOST) throw new Error("target host is invalid")
+    return telegramGatewayQuiescence()
+  }
   if (operation === "inventory_keys") {
     exactKeys(payload, ["operation", "targetServerId"], operation)
     if (payload.targetServerId !== TARGET_SERVER) throw new Error("target server is invalid")