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

package/changelog.json

@@ -1,6 +1,15 @@
 {
   "_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.866",
+      "changes": [
+        "The Sanctuary lifecycle now relaunches a gateway that exits before readiness (backoff of 2, 10 and 30 seconds) within one 15-minute readiness deadline and, if every attempt fails, throws promptly with the gateway.log tail (token-shaped text masked before the tail is cut) instead of waiting out a fresh budget.",
+        "The Sanctuary Telegram authority retries getMe with backoff on network-class errors (fetch failed, ECONNRESET, ETIMEDOUT, 5xx) and still fails at once on auth errors such as 401.",
+        "The Sanctuary authority socket server handles client connection errors by logging them and skips writes to destroyed connections, so a client that disconnects mid-response no longer crashes the gateway with write EPIPE.",
+        "The Butler upgrade script checks that api.telegram.org is reachable before pausing host supervision and aborts early with a clear message if it is not; it skips the check when an upgrade journal exists (resume or rollback)."
+      ]
+    },
     {
       "version": "0.1.0-alpha.865",
       "changes": [

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

@@ -909,7 +909,31 @@ function waitForButler(imageRef, seconds) {
   return false
 }
 
-function upgrade(version, rehearse, { noGate = false, plant } = {}) {
+// The new gateway asks Telegram who it is (getMe) before it reports ready. When the host cannot reach
+// Telegram, that fails and the whole upgrade rolls back after host supervision was already paused
+// (the 863 -> 864 upgrade). Any HTTP answer from the API host proves the network path; no token is sent.
+export const TELEGRAM_API_URL = "https://api.telegram.org/"
+export async function telegramApiReachable({ fetchImpl = globalThis.fetch, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), tries = 3, timeoutMs = 8000, retryDelayMs = 3000 } = {}) {
+  let detail = "no attempt made"
+  for (let attempt = 1; attempt <= tries; attempt += 1) {
+    try {
+      const response = await fetchImpl(TELEGRAM_API_URL, { method: "GET", signal: AbortSignal.timeout(timeoutMs) })
+      return { ok: true, detail: `HTTP ${response.status}` }
+    } catch (error) {
+      detail = error instanceof Error ? (error.cause instanceof Error ? `${error.message}: ${error.cause.message}` : error.message) : String(error)
+      if (attempt < tries) await sleep(retryDelayMs)
+    }
+  }
+  return { ok: false, detail: `${detail} (${tries} attempts)` }
+}
+
+// A resume or rollback (an upgrade journal exists) must never be blocked by a network probe.
+export async function checkTelegramBeforePause({ journalExists, probe = telegramApiReachable }) {
+  if (journalExists) return { skipped: true, ok: true, detail: "upgrade journal present" }
+  return { skipped: false, ...(await probe()) }
+}
+
+async function upgrade(version, rehearse, { noGate = false, plant } = {}) {
   say(`in-place upgrade to ${version}${rehearse ? ` — REHEARSAL: stop after "${rehearse}", then roll back` : ""}`)
   if (rehearse && !UPGRADE_STEPS.includes(rehearse)) fail(`--rehearse takes one of: ${UPGRADE_STEPS.join(", ")}`)
   const gated = !rehearse && !noGate
@@ -937,6 +961,10 @@ function upgrade(version, rehearse, { noGate = false, plant } = {}) {
   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 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")
+  else ok(`api.telegram.org reachable (${telegram.detail})`)
   pauseSupervision()
   let failure = null
   try {
@@ -1046,7 +1074,7 @@ export function parseUpgradeArgs(argv) {
   return parsed
 }
 
-function run(argv) {
+async function run(argv) {
   let args
   try { args = parseUpgradeArgs(argv) } catch (error) { console.error(error.message); process.exit(2) }
   requireRoot()
@@ -1054,7 +1082,7 @@ function run(argv) {
   else if (args.phase === "prepare") prepare(args.version)
   else if (args.phase === "install") install(args.version)
   else if (args.phase === "verify") verify(args.gate)
-  else if (args.phase === "upgrade") upgrade(args.version, args.rehearse, { noGate: args.noGate, plant: args.plant })
+  else if (args.phase === "upgrade") await upgrade(args.version, args.rehearse, { noGate: args.noGate, plant: args.plant })
 }
 
-if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) run(process.argv.slice(2))
+if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) run(process.argv.slice(2)).catch((error) => { console.error(error); process.exit(1) })

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

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

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.865</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.866</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

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

@@ -73,6 +73,10 @@ const DIGEST = /^sha256:[a-f0-9]{64}$/u;
 // page cache on Unraid's array that takes minutes, so readiness gets a generous budget
 // (a 120 s budget failed a real rollback on 2026-09-24).
 const GATEWAY_READY_TIMEOUT_MS = 900_000;
+const GATEWAY_START_BACKOFF_MS = [2_000, 10_000, 30_000];
+const GATEWAY_LOG_TAIL_CHARS = 2_000;
+// Read more than is shown, so masking sees whole tokens before the tail is cut.
+const GATEWAY_LOG_READ_BYTES = 4_096;
 const GATEWAY_LOG_MAX_BYTES = 5 * 1024 * 1024;
 const TEMPLATE_JOURNAL = "/boot/config/custom/ouro-butler/docker-man-template-transaction.json";
 // In-place upgrade of an installed authority: same epoch (token, issuer, cursor,
@@ -536,29 +540,69 @@ class SanctuaryAuthorityRootLifecycle {
         if (!this.#tokensAbsent() || !this.#rotated())
             throw new Error("Sanctuary root token custody is not exclusive");
         if (this.#pid() === null) {
-            this.#remove(`${this.#epochRoot()}/readiness.json`);
-            const log = this.#gatewayLog();
-            let child;
-            try {
-                child = (0, node_child_process_1.spawn)(this.#p("/usr/local/bin/node"), [this.#p(`${ROOT}/package/dist/heart/daemon/sanctuary-telegram-authority-entry.js`), "--config", this.#p(`${ROOT}/active.json`)], {
-                    cwd: "/", env: { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" }, detached: true, stdio: ["ignore", log, log],
-                });
-            }
-            finally {
-                fs.closeSync(log);
+            // The gateway can exit within seconds of launch (a transient Telegram network error at
+            // getMe did, 863 -> 864). Retry the launch with backoff, and when every attempt fails
+            // say so now, with the gateway's own output, instead of waiting out the readiness budget.
+            // One deadline bounds every launch: a relaunch only gets the budget that remains.
+            const deadline = Date.now() + GATEWAY_READY_TIMEOUT_MS;
+            for (let attempt = 0;; attempt += 1) {
+                const failure = await this.#launchGatewayOnce(deadline - Date.now());
+                if (failure === null)
+                    return;
+                if (attempt >= GATEWAY_START_BACKOFF_MS.length || Date.now() + GATEWAY_START_BACKOFF_MS[attempt] >= deadline) {
+                    throw new Error(`Sanctuary gateway ${failure} before readiness after ${attempt + 1} attempts; gateway.log tail:\n${this.#gatewayLogTail()}`);
+                }
+                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "daemon", event: "daemon.sanctuary_gateway_start_retry", message: "Sanctuary gateway exited before readiness; retrying launch", meta: { attempt: attempt + 1, delayMs: GATEWAY_START_BACKOFF_MS[attempt], failure } });
+                await new Promise((resolve) => setTimeout(resolve, GATEWAY_START_BACKOFF_MS[attempt]));
             }
-            child.unref();
-            let failed = false;
-            child.once("error", () => { failed = true; });
-            await this.#wait(async () => {
-                if (failed)
-                    throw new Error("Sanctuary gateway launch failed");
-                return this.#ready();
-            }, GATEWAY_READY_TIMEOUT_MS);
         }
         else
             await this.#wait(() => this.#ready(), GATEWAY_READY_TIMEOUT_MS);
     }
+    /** One launch: resolves null once the gateway is ready, or "exited"/"failed to launch" if the process ends first. */
+    async #launchGatewayOnce(budgetMs) {
+        this.#remove(`${this.#epochRoot()}/readiness.json`);
+        const log = this.#gatewayLog();
+        let child;
+        try {
+            child = (0, node_child_process_1.spawn)(this.#p("/usr/local/bin/node"), [this.#p(`${ROOT}/package/dist/heart/daemon/sanctuary-telegram-authority-entry.js`), "--config", this.#p(`${ROOT}/active.json`)], {
+                cwd: "/", env: { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" }, detached: true, stdio: ["ignore", log, log],
+            });
+        }
+        finally {
+            fs.closeSync(log);
+        }
+        child.unref();
+        let ended = null;
+        child.once("error", () => { ended = "failed to launch"; });
+        child.once("exit", (code, signal) => { ended = `exited (${signal ?? `code ${code}`})`; });
+        let readiness = "ready";
+        await this.#wait(async () => {
+            if (ended !== null) {
+                readiness = "ended";
+                return true;
+            }
+            return this.#ready();
+        }, budgetMs);
+        return readiness === "ended" ? ended : null;
+    }
+    /** The last of gateway.log, with anything token-shaped masked, for an error message. */
+    #gatewayLogTail() {
+        const file = this.#p(`${ROOT}/gateway.log`);
+        if (!fs.existsSync(file))
+            return "(no gateway.log)";
+        const size = fs.statSync(file).size;
+        const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try {
+            const length = Math.min(size, GATEWAY_LOG_READ_BYTES);
+            const buffer = Buffer.alloc(length);
+            fs.readSync(fd, buffer, 0, length, size - length);
+            return buffer.toString("utf8").replace(/[0-9]{5,}:[A-Za-z0-9_-]{20,}/gu, "[token]").slice(-GATEWAY_LOG_TAIL_CHARS).trim() || "(gateway.log is empty)";
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
     /** The gateway's own output, kept root-only beside the token it guards and capped at two
      * generations. It used to go nowhere, so a gateway that exited at startup said nothing
      * (D-036: finding "host cgroup entry is invalid" took a hand-run gateway). */

package/dist/heart/daemon/sanctuary-telegram-authority-entry.js

@@ -199,6 +199,36 @@ async function readBoundedFileResponse(response) {
     const contentType = response.headers.get("content-type");
     return { body: Buffer.concat(chunks, total), ...(contentType ? { contentType } : {}) };
 }
+const GET_ME_BACKOFF_MS = [5_000, 10_000, 20_000, 30_000];
+const NETWORK_FAILURE = /fetch failed|ECONNRESET|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|ENETUNREACH|EHOSTUNREACH|EPIPE|socket hang up|network|timed out/iu;
+/** A getMe failure worth another try: Telegram 5xx, or no HTTP answer at all (the client reports a
+ * transport failure as a status-less TelegramApiError). Auth and other 4xx answers are never retried. */
+function isTransientTelegramFailure(error) {
+    if (!(error instanceof telegram_client_1.TelegramApiError))
+        return false;
+    if (error.status !== null)
+        return error.status >= 500;
+    return error.errorCode === null && NETWORK_FAILURE.test(error.message);
+}
+async function getMeWithRetry(api, sleep) {
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            return await api.request("getMe", {});
+        }
+        catch (error) {
+            if (attempt >= GET_ME_BACKOFF_MS.length || !isTransientTelegramFailure(error))
+                throw error;
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "daemon",
+                event: "daemon.sanctuary_authority_getme_retry",
+                message: "Telegram getMe failed with a transient error; retrying",
+                meta: { attempt: attempt + 1, delayMs: GET_ME_BACKOFF_MS[attempt] },
+            });
+            await sleep(GET_ME_BACKOFF_MS[attempt]);
+        }
+    }
+}
 async function startSanctuaryTelegramAuthority(options) {
     (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_authority_boot_requested", message: "Sanctuary authority boot requested; prerequisite verification pending" });
     const expectedUid = options.expectedUid ?? 0;
@@ -245,7 +275,7 @@ async function startSanctuaryTelegramAuthority(options) {
         const publicKey = (0, node_crypto_1.createPublicKey)(privateKey);
         if (!options.retireOnly) {
             api = (options.createApi ?? ((value) => (0, telegram_client_1.createTelegramBotApi)({ token: value })))(token);
-            const identity = await api.request("getMe", {});
+            const identity = await getMeWithRetry(api, options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))));
             if (!isObject(identity) || String(identity.id) !== config.botId) {
                 throw new Error("Sanctuary Telegram authority bot identity changed");
             }

package/dist/heart/daemon/sanctuary-telegram-authority-service.js

@@ -520,6 +520,17 @@ function createSanctuaryTelegramAuthorityServer(options) {
         connection.setEncoding("utf8");
         connection.setTimeout(connectionTimeoutMs, () => connection.destroy());
         connection.once("close", () => connections.delete(connection));
+        // A client that vanishes mid-response (reset, timeout, crash) surfaces as EPIPE/ECONNRESET on this
+        // socket; unhandled, that killed the whole gateway. Log it and let the connection close.
+        connection.on("error", (error) => {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "daemon",
+                event: "daemon.sanctuary_authority_connection_error",
+                message: "Sanctuary authority client connection failed; dropping it",
+                meta: { code: error.code ?? "unknown" },
+            });
+        });
         let buffer = "";
         connection.on("data", (chunk) => {
             buffer += chunk;
@@ -573,20 +584,22 @@ function createSanctuaryTelegramAuthorityServer(options) {
                 const response = dispatchTail.then(async () => {
                     try {
                         const result = await options.dispatch(frame.method, frame.params);
-                        connection.write(`${JSON.stringify({
-                            protocolVersion: PROTOCOL_VERSION,
-                            id: frame.id,
-                            ok: true,
-                            result,
-                        })}\n`);
+                        if (!connection.destroyed)
+                            connection.write(`${JSON.stringify({
+                                protocolVersion: PROTOCOL_VERSION,
+                                id: frame.id,
+                                ok: true,
+                                result,
+                            })}\n`);
                     }
                     catch {
-                        connection.write(`${JSON.stringify({
-                            protocolVersion: PROTOCOL_VERSION,
-                            id: frame.id,
-                            ok: false,
-                            error: { message: "Sanctuary authority request failed" },
-                        })}\n`);
+                        if (!connection.destroyed)
+                            connection.write(`${JSON.stringify({
+                                protocolVersion: PROTOCOL_VERSION,
+                                id: frame.id,
+                                ok: false,
+                                error: { message: "Sanctuary authority request failed" },
+                            })}\n`);
                     }
                 });
                 dispatchTail = response;

package/npm-shrinkwrap.json

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