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

package/changelog.json

@@ -1,6 +1,22 @@
 {
   "_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.867",
+      "changes": [
+        "Butler awaits can now ask the owner to decide: resolve_await accepts verdict ask_owner with a plain-words question and 2 to 4 choices, which closes the await as asked_owner (once per await instance, at most 3 per requester per day) and sends the question to the owner's own Telegram chat as the Butler, instead of an await tick repeating verdict no forever on a confirmed dead download.",
+        "Butler awaits can now ask the owner to decide: resolve_await accepts verdict ask_owner with a plain-words question and 2 to 4 choices, which closes the await as asked_owner (once per await instance, at most 3 per non-owner requester per day) and sends the question to the owner's own Telegram chat as the Butler, instead of an await tick repeating verdict no forever on a confirmed dead download."
+      ]
+    },
+    {
+      "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.867",
   "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.867</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/a2a/replay-harness.js

@@ -112,8 +112,10 @@ function isReplayWindowOpen(agentRoot, friendId, now = Date.now(), trustedUid =
         : Number.NaN;
     return Number.isFinite(expiresAt) && expiresAt > now && expiresAt <= now + exports.REPLAY_WINDOW_MAX_MS;
 }
-/** Appends one notice to the sink; throws when it cannot be written, so the caller refuses exactly as a failed Telegram send does. */
+/** Appends one notice to the sink, once per notice id and friend (a retry after a crash adds nothing); throws when it cannot be written, so the caller refuses exactly as a failed Telegram send does. */
 function appendReplayNotice(agentRoot, notice, now = Date.now()) {
+    if (replayNoticeRecorded(agentRoot, notice.noticeId, notice.friendId))
+        return;
     fs.mkdirSync(replayDir(agentRoot), { recursive: true });
     const line = JSON.stringify({ at: new Date(now).toISOString(), ...notice });
     fs.appendFileSync(replaySinkPath(agentRoot), `${line}\n`, { mode: 0o600 });

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

@@ -33,7 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.askedOwnerText = askedOwnerText;
 exports.createA2AAwaitOwnerDeliverer = createA2AAwaitOwnerDeliverer;
+exports.defaultNotifyOwner = defaultNotifyOwner;
 const path = __importStar(require("path"));
 const friends_1 = require("@ouro.bot/friends");
 const identity_1 = require("../identity");
@@ -46,6 +48,13 @@ const runtime_1 = require("../../nerves/runtime");
  * sent as the owner or to the peer, and the notice id is the await's delivery id, so a retry cannot double-send.
  */
 const NOTICE_ID_MAX_BYTES = 512;
+/** A question for the owner reads as the owner's own question, with a pointer to the request it is about; every other outcome is a follow-up report. */
+function askedOwnerText(question, about) {
+    return `${question}\n\n(about the request from ${about})`;
+}
+function ownerNoticeText(request, from) {
+    return request.noticeKind === "asked_owner" ? askedOwnerText(request.content, from) : `Follow-up on a request from ${from}: ${request.content}`;
+}
 function createA2AAwaitOwnerDeliverer(agentName, notifyOwner = defaultNotifyOwner(agentName)) {
     return async (request) => {
         if (!request.deliveryId || Buffer.byteLength(request.deliveryId) > NOTICE_ID_MAX_BYTES) {
@@ -54,12 +63,12 @@ function createA2AAwaitOwnerDeliverer(agentName, notifyOwner = defaultNotifyOwne
         try {
             const peer = await new friends_1.FileFriendStore(path.join((0, identity_1.getAgentRoot)(agentName), "friends")).get(request.friendId);
             const agentRoot = (0, identity_1.getAgentRoot)(agentName);
+            const from = peer?.name ?? "a connected agent";
             if ((0, replay_harness_1.isReplayWindowOpen)(agentRoot, request.friendId)) {
-                (0, replay_harness_1.appendReplayNotice)(agentRoot, { noticeId: request.deliveryId, text: request.content, friendId: request.friendId });
+                (0, replay_harness_1.appendReplayNotice)(agentRoot, { noticeId: request.deliveryId, text: request.noticeKind === "asked_owner" ? ownerNoticeText(request, from) : request.content, friendId: request.friendId });
                 return { status: "delivered_now", detail: "written to the replay sink (replay window open for this peer)" };
             }
-            const from = peer?.name ?? "a connected agent";
-            await notifyOwner({ noticeId: request.deliveryId, text: `Follow-up on a request from ${from}: ${request.content}` });
+            await notifyOwner({ noticeId: request.deliveryId, text: ownerNoticeText(request, from) });
             return { status: "delivered_now", detail: "sent to the owner's Telegram chat as the agent" };
         }
         catch (error) {

package/dist/heart/awaiting/await-alert.js

@@ -74,6 +74,9 @@ function resolveAlertKey(agentRoot, friendId, channel) {
 function buildAlertContent(awaitFile, reason, observation) {
     const condition = awaitFile.condition ?? awaitFile.name;
     const obs = readNonEmpty(observation);
+    if (reason === "asked_owner") {
+        return obs ? `${condition} — ${obs}` : `${condition} — I have asked the owner how to proceed.`;
+    }
     if (reason === "resolved") {
         return obs ? `${condition} — ready. ${obs}` : `${condition} — ready.`;
     }
@@ -120,14 +123,15 @@ async function deliverAwaitAlert(options) {
         });
         return { attempted: false, skipped: "no session key" };
     }
-    const content = buildAlertContent(awaitFile, reason, observation);
+    const content = options.content ?? buildAlertContent(awaitFile, reason, observation);
     const delivery = await (0, cross_chat_delivery_1.deliverCrossChatMessage)({
         friendId,
         channel,
         key,
         content,
         ...(awaitFile.request_id ? { requestId: awaitFile.request_id } : {}),
-        deliveryId: `await:${awaitFile.name}:${reason}`,
+        deliveryId: options.deliveryId ?? `await:${awaitFile.name}:${reason}`,
+        ...(reason === "asked_owner" ? { noticeKind: "asked_owner" } : {}),
         intent: "generic_outreach",
     }, deliveryDeps);
     (0, runtime_1.emitNervesEvent)({

package/dist/heart/awaiting/await-parser.js

@@ -39,7 +39,7 @@ const path = __importStar(require("path"));
 const frontmatter_1 = require("../../util/frontmatter");
 const runtime_1 = require("../../nerves/runtime");
 function isAwaitStatus(value) {
-    return value === "pending" || value === "resolved" || value === "expired" || value === "canceled";
+    return value === "pending" || value === "resolved" || value === "expired" || value === "canceled" || value === "asked_owner";
 }
 function isAwaitMode(value) {
     return value === "full" || value === "quick";
@@ -121,6 +121,9 @@ function parseAwaitFile(content, filePath) {
         last_observation_at_expiry: nonEmptyString(frontmatter.last_observation_at_expiry),
         canceled_at: nonEmptyString(frontmatter.canceled_at),
         cancel_reason: nonEmptyString(frontmatter.cancel_reason),
+        ...(nonEmptyString(frontmatter.asked_at) ? { asked_at: nonEmptyString(frontmatter.asked_at) } : {}),
+        ...(nonEmptyString(frontmatter.ask_question) ? { ask_question: nonEmptyString(frontmatter.ask_question) } : {}),
+        ...(nonEmptyString(frontmatter.ask_choices) ? { ask_choices: nonEmptyString(frontmatter.ask_choices) } : {}),
     };
 }
 function formatFrontmatterValue(value) {

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/dist/repertoire/tools-awaiting.js

@@ -53,6 +53,7 @@ const session_events_1 = require("../heart/session-events");
 const runtime_1 = require("../nerves/runtime");
 const await_parser_1 = require("../heart/awaiting/await-parser");
 const await_alert_1 = require("../heart/awaiting/await-alert");
+const friends_1 = require("@ouro.bot/friends");
 const a2a_await_delivery_1 = require("../heart/awaiting/a2a-await-delivery");
 const pending_1 = require("../mind/pending");
 const router_1 = require("../heart/external-events/router");
@@ -97,6 +98,15 @@ function relationshipScopeFor(ctx, awaitName) {
     }
     return { session: ctx.currentSession, requestId: ctx.relationshipAuthorization?.requestId };
 }
+function readAwaitDoneDefinition(agentRoot, name) {
+    const filePath = awaitDoneFilePath(agentRoot, name);
+    try {
+        return (0, await_parser_1.parseAwaitFile)(fs.readFileSync(filePath, "utf-8"), filePath);
+    }
+    catch {
+        return null;
+    }
+}
 function readAwaitDefinition(agentRoot, name) {
     const filePath = awaitFilePath(agentRoot, name);
     try {
@@ -135,6 +145,169 @@ function resolveDeliveryDeps(agentName) {
     const deps = injected.buildDeliveryDeps ? injected.buildDeliveryDeps(agentName) : defaultDeliveryDeps(agentName);
     return { ...deps, deliverers: { a2a: (0, a2a_await_delivery_1.createA2AAwaitOwnerDeliverer)(agentName), ...deps.deliverers } };
 }
+const ASK_OWNER_MIN_CHOICES = 2;
+const ASK_OWNER_MAX_CHOICES = 4;
+function oneLine(value) {
+    return value.replace(/\s+/gu, " ").trim();
+}
+/**
+ * Validates an ask_owner request. The question and choices are collapsed to single lines because they are archived as
+ * frontmatter, and choices may not contain "|" because the archive joins them with " | ".
+ */
+function parseAskOwner(question, choices) {
+    const cleanQuestion = typeof question === "string" ? oneLine(question) : "";
+    if (!cleanQuestion)
+        return { ok: false, error: "question is required for ask_owner: put the decision to the owner in plain words" };
+    if (!Array.isArray(choices) || choices.length < ASK_OWNER_MIN_CHOICES || choices.length > ASK_OWNER_MAX_CHOICES) {
+        return { ok: false, error: `ask_owner needs ${ASK_OWNER_MIN_CHOICES} to ${ASK_OWNER_MAX_CHOICES} choices` };
+    }
+    const cleanChoices = choices.map((choice) => typeof choice === "string" ? oneLine(choice) : "");
+    if (cleanChoices.some((choice) => !choice))
+        return { ok: false, error: "every ask_owner choice must be a non-empty string" };
+    if (cleanChoices.some((choice) => choice.includes("|")))
+        return { ok: false, error: 'ask_owner choices must not contain "|"' };
+    return { ok: true, question: cleanQuestion, choices: cleanChoices };
+}
+function formatOwnerQuestion(question, choices) {
+    return `${question}\n\n${choices.map((choice) => `- ${choice}`).join("\n")}`;
+}
+function failedAskOwner(agentName, name, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    (0, runtime_1.emitNervesEvent)({ level: "error", component: "repertoire", event: "repertoire.await_ask_owner_error", message: "ask_owner could not reach the owner", meta: { agent: agentName, name, error: detail } });
+    return JSON.stringify({ error: `the owner message could not be sent (${detail}); the await is still pending, so ask_owner can be retried` });
+}
+/** At most this many ask_owner closures per requester in a rolling day, so one requester cannot make the Butler pester the owner. */
+const ASK_OWNER_DAILY_LIMIT = 3;
+const ASK_OWNER_WINDOW_MS = 24 * 60 * 60 * 1000;
+function askLedgerPath(agentRoot) {
+    return path.join(awaitingDir(agentRoot), ".asks.jsonl");
+}
+/** Every ask_owner closure is appended here, because the archive is overwritten when an await name is reused. */
+function recordAsk(agentRoot, entry) {
+    fs.mkdirSync(awaitingDir(agentRoot), { recursive: true });
+    fs.appendFileSync(askLedgerPath(agentRoot), `${JSON.stringify(entry)}\n`, "utf-8");
+}
+function recentAskCount(agentRoot, filer, now) {
+    let raw;
+    try {
+        raw = fs.readFileSync(askLedgerPath(agentRoot), "utf-8");
+    }
+    catch {
+        return 0;
+    }
+    return raw.split("\n").filter((line) => {
+        try {
+            const entry = JSON.parse(line);
+            return (entry.filer ?? null) === filer && typeof entry.at === "string" && now - Date.parse(entry.at) < ASK_OWNER_WINDOW_MS;
+        }
+        catch {
+            return false;
+        }
+    }).length;
+}
+const askOwnerInFlight = new Set();
+/** A friend store that cannot be read makes the filer unknown, which is never the owner; it must not fail the ask. */
+async function lookupFiler(agentRoot, friendId) {
+    try {
+        const friend = friendId ? await new friends_1.FileFriendStore(path.join(agentRoot, "friends")).get(friendId) : null;
+        return { isOwner: Boolean(friend && friend.admissionState === "active" && friend.trustLevel === "family" && friend.capabilityProfileId === "sanctuary-owner"), name: friend?.name ?? null };
+    }
+    catch {
+        return { isOwner: false, name: null };
+    }
+}
+function delivered(alert) {
+    return alert?.delivery?.status === "delivered_now" || alert?.delivery?.status === "queued_for_later";
+}
+/**
+ * The await's condition cannot be met without the owner deciding. The owner is asked once, as the agent, in the
+ * owner's own chat, and only then is the await archived as asked_owner. One notice id per await instance ties every
+ * path together: the A2A owner delivery, the direct owner message and the replay sink all dedupe on it, so a retry after
+ * a crash between send and archive sends nothing twice. An await filed from A2A goes through the A2A owner delivery,
+ * which writes the owner notice (or the replay sink during a replay window); the direct notice is only the fallback
+ * when that path blocked or failed. When someone other than the owner filed the await, the text says whose request it is
+ * about, and a non-A2A filer is also told that the owner was asked (the obligation stays open if that could not be said).
+ */
+async function askOwnerTool(name, observation, question, choices, existing, agentRoot, agentName) {
+    const parsed = parseAskOwner(question, choices);
+    if (!parsed.ok)
+        return JSON.stringify({ error: parsed.error });
+    const inFlightKey = `${agentRoot}\0${name}`;
+    if (askOwnerInFlight.has(inFlightKey))
+        return JSON.stringify({ error: `await "${name}" is already being asked; wait for the owner's reply instead of asking again` });
+    askOwnerInFlight.add(inFlightKey);
+    try {
+        const filerId = existing.filed_for_friend_id ?? null;
+        const filer = await lookupFiler(agentRoot, filerId);
+        if (!filer.isOwner && recentAskCount(agentRoot, filerId, Date.now()) >= ASK_OWNER_DAILY_LIMIT) {
+            return JSON.stringify({ error: `ask_owner limit reached: this requester has already had my owner asked ${ASK_OWNER_DAILY_LIMIT} times in the last day; do not retry ask_owner, resolve with verdict 'no' with an observation and keep polling` });
+        }
+        const isA2A = existing.filed_from === "a2a";
+        const noticeId = `await:${name}:asked_owner:${String(existing.created_at)}`;
+        const question = formatOwnerQuestion(parsed.question, parsed.choices);
+        const ownerText = filer.isOwner ? question : (0, a2a_await_delivery_1.askedOwnerText)(question, filer.name ?? (isA2A ? "a connected agent" : "a friend"));
+        let alert = null;
+        let sent = false;
+        if (isA2A) {
+            try {
+                alert = await (0, await_alert_1.deliverAwaitAlert)({ awaitFile: { ...existing, alert: "a2a" }, reason: "asked_owner", observation: question, content: question, deliveryId: noticeId, agentRoot, agentName, deliveryDeps: resolveDeliveryDeps(agentName) });
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({ level: "error", component: "repertoire", event: "repertoire.await_alert_error", message: "await alert delivery threw", meta: { agent: agentName, name, error: error instanceof Error ? error.message : String(error) } });
+            }
+            sent = delivered(alert);
+        }
+        if (!sent) {
+            try {
+                await (injected.notifyOwner ? injected.notifyOwner(agentName) : (0, a2a_await_delivery_1.defaultNotifyOwner)(agentName))({ noticeId, text: ownerText });
+            }
+            catch (error) {
+                return failedAskOwner(agentName, name, error);
+            }
+        }
+        let friendNotice = null;
+        const tellsFriend = !isA2A && !filer.isOwner && Boolean(filerId);
+        if (tellsFriend) {
+            try {
+                friendNotice = await (0, await_alert_1.deliverAwaitAlert)({ awaitFile: existing, reason: "asked_owner", observation: observation.trim(), content: `About "${existing.condition ?? name}": I have asked the owner how to proceed and will let you know what they decide.`, deliveryId: `${noticeId}:filer`, agentRoot, agentName, deliveryDeps: resolveDeliveryDeps(agentName) });
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({ level: "error", component: "repertoire", event: "repertoire.await_alert_error", message: "await alert delivery threw", meta: { agent: agentName, name, error: error instanceof Error ? error.message : String(error) } });
+            }
+        }
+        const askedAt = new Date().toISOString();
+        const archive = archiveAwait(agentRoot, name, {
+            status: "asked_owner",
+            asked_at: askedAt,
+            ask_question: parsed.question,
+            ask_choices: parsed.choices.join(" | "),
+            resolution_observation: observation.trim(),
+        });
+        /* v8 ignore next -- defensive: archiveAwait only fails on the file-disappears-mid-call race already covered by v8 ignore inside archiveAwait @preserve */
+        if (!archive.ok)
+            return JSON.stringify({ error: archive.error });
+        recordAsk(agentRoot, { filer: filerId, name, at: askedAt });
+        if (!tellsFriend || delivered(friendNotice))
+            fulfillAwaitObligation(agentRoot, archive.file);
+        (0, runtime_1.emitNervesEvent)({
+            component: "repertoire",
+            event: "repertoire.await_asked_owner",
+            message: "await closed by asking the owner",
+            meta: { agent: agentName, name, choices: parsed.choices.length },
+        });
+        const summary = (result) => result ? { attempted: result.attempted, status: result.delivery?.status ?? null, skipped: result.skipped ?? null } : null;
+        return JSON.stringify({
+            verdict: "ask_owner",
+            asked: true,
+            archived: awaitDoneFilePath(agentRoot, name),
+            alert: summary(alert),
+            ...(tellsFriend ? { filerNotice: summary(friendNotice) } : {}),
+        });
+    }
+    finally {
+        askOwnerInFlight.delete(inFlightKey);
+    }
+}
 function fileAwait(args, agentRoot, agentName, sessionFriendId, sessionChannel, sessionKey, requestId) {
     const nameError = validateName(args.name);
     if (nameError)
@@ -245,23 +418,28 @@ function fulfillAwaitObligation(agentRoot, awaitFile) {
     if (awaitFile.obligation_id)
         (0, obligations_1.fulfillObligation)(agentRoot, awaitFile.obligation_id);
 }
-async function resolveAwaitTool(name, verdict, observation, agentRoot, agentName) {
+async function resolveAwaitTool(name, verdict, observation, agentRoot, agentName, ask) {
     const nameError = validateName(name);
     if (nameError)
         return JSON.stringify({ error: nameError });
     const existing = readAwaitDefinition(agentRoot, name);
     if (!existing) {
+        if (verdict === "ask_owner" && readAwaitDoneDefinition(agentRoot, name)?.status === "asked_owner") {
+            return JSON.stringify({ error: `await "${name}" has already asked the owner and is closed; wait for the owner's reply instead of asking again` });
+        }
         return JSON.stringify({ error: `await "${name}" not found in awaiting/` });
     }
     if (existing.status !== "pending") {
         return JSON.stringify({ error: `await "${name}" is not pending (status: ${existing.status})` });
     }
-    if (verdict !== "yes" && verdict !== "no") {
-        return JSON.stringify({ error: `verdict must be exactly "yes" or "no" (got ${JSON.stringify(verdict)}); use "no" with an observation while still waiting` });
+    if (verdict !== "yes" && verdict !== "no" && verdict !== "ask_owner") {
+        return JSON.stringify({ error: `verdict must be exactly "yes", "no", or "ask_owner" (got ${JSON.stringify(verdict)}); use "no" with an observation while still waiting` });
     }
     if (!observation || !observation.trim()) {
         return JSON.stringify({ error: "observation is required" });
     }
+    if (verdict === "ask_owner")
+        return askOwnerTool(name, observation, ask?.question, ask?.choices, existing, agentRoot, agentName);
     if (verdict === "no") {
         // Update runtime state via recordAwaitCheck-style write
         const { recordAwaitCheck } = await Promise.resolve().then(() => __importStar(require("../heart/awaiting/await-runtime-state")));
@@ -535,13 +713,15 @@ exports.awaitingToolDefinitions = [
             type: "function",
             function: {
                 name: "resolve_await",
-                description: "Resolve a pending await with a verdict. verdict='yes' archives and fires the alert. verdict='no' records the observation and continues polling; still pending is always 'no'.",
+                description: "Resolve a pending await with a verdict. verdict='yes' archives and fires the alert. verdict='no' records the observation and continues polling; still pending is always 'no'. verdict='ask_owner' (with question and choices) closes the await and asks my owner to decide, exactly once: use it when the condition cannot be met without the owner deciding, for example a confirmed dead download. Never use ask_owner for \"not yet\" or a merely suspected problem; that is 'no'.",
                 parameters: {
                     type: "object",
                     properties: {
                         name: { type: "string", description: "Await name (filename stem)." },
-                        verdict: { type: "string", enum: ["yes", "no"], description: "Exactly 'yes' if the condition is met. Exactly 'no' for anything else, including still pending, not yet, or unable to tell: send 'no' with an observation and polling continues." },
+                        verdict: { type: "string", enum: ["yes", "no", "ask_owner"], description: "Exactly 'yes' if the condition is met. Exactly 'no' for anything else, including still pending, not yet, or unable to tell: send 'no' with an observation and polling continues. 'ask_owner' only when the condition cannot be met without the owner deciding; it needs question and choices." },
                         observation: { type: "string", description: "One-line summary of what I saw this tick." },
+                        question: { type: "string", description: "Only for ask_owner: the decision I need from my owner, in plain words." },
+                        choices: { type: "array", items: { type: "string" }, minItems: 2, maxItems: 4, description: "Only for ask_owner: 2 to 4 short options the owner can pick from." },
                     },
                     required: ["name", "verdict", "observation"],
                 },
@@ -575,7 +755,7 @@ exports.awaitingToolDefinitions = [
                 if (!binding?.active)
                     return JSON.stringify({ error: "resolve_await is limited to the current relationship request or bound external event" });
             }
-            return resolveAwaitTool(a.name, a.verdict, a.observation, agentRoot, agentName);
+            return resolveAwaitTool(a.name, a.verdict, a.observation, agentRoot, agentName, { question: a.question, choices: a.choices });
         },
         riskProfile: {
             mutates: ["durable_state_write", "external_side_effect"],

package/dist/senses/await-turn-message.js

@@ -54,5 +54,6 @@ function buildAwaitTurnMessage(options) {
     }
     lines.push("");
     lines.push("look around and decide. if the condition is met, call resolve_await with verdict='yes' and a one-line observation. otherwise call resolve_await with verdict='no' and a one-line observation of what i saw this tick.");
+    lines.push("verdicts: 'yes' (condition met), 'no' (not yet or unsure), 'ask_owner' (only when the condition cannot be met without my owner deciding, e.g. a confirmed dead download; give a plain question and 2-4 choices).");
     return lines.join("\n");
 }

package/npm-shrinkwrap.json

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