@ouro.bot/cli 0.1.0-alpha.956 → 0.1.0-alpha.958

package/dist/heart/core.js

@@ -285,6 +285,7 @@ exports.STEP_BUDGET_EXTENSION = 4;
 /** Hard ceiling on the per-turn provider-call budget, however much progress is made. */
 exports.MAX_PROVIDER_ITERATIONS_CEILING = 24;
 const STEP_BUDGET_REPORT_INSTRUCTION = "the step budget for this turn is used up. do not call any more work tools; none of the tool calls in your last message were executed. call settle now with a short progress report: what is done (with evidence from tool results above), what is still in flight, and what you will do next. say you can continue where you left off when the conversation resumes.";
+const STEP_BUDGET_REST_INSTRUCTION = "the step budget for this turn is used up. do not call any more work tools; none of the tool calls in your last message were executed. call rest now with a short note: what is done, what is still open, and what to pick up next time.";
 function continuationCallbacks(callbacks, text) {
     const noop = () => undefined;
     return {
@@ -1208,6 +1209,10 @@ async function runAgent(messages, callbacks, channel, signal, options) {
     let stepBudget = exports.MAX_PROVIDER_ITERATIONS;
     let lastIterationMadeProgress = false;
     let stepReportIteration = null;
+    // The one tool a turn may call after its step budget is used up: settle for conversations, rest for private turns.
+    let stepReportTool = "settle";
+    // A pre-dispatch contract check may reject the same call twice in a turn; after that it is advisory, so a check no call can satisfy never traps the turn.
+    const requiredDispatchRejectionCounts = new Map();
     const budgetExhausted = () => {
         if (providerIterations < stepBudget)
             return false;
@@ -1444,7 +1449,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 .filter((name) => candidateToolNames.has(name)));
             const forcingHistoricalEffect = forcedHistoricalToolNames.size > 0;
             const activeTools = stepReportIteration !== null
-                ? candidateActiveTools.filter((tool) => tool.function.name === "settle")
+                ? candidateActiveTools.filter((tool) => tool.function.name === stepReportTool)
                 : forcingHistoricalEffect
                     ? candidateActiveTools.filter((tool) => forcedHistoricalToolNames.has(tool.function.name))
                     : candidateActiveTools;
@@ -1605,8 +1610,8 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 nextAttemptControls = [];
                 providerIterations += 1;
                 if (stepReportIteration !== null) {
-                    // The progress-report call is the last one: it must settle, or the turn errors.
-                    const settledReport = result.toolCalls.length === 1 && result.toolCalls[0].name === "settle";
+                    // The progress-report call is the last one: it must settle (or rest), or the turn errors.
+                    const settledReport = result.toolCalls.length === 1 && result.toolCalls[0].name === stepReportTool;
                     if (providerIterations > stepReportIteration || (result.toolCalls.length > 0 && !settledReport)) {
                         throw new Error(`provider iteration limit exhausted at response ${providerIterations} before the progress report settled`);
                     }
@@ -1676,20 +1681,22 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 if (thinkingItems.length > 0) {
                     msg._thinking_blocks = thinkingItems;
                 }
-                const settlingNow = result.toolCalls.length === 1 && result.toolCalls[0].name === "settle";
+                const settlingNow = result.toolCalls.length === 1 && (result.toolCalls[0].name === "settle" || result.toolCalls[0].name === "rest");
                 if (stepReportIteration === null && result.toolCalls.length > 0 && !settlingNow && budgetExhausted()) {
-                    if (!candidateToolNames.has("settle")) {
+                    const wrapUpTool = candidateToolNames.has("settle") ? "settle" : candidateToolNames.has("rest") ? "rest" : null;
+                    if (!wrapUpTool) {
                         throw new Error(`provider iteration limit exhausted at response ${stepBudget} before tool execution`);
                     }
-                    // Do not error into the reply: give the model one settle-only call to report progress.
+                    // Do not error into the reply: give the model one settle-only (or rest-only) call to report progress.
                     streamCallbackBuffer?.discard();
                     stepReportIteration = providerIterations + 1;
+                    stepReportTool = wrapUpTool;
                     rejectAttempt(msg, [
                         ...result.toolCalls.map((tc) => ({ role: "tool", tool_call_id: tc.id, content: "not executed: the step budget for this turn is used up." })),
-                        { role: "user", content: STEP_BUDGET_REPORT_INSTRUCTION },
+                        { role: "user", content: wrapUpTool === "settle" ? STEP_BUDGET_REPORT_INSTRUCTION : STEP_BUDGET_REST_INSTRUCTION },
                     ]);
                     callbacks.onClearText?.();
-                    (0, runtime_1.emitNervesEvent)({ level: "warn", component: "engine", event: "engine.step_budget_exhausted", message: "step budget used up; requesting a settle-only progress report", meta: { stepBudget, providerIterations } });
+                    (0, runtime_1.emitNervesEvent)({ level: "warn", component: "engine", event: "engine.step_budget_exhausted", message: `step budget used up; requesting a ${wrapUpTool}-only progress report`, meta: { stepBudget, providerIterations } });
                     continue;
                 }
                 if (result.toolCalls.length > 0)
@@ -2166,14 +2173,16 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         const restArgs = validatedCallArguments.get(result.toolCalls[0]);
                         callbacks.onToolStart("rest", restArgs);
                         // Attention queue gate: reject rest if items remain
+                        // A budget wrap-up rest is final: held work and fresh messages wait for the next turn.
+                        const wrappingUp = stepReportIteration !== null;
                         const attentionQueue = augmentedToolContext?.delegatedOrigins;
-                        if (attentionQueue && attentionQueue.length > 0) {
+                        if (!wrappingUp && attentionQueue && attentionQueue.length > 0) {
                             callbacks.onToolEnd("rest", (0, tools_1.summarizeArgs)("rest", restArgs, toolSelection), false);
                             const gateMessage = "current held-work frame still has unsurfaced items — return each listed item with surface(delegationId=...) before you rest. Older transcript claims are historical; only the current held-work frame is the gate.";
                             rejectToolBatch(msg, [gateMessage]);
                             continue;
                         }
-                        if (hasFreshPendingWork(options) && !freshWorkGateFired) {
+                        if (!wrappingUp && hasFreshPendingWork(options) && !freshWorkGateFired) {
                             freshWorkGateFired = true;
                             callbacks.onToolEnd("rest", (0, tools_1.summarizeArgs)("rest", restArgs, toolSelection), false);
                             const gateMessage = "fresh work arrived for me this turn — inspect the pending messages above and take the next concrete action before you rest.";
@@ -2206,8 +2215,20 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     for (const entry of validCalls) {
                         const requiredArgs = entry.validated.arguments;
                         const rejection = options?.requiredToolCalls?.validateToolCallBeforeDispatch?.(entry.call.name, requiredArgs);
-                        if (rejection)
-                            requiredDispatchRejections.set(entry.call.id, { name: entry.call.name, args: requiredArgs, message: rejection });
+                        if (!rejection)
+                            continue;
+                        const rejectionKey = `${entry.call.name}\0${rejection}`;
+                        const priorRejections = requiredDispatchRejectionCounts.get(rejectionKey) ?? 0;
+                        if (priorRejections >= 2) {
+                            (0, runtime_1.emitNervesEvent)({
+                                level: "warn", component: "engine", event: "engine.required_tool_dispatch_advisory",
+                                message: "required tool dependency rejected twice this turn; letting the call through",
+                                meta: { toolName: entry.call.name },
+                            });
+                            continue;
+                        }
+                        requiredDispatchRejectionCounts.set(rejectionKey, priorRejections + 1);
+                        requiredDispatchRejections.set(entry.call.id, { name: entry.call.name, args: requiredArgs, message: rejection });
                     }
                     if (requiredDispatchRejections.size > 0) {
                         streamCallbackBuffer?.discard();

package/dist/heart/external-events/router.js

@@ -813,8 +813,13 @@ function recordExternalEventInternal(input, options = {}) {
                     && existing.recoveryGrant?.generation === existing.generation && existing.failureProvenance !== undefined
                     && Date.parse(now) - Date.parse(existing.failureProvenance.failedAt) >= EXHAUSTED_RECOVERY_REOPEN_MS
                     && Math.floor(Date.parse(now) / 3_600_000) % EXHAUSTED_RECOVERY_SLOTS === exhaustedRecoverySlot(existing);
-                const shouldWake = !quietInitialReceipt && (!existing || quietBaselineChanged
+                // A recovery is only news to an owner who was told about the incident, or to a turn that asked to watch for it; any other recovery settles here without a model turn.
+                const silentRecovery = input.transition === "recovered" && existing !== null
+                    && existing.disposition?.decision !== "ask" && existing.disposition?.decision !== "report" && existing.disposition?.nextWake.kind !== "on_recovery";
+                const settledRecoveryReopened = existing?.executionState === "handled" && !existing.disposition && existing.transition === "recovered" && input.transition !== "recovered";
+                const shouldWake = !quietInitialReceipt && !silentRecovery && (!existing || quietBaselineChanged || settledRecoveryReopened
                     || (existing.disposition ? predicateMatches(existing.disposition, input, revision) : existing.executionState === "dead_letter" && (revision !== existing.observationRevision || exhaustedRecoveryReopens)));
+                const settles = quietInitialReceipt || silentRecovery;
                 const generation = existing ? existing.generation + (shouldWake ? 1 : 0) : 1;
                 const record = {
                     schemaVersion: 2,
@@ -834,17 +839,17 @@ function recordExternalEventInternal(input, options = {}) {
                     observationRevision: revision,
                     observationDigest: digest,
                     transition: input.transition ?? (existing ? "unchanged" : "opened"),
-                    executionState: quietInitialReceipt ? "handled" : shouldWake ? "received" : existing.executionState,
+                    executionState: settles ? "handled" : shouldWake ? "received" : existing.executionState,
                     generation,
-                    attemptCount: shouldWake || quietInitialReceipt ? 0 : existing.attemptCount,
-                    claimOwner: shouldWake || quietInitialReceipt ? null : existing.claimOwner,
-                    claimExpiresAt: shouldWake || quietInitialReceipt ? null : existing.claimExpiresAt,
-                    nextAttemptAt: shouldWake || quietInitialReceipt ? null : existing.nextAttemptAt,
-                    lastError: shouldWake || quietInitialReceipt ? null : existing.lastError,
-                    ...(!shouldWake && !quietInitialReceipt && existing?.failureProvenance ? { failureProvenance: existing.failureProvenance } : {}),
-                    ...(!shouldWake && !quietInitialReceipt && existing?.recoveryGrant ? { recoveryGrant: existing.recoveryGrant } : {}),
-                    disposition: shouldWake || quietInitialReceipt ? null : existing.disposition,
-                    pendingObservation: shouldWake || quietInitialReceipt ? null : existing.pendingObservation,
+                    attemptCount: shouldWake || settles ? 0 : existing.attemptCount,
+                    claimOwner: shouldWake || settles ? null : existing.claimOwner,
+                    claimExpiresAt: shouldWake || settles ? null : existing.claimExpiresAt,
+                    nextAttemptAt: shouldWake || settles ? null : existing.nextAttemptAt,
+                    lastError: shouldWake || settles ? null : existing.lastError,
+                    ...(!shouldWake && !settles && existing?.failureProvenance ? { failureProvenance: existing.failureProvenance } : {}),
+                    ...(!shouldWake && !settles && existing?.recoveryGrant ? { recoveryGrant: existing.recoveryGrant } : {}),
+                    disposition: shouldWake || settles ? null : existing.disposition,
+                    pendingObservation: shouldWake || settles ? null : existing.pendingObservation,
                     dispatchEnabled: options.dispatchEnabled ?? existing?.dispatchEnabled ?? true,
                     shouldWake,
                     ...(persistedRetention ? { retentionSummary: persistedRetention } : {}),
@@ -1399,7 +1404,10 @@ function settleExternalEventFailureIfOwned(recordPath, input) {
             || record.generation !== input.expectedGeneration) {
             return { settled: false, record };
         }
-        const settled = commitMutation(recordPath, retryState(record, now, 5, 1_000, input.error, input.failureClass), now);
+        const next = input.deferUntil
+            ? { ...record, executionState: "retry_wait", claimOwner: null, claimExpiresAt: null, nextAttemptAt: input.deferUntil, attemptCount: Math.max(0, record.attemptCount - 1), lastError: input.error.slice(0, 1_000), shouldWake: false }
+            : retryState(record, now, 5, 1_000, input.error, input.failureClass);
+        const settled = commitMutation(recordPath, next, now);
         return { settled: true, record: settled };
     });
 }

package/dist/repertoire/house-sweep.js

@@ -185,7 +185,7 @@ function summarizeArr(service, queuePayload, missingPayload, historyPayload, now
             id, area: "downloads", severity: "warn", refs,
             next: series ? "fix" : "owner",
             summary: `${label} download of ${name} is stuck at ${percent}% (${release}): ${problem}`,
-            fingerprint: fingerprintOf(id, problem.startsWith("no progress") ? "frozen" : problem),
+            fingerprint: fingerprintOf(id, "stuck"),
             ...(series ? { fix: { tool: "media_fill_missing", args: { service_id: subjectId }, note: "keeps the partial download; replaces it only when a seeded alternative is grabbed" } } : {}),
         });
     }
@@ -228,7 +228,7 @@ function summarizeArr(service, queuePayload, missingPayload, historyPayload, now
         findings.push({
             id, area: "missing", severity: "info", next: "fix",
             summary: series ? `${entry.name}: ${entry.count} monitored episode${entry.count === 1 ? "" : "s"} missing, the oldest aired ${days} days ago` : `${entry.name}: monitored movie still missing after ${days} days`,
-            fingerprint: fingerprintOf(id, String(entry.count)),
+            fingerprint: fingerprintOf(id, "missing"),
             fix: series
                 ? { tool: "media_fill_missing", args: { service_id: subjectId }, note: "searches, grabs a seeded release, imports what finished" }
                 : { tool: "media_search_now", args: { kind: "movie", service_id: subjectId }, note: "triggers a Radarr search" },
@@ -272,7 +272,7 @@ async function sweepHost(sanctuary, policyStates, nowMs, findings) {
     const capacity = (id, label, percent) => {
         if (percent === null || percent < exports.CAPACITY_PERCENT)
             return;
-        findings.push({ id, area: "disk", severity: percent >= exports.CRITICAL_CAPACITY_PERCENT ? "critical" : "warn", next: "owner", summary: `${label} is ${percent}% full`, fingerprint: fingerprintOf(id, String(Math.floor(percent))) });
+        findings.push({ id, area: "disk", severity: percent >= exports.CRITICAL_CAPACITY_PERCENT ? "critical" : "warn", next: "owner", summary: `${label} is ${percent}% full`, fingerprint: fingerprintOf(id, percent >= exports.CRITICAL_CAPACITY_PERCENT ? "critical" : "full") });
     };
     capacity("disk:array:capacity", "the array", summary.arrayUsedPercent);
     for (const share of list(storage?.shares).map(dict))
@@ -285,7 +285,7 @@ async function sweepHost(sanctuary, policyStates, nowMs, findings) {
             findings.push({ id: `${id}:smart`, area: "disk", severity: "critical", next: "owner", summary: `${text(disk.name)} reports a failed SMART status`, fingerprint: fingerprintOf(`${id}:smart`, "failed") });
         const temperature = num(disk.temperatureC);
         if (temperature !== null && temperature >= exports.TEMPERATURE_C)
-            findings.push({ id: `${id}:temperature`, area: "disk", severity: "warn", next: "owner", summary: `${text(disk.name)} is ${temperature}C`, fingerprint: fingerprintOf(`${id}:temperature`, String(Math.floor(temperature / 5))) });
+            findings.push({ id: `${id}:temperature`, area: "disk", severity: "warn", next: "owner", summary: `${text(disk.name)} is ${temperature}C`, fingerprint: fingerprintOf(`${id}:temperature`, "hot") });
     }
     const parity = dict(disks?.parity);
     summary.parity = text(parity.result) || null;
@@ -294,7 +294,7 @@ async function sweepHost(sanctuary, policyStates, nowMs, findings) {
     if (disks) {
         const result = summary.parity;
         if (result === "failed")
-            findings.push({ id: "parity:result", area: "parity", severity: "critical", next: "owner", summary: `the last parity check failed (${num(parity.errors) ?? "unknown"} errors)`, fingerprint: fingerprintOf("parity:result", `failed:${num(parity.errors)}`) });
+            findings.push({ id: "parity:result", area: "parity", severity: "critical", next: "owner", summary: `the last parity check failed (${num(parity.errors) ?? "unknown"} errors)`, fingerprint: fingerprintOf("parity:result", "failed") });
         else if (result !== "in_progress" && (summary.parityAgeDays === null || summary.parityAgeDays >= exports.PARITY_MAX_AGE_DAYS))
             findings.push({ id: "parity:age", area: "parity", severity: "warn", next: "owner", summary: summary.parityAgeDays === null ? "parity check age is unknown" : `the last parity check was ${summary.parityAgeDays} days ago`, fingerprint: fingerprintOf("parity:age", summary.parityAgeDays === null ? "unknown" : "old") });
     }
@@ -434,10 +434,12 @@ async function runHouseSweep(deps) {
     })
         .sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] || a.id.localeCompare(b.id));
     if (!deps.replay) {
-        // A finding that is gone is forgotten, so it is told again if it comes back.
-        // ...but only when its source was readable: an outage must not make every finding look new on recovery.
+        // A finding that has been gone for REMIND_DAYS is forgotten, so it is told again if it comes back after that.
+        // A brief disappearance (or an unreadable source) keeps the entry, so a flickering finding never returns as "new".
         const present = new Set(ordered.map((finding) => finding.id));
-        const kept = Object.fromEntries(Object.entries(ledger).filter(([id]) => present.has(id) || sourcesFor(id).some((source) => sources[source] !== "ok")));
+        const kept = Object.fromEntries(Object.entries(ledger).filter(([id, told]) => present.has(id)
+            || sourcesFor(id).some((source) => sources[source] !== "ok")
+            || nowMs - Date.parse(told.reportedAt) < exports.REMIND_DAYS * DAY_MS));
         if (Object.keys(kept).length !== Object.keys(ledger).length)
             (0, exports.writeLedger)(deps.agentRoot, kept);
     }

package/dist/repertoire/tools-continuity.js

@@ -50,11 +50,12 @@ const externalEventDispositionProperties = {
     expectedGeneration: { type: "number", description: "Exact generation shown in the external-event turn" },
     classifiedRevision: { type: "string", description: "Exact observation revision investigated in this turn" },
     classification: { type: "string", enum: ["expected", "needs_attention", "adopted", "snoozed", "dismissed_until_change", "resolved"] },
-    stewardPolicyKind: { type: "string", enum: ["current", "none"], description: "Use current with the exact live policy key/version, or none only for a fresh observation with no applicable policy" },
+    stewardPolicyKind: { type: "string", enum: ["current", "none"], description: "Use current with the exact live policy key/version when one applies; otherwise use none. Any event may be closed with none." },
     stewardPolicyKey: { type: "string", description: "Exact current policy key used for this decision" },
     stewardPolicyVersion: { type: "number", description: "Exact current policy version used for this decision" },
     decision: { type: "string", enum: ["silent", "act", "ask", "report"] },
-    reason: { type: "string", description: "Short plain-language reason for the decision" },
+    reason: { type: "string", description: "Internal audit note for the decision; never shown to the owner" },
+    owner_message: { type: "string", description: "Required for ask or report: the exact short plain message the owner reads, as you would text a friend. No ids, leases, generations, revisions or receipts." },
     nextWake: { type: "string", enum: ["on_change", "on_escalation", "on_recovery", "at"], description: "Use on_change unless you already called await_condition for this exact event and are supplying its awaitId" },
     wakeAt: { type: "string", description: "ISO time required only when nextWake=at" },
     awaitId: { type: "string", description: "Existing await_condition receipt required when nextWake=at; never invent one" },
@@ -70,6 +71,8 @@ const externalEventDispositionBatchSchema = {
     description: "All exact leases from one coalesced external-event turn",
     items: { type: "object", properties: externalEventDispositionProperties, required: externalEventDispositionRequired, additionalProperties: false },
 };
+// The owner reads owner_message verbatim, so internal bookkeeping words never reach them.
+const OWNER_MESSAGE_FORBIDDEN = /\b(generation|lease|revision|receipt|disposition|claimOwner|recordPath)s?\b|[\u200b-\u200f\u202a-\u202e\u2060-\u206f\ufeff]/iu;
 function prepareExternalEventDisposition(a, ctx) {
     const agentName = (0, identity_1.getAgentName)();
     const agentEventRoot = path.resolve((0, router_1.getExternalEventRoot)(), agentName);
@@ -99,6 +102,7 @@ function prepareExternalEventDisposition(a, ctx) {
     const policyVersion = Number(a.stewardPolicyVersion);
     const policyKind = String(a.stewardPolicyKind ?? "");
     const reason = String(a.reason ?? "").trim();
+    const ownerText = String(a.owner_message ?? "").trim();
     if (!reason || (policyKind !== "none" && (!Number.isSafeInteger(policyVersion) || policyVersion < 1))
         || !["current", "none"].includes(policyKind)
         || !["expected", "needs_attention", "adopted", "snoozed", "dismissed_until_change", "resolved"].includes(classification)
@@ -113,8 +117,6 @@ function prepareExternalEventDisposition(a, ctx) {
     const policy = (0, steward_policy_1.readStewardPolicy)(agentRoot);
     let stewardPolicy;
     if (policyKind === "none") {
-        if (record.transition !== "opened")
-            throw new Error("External event no-policy disposition requires a fresh observation");
         stewardPolicy = { kind: "none" };
     }
     else {
@@ -178,15 +180,19 @@ function prepareExternalEventDisposition(a, ctx) {
         finish: async () => {
             let ownerMessage;
             if (decision === "ask" || decision === "report") {
-                if (Buffer.byteLength(reason, "utf8") > 1_200)
+                if (!ownerText)
+                    throw new Error("ask and report need owner_message: the short plain text the owner will read");
+                if (Buffer.byteLength(ownerText, "utf8") > 1_200)
                     throw new Error("External event owner message must be phone-sized");
+                if (OWNER_MESSAGE_FORBIDDEN.test(ownerText))
+                    throw new Error("owner_message must be plain words for the owner, with no internal ids, leases, generations, revisions, receipts or hidden characters");
                 if (!ctx?.externalEventEffects)
                     throw new Error("External event owner delivery is unavailable");
                 // The whole dispatched batch shares one owner message; the delivery port settles later decisions as covered by it.
                 const relatedEvents = [turnContext, ...(turnContext.relatedEvents ?? [])]
                     .filter((event) => path.resolve(event.recordPath) !== recordPath)
                     .map((event) => ({ source: event.source, eventId: event.eventId, generation: event.generation }));
-                const delivered = await ctx.externalEventEffects.deliverOwnerDecision({ source: record.source, eventId: record.eventId, generation: record.generation, text: reason, relatedEvents });
+                const delivered = await ctx.externalEventEffects.deliverOwnerDecision({ source: record.source, eventId: record.eventId, generation: record.generation, text: ownerText, relatedEvents });
                 ownerMessage = { status: delivered.status, effectKey: delivered.effectKey };
             }
             const handled = (0, router_1.commitExternalEventDisposition)(recordPath, {
@@ -220,7 +226,7 @@ exports.continuityToolDefinitions = [
             type: "function",
             function: {
                 name: "external_event_disposition",
-                description: "Classify the exact external-event generation I just investigated. An ask or report is the sole owner-delivery path and sends reason once for this receipt; silent and act only record the disposition. In a batch, only the first ask or report sends a message and the later ones are recorded as covered by it, so write that first reason to cover every listed lease.",
+                description: "Classify the exact external-event generation I just investigated. An ask or report is the sole owner-delivery path and sends owner_message once for this receipt; reason stays internal. silent and act only record the disposition. In a batch, only the first ask or report sends a message and the later ones are recorded as covered by it, so write that first owner_message to cover every listed incident.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -396,7 +402,7 @@ exports.continuityToolDefinitions = [
                         incidentKey: { type: "string", description: "Stable incident key within the source" },
                         classifiedRevision: { type: "string", description: "Observation revision classified by the agent" },
                         correlationKey: { type: "string", description: "Optional key relating several incidents to one concern" },
-                        expectedUpdatedAt: { type: "string", description: "Optional Care updatedAt value for CAS fencing" },
+                        expectedUpdatedAt: { type: "string", description: "The Care's current updatedAt, copied from the last care_manage result. Required for bind_incident and resolve_incident; optional for update." },
                         currentRisk: { type: "string", description: "Current material risk for this Care, or an empty string to clear it" },
                         nextCheckAt: { type: "string", description: "Exact ISO time of the next owned check" },
                     },
@@ -442,7 +448,7 @@ exports.continuityToolDefinitions = [
             }
             else if (a.action === "bind_incident") {
                 if (!a.expectedUpdatedAt)
-                    throw new Error("Care incident binding requires expectedUpdatedAt");
+                    throw new Error("bind_incident requires expectedUpdatedAt: copy the Care's current updatedAt from the last care_manage result");
                 result = (0, cares_1.bindCareIncident)(agentRoot, a.id, {
                     source: a.source,
                     incidentKey: a.incidentKey,
@@ -452,7 +458,7 @@ exports.continuityToolDefinitions = [
             }
             else if (a.action === "resolve_incident") {
                 if (!a.expectedUpdatedAt)
-                    throw new Error("Care incident resolution requires expectedUpdatedAt");
+                    throw new Error("resolve_incident requires expectedUpdatedAt: copy the Care's current updatedAt from the last care_manage result");
                 result = (0, cares_1.resolveCareIncident)(agentRoot, a.id, {
                     source: a.source,
                     incidentKey: a.incidentKey,

package/dist/senses/private-runtime-worker.js

@@ -40,6 +40,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const private_runtime_1 = require("./private-runtime");
 const router_1 = require("../heart/external-events/router");
+const telegram_handoff_1 = require("./telegram-handoff");
 const runtime_1 = require("../nerves/runtime");
 const identity_1 = require("../heart/identity");
 const pending_1 = require("../mind/pending");
@@ -167,6 +168,50 @@ function reserveHabitAutonomyBudget(habitRun, nowIso) {
         now: nowIso,
     }, (0, autonomy_budget_1.resolveAutonomyBudgetPolicy)(habitRun.agentRoot, agentName));
 }
+/**
+ * External-event turns are paid model work, so they draw on their own daily allowance (the agent's
+ * habitPaidTurnsPerDay, counted under the "external-events" name so a busy event day cannot starve a
+ * habit) and share one storm breaker: three failed event turns within ten minutes pause event turns
+ * for thirty minutes.
+ */
+const EXTERNAL_EVENT_BUDGET_NAME = "external-events";
+function externalEventStorm(agentName) {
+    return {
+        agent: agentName,
+        triggerType: "habit",
+        sourceKind: "private-runtime",
+        senseOrHabit: EXTERNAL_EVENT_BUDGET_NAME,
+        provider: "model",
+        target: { kind: EXTERNAL_EVENT_BUDGET_NAME },
+        normalizedErrorName: "external_event_turn_failed",
+        normalizedErrorCode: "turn_failed",
+        codeLocation: "private-runtime-worker",
+        idempotencyBucket: EXTERNAL_EVENT_BUDGET_NAME,
+    };
+}
+/** A blocked event turn waits this long (the breaker's block length) and keeps its retry attempts. */
+const EXTERNAL_EVENT_BLOCKED_DEFER_MS = 30 * 60_000;
+function reserveExternalEventAutonomyBudget(event, nowIso) {
+    // Disk, parity and array failures always get a turn: the owner must hear about them even on a busy day.
+    if ([event, ...(event.relatedEvents ?? [])].some((member) => (0, telegram_handoff_1.isCriticalNoticeKey)(member.eventId)))
+        return null;
+    const agentRoot = (0, identity_1.getAgentRoot)();
+    const agentName = (0, identity_1.getAgentName)();
+    return (0, autonomy_budget_1.reserveAutonomyBudget)(agentRoot, {
+        agent: agentName,
+        triggerType: "habit",
+        sourceKind: "private-runtime",
+        senseOrHabit: EXTERNAL_EVENT_BUDGET_NAME,
+        target: { kind: EXTERNAL_EVENT_BUDGET_NAME },
+        idempotencyKey: `event:${event.recordPath}:${event.generation}:${event.claimOwner}`,
+        now: nowIso,
+        storm: externalEventStorm(agentName),
+    }, (0, autonomy_budget_1.resolveAutonomyBudgetPolicy)(agentRoot, agentName));
+}
+function recordExternalEventTurnFailure(nowIso) {
+    const agentRoot = (0, identity_1.getAgentRoot)();
+    (0, autonomy_budget_1.recordAutonomyFailure)(agentRoot, { ...externalEventStorm((0, identity_1.getAgentName)()), occurredAt: nowIso }, (0, autonomy_budget_1.resolveAutonomyBudgetPolicy)(agentRoot, (0, identity_1.getAgentName)()));
+}
 /**
  * Habit recursion detector thresholds. This protects against the *external*
  * IPC self-loop where heartbeat-shaped messages get re-issued faster
@@ -537,7 +582,9 @@ function createPrivateRuntimeWorker(runTurn = (options) => (0, private_runtime_1
                         const turnStartedAt = new Date(nowSource()).toISOString();
                         const autonomyDecision = currentHabitRun && !currentHabitRun.blockedReason
                             ? reserveHabitAutonomyBudget(currentHabitRun, turnStartedAt)
-                            : null;
+                            : currentExternalEvent
+                                ? reserveExternalEventAutonomyBudget(currentExternalEvent, turnStartedAt)
+                                : null;
                         if (currentHabitRun)
                             recordHabitStartIfNeeded(currentHabitRun);
                         if (currentHabitRun?.blockedReason) {
@@ -620,15 +667,20 @@ function createPrivateRuntimeWorker(runTurn = (options) => (0, private_runtime_1
                             : blockedAutonomyTurn || turnOutcome === "blocked" || turnOutcome === "suspended"
                                 ? "external-event turn was blocked"
                                 : "external-event turn completed without a terminal disposition";
+                        const settledAt = nowSource();
+                        const deferUntil = blockedAutonomyTurn ? new Date(settledAt + EXTERNAL_EVENT_BLOCKED_DEFER_MS).toISOString() : undefined;
                         let settledIncomplete = false;
                         for (const member of [currentExternalEvent, ...(currentExternalEvent.relatedEvents ?? [])]) {
                             const result = (0, router_1.settleExternalEventFailureIfOwned)(member.recordPath, {
                                 owner: member.claimOwner,
                                 expectedGeneration: member.generation,
                                 error: failureReason,
+                                ...(deferUntil ? { deferUntil } : {}),
                             });
                             settledIncomplete = result.settled || settledIncomplete;
                         }
+                        if (!blockedAutonomyTurn && (turnErrors.length > 0 || turnOutcome === "errored" || settledIncomplete))
+                            recordExternalEventTurnFailure(new Date(settledAt).toISOString());
                         if (settledIncomplete && turnErrors.length === 0)
                             turnErrors.push(failureReason);
                     }

package/dist/senses/sanctuary-health-acceptance-probe.js

@@ -547,7 +547,7 @@ async function runSanctuaryHealthAcceptanceProbe(input, dependencies = createSan
                 }
                 const runPhase = async (name, trigger, fixtureStatus, fetchImpl, now) => {
                     const sweep = (0, sanctuary_health_1.createSanctuaryHealthSweep)({
-                        toolContext: dependencies.toolContext, statePath, fetch: fetchImpl, now: () => now, lease,
+                        toolContext: dependencies.toolContext, statePath, fetch: fetchImpl, now: () => now, lease, endpointDebounce: false,
                         acceptanceEventMeta: () => ({ scenarioHandleDigest: input.scenarioHandleDigest }),
                     });
                     await (0, sanctuary_health_runner_1.runSanctuaryHealthHabit)("sanctuary", {

package/dist/senses/sanctuary-health.js

@@ -226,6 +226,7 @@ function load(filePath) {
             lastDigestDay: value.lastDigestDay,
             updatedAt: value.updatedAt,
             ...(value.pendingRecovered?.length ? { pendingRecovered: value.pendingRecovered } : {}),
+            ...(endpointFailuresOf(value.endpointFailures) ? { endpointFailures: endpointFailuresOf(value.endpointFailures) } : {}),
             outbox: value.outbox ? { ...value.outbox, kind: value.outbox.kind ?? "legacy_unknown" } : null,
             indeterminateDeliveries: (value.indeterminateDeliveries ?? []).map((delivery) => ({ ...delivery, kind: delivery.kind ?? "legacy_unknown" })),
             deliveredReceipts: (value.deliveredReceipts ?? []).map((receipt) => ({ ...receipt, kind: receipt.kind ?? "legacy_unknown" })),
@@ -242,6 +243,13 @@ function load(filePath) {
 function readSanctuaryHealthState(filePath) {
     return load(filePath);
 }
+// A malformed failure counter only delays an endpoint incident by one sweep, so it is dropped rather than treated as corrupt state.
+function endpointFailuresOf(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const entries = Object.entries(value).filter(([, count]) => Number.isSafeInteger(count) && count > 0);
+    return entries.length > 0 ? Object.fromEntries(entries) : null;
+}
 function save(filePath, state) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     const temporary = `${filePath}.tmp-${process.pid}-${(0, node_crypto_1.randomUUID)()}`;
@@ -295,6 +303,16 @@ async function probeSanctuaryEndpoint(url, fetchImpl = fetch) {
 }
 function createSanctuaryHealthSweep(options) {
     const fetchImpl = options.fetch ?? fetch;
+    const endpointRetryDelayMs = options.endpointRetryDelayMs ?? 3_000;
+    const endpointDebounce = options.endpointDebounce ?? true;
+    const endpointFailuresToOpen = endpointDebounce ? 2 : 1;
+    const probeWithRetry = async (url) => {
+        const first = await probeSanctuaryEndpoint(url, fetchImpl);
+        if (first.ok || !endpointDebounce)
+            return first;
+        await new Promise((resolve) => setTimeout(resolve, endpointRetryDelayMs));
+        return probeSanctuaryEndpoint(url, fetchImpl);
+    };
     const now = options.now ?? (() => new Date());
     const acceptanceEventMeta = options.acceptanceEventMeta ?? (() => (0, sanctuary_acceptance_marker_1.sanctuaryAcceptanceEventMeta)("sanctuary"));
     const runSweep = async () => {
@@ -313,7 +331,7 @@ function createSanctuaryHealthSweep(options) {
             throw new Error("Sanctuary health runtime is unavailable");
         const [containersResult, storageResult, disksResult, notificationsResult, endpoints] = await Promise.all([
             runtime.listContainers(), runtime.getStorage(), runtime.getDisks(), runtime.getNotifications(),
-            Promise.all(exports.SANCTUARY_PUBLIC_ENDPOINTS.map((url) => probeSanctuaryEndpoint(url, fetchImpl))),
+            Promise.all(exports.SANCTUARY_PUBLIC_ENDPOINTS.map((url) => probeWithRetry(url))),
         ]);
         const incidents = new Map();
         const add = (id, rawSummary) => {
@@ -364,13 +382,20 @@ function createSanctuaryHealthSweep(options) {
         const notifications = record(notificationsResult)?.ok ? record(record(notificationsResult)?.data)?.unacknowledged : null;
         if (!Array.isArray(notifications))
             add("notifications:unavailable", "notification status is unavailable");
+        // Informational (Unraid "normal") notifications are not incidents; warnings and alerts are.
         else
             for (const item of notifications)
-                add(`notification:${item.id}`, `unacknowledged notification: ${item.title || item.id}`);
-        for (const endpoint of endpoints)
-            if (!endpoint.ok)
-                add(`endpoint:${endpoint.url}`, `${endpoint.url} returned ${endpoint.status || "no response"}`);
+                if (item.severity !== "info")
+                    add(`notification:${item.id}`, `unacknowledged notification: ${item.title || item.id}`);
         const previous = load(options.statePath);
+        const endpointFailures = {};
+        for (const endpoint of endpoints) {
+            if (endpoint.ok)
+                continue;
+            endpointFailures[endpoint.url] = (previous.endpointFailures?.[endpoint.url] ?? 0) + 1;
+            if (endpointFailures[endpoint.url] >= endpointFailuresToOpen)
+                add(`endpoint:${endpoint.url}`, `${endpoint.url} returned ${endpoint.status || "no response"}`);
+        }
         const current = Object.fromEntries([...incidents.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([id, incident]) => {
             const prior = previous.incidents[id];
             const transition = !prior ? "opened" : prior.observationRevision === incident.observationRevision ? "unchanged" : "changed";
@@ -401,6 +426,7 @@ function createSanctuaryHealthSweep(options) {
             lastDigestDay: null,
             updatedAt: now().toISOString(),
             ...(unacknowledgedRecovered.length > 0 ? { pendingRecovered: unacknowledgedRecovered } : {}),
+            ...(Object.keys(endpointFailures).length > 0 ? { endpointFailures } : {}),
             outbox: null,
             indeterminateDeliveries: [],
             deliveredReceipts: previous.deliveredReceipts,

package/dist/senses/telegram-handoff.js

@@ -33,10 +33,17 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OWNER_CHAT_HANDOFF_MS = void 0;
+exports.QUIET_HOURS = exports.PROACTIVE_DAILY_CAP = exports.OWNER_CHAT_HANDOFF_MS = void 0;
 exports.ownerChatHandedOff = ownerChatHandedOff;
 exports.readHeldNotices = readHeldNotices;
 exports.writeHeldNotices = writeHeldNotices;
+exports.isQuietHour = isQuietHour;
+exports.isCriticalNoticeKey = isCriticalNoticeKey;
+exports.proactiveHoldReason = proactiveHoldReason;
+exports.recordProactiveSend = recordProactiveSend;
+exports.foldHeldNotices = foldHeldNotices;
+exports.readReleasedHeldKeys = readReleasedHeldKeys;
+exports.recordReleasedHeldKeys = recordReleasedHeldKeys;
 /**
  * Ari sometimes hands his Telegram chat to someone else ("I'm going to hand you to my wife, Rachel"). For a while after that,
  * the chat is that person's conversation, so house notices (an outage, a recovery) wait instead of landing in it
@@ -45,6 +52,7 @@ exports.writeHeldNotices = writeHeldNotices;
  */
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
 const session_events_1 = require("../heart/session-events");
 const runtime_1 = require("../nerves/runtime");
 exports.OWNER_CHAT_HANDOFF_MS = 2 * 60 * 60 * 1000;
@@ -78,3 +86,69 @@ function writeHeldNotices(filePath, notices) {
     fs.renameSync(temporary, filePath);
     (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.telegram_held_notices_saved", message: "saved the house notices held during a handoff", meta: { held: notices.length } });
 }
+/**
+ * Proactive pacing: at most PROACTIVE_DAILY_CAP unprompted owner messages per local day, and none in quiet hours
+ * (23:00-08:00 local), except critical ones (array or disk failure, parity errors). A held message waits in the same
+ * held-notice file and goes out, folded into one message, at the next allowed moment.
+ */
+exports.PROACTIVE_DAILY_CAP = 3;
+exports.QUIET_HOURS = { start: 23, end: 8 };
+const CRITICAL_NOTICE = /\b(?:disk:[^"\s]*:smart|parity:|disk:array:state)/u;
+function localParts(now, timeZone) {
+    const parts = Object.fromEntries(new Intl.DateTimeFormat("en-CA", { timeZone, year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", hourCycle: "h23" })
+        .formatToParts(now).map((part) => [part.type, part.value]));
+    return { day: `${parts.year}-${parts.month}-${parts.day}`, hour: Number(parts.hour) };
+}
+function isQuietHour(now, pacing) {
+    const { hour } = localParts(now, pacing.timeZone);
+    return hour >= exports.QUIET_HOURS.start || hour < exports.QUIET_HOURS.end;
+}
+function isCriticalNoticeKey(key) {
+    return CRITICAL_NOTICE.test(key);
+}
+function readProactiveLedger(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        return typeof parsed.day === "string" && Number.isSafeInteger(parsed.count) ? { day: parsed.day, count: parsed.count } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Why a non-critical proactive message must wait now, or null when it may go. */
+function proactiveHoldReason(ledgerPath, now, pacing) {
+    if (isQuietHour(now, pacing))
+        return "quiet_hours";
+    const ledger = readProactiveLedger(ledgerPath);
+    return ledger?.day === localParts(now, pacing.timeZone).day && ledger.count >= exports.PROACTIVE_DAILY_CAP ? "daily_cap" : null;
+}
+function recordProactiveSend(ledgerPath, now, pacing) {
+    const day = localParts(now, pacing.timeZone).day;
+    const ledger = readProactiveLedger(ledgerPath);
+    fs.mkdirSync(path.dirname(ledgerPath), { recursive: true });
+    fs.writeFileSync(ledgerPath, JSON.stringify({ day, count: ledger?.day === day ? ledger.count + 1 : 1 }), { mode: 0o600 });
+}
+/** Several held notices go out as one message so a quiet night never becomes a morning burst. */
+function foldHeldNotices(held) {
+    if (held.length === 1)
+        return held[0];
+    return { key: `held-batch:${(0, node_crypto_1.createHash)("sha256").update(held.map((notice) => notice.key).join("\0")).digest("hex").slice(0, 32)}`, text: ["While you were away:", ...held.map((notice) => `- ${notice.text}`)].join("\n") };
+}
+const RELEASED_KEYS_LIMIT = 500;
+/** Keys of held notices that went out inside a folded batch, so a retried decision sees its message already exists. */
+function readReleasedHeldKeys(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        return Array.isArray(parsed) ? parsed.filter((entry) => typeof entry === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+function recordReleasedHeldKeys(filePath, keys) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const next = [...readReleasedHeldKeys(filePath).filter((key) => !keys.includes(key)), ...keys].slice(-RELEASED_KEYS_LIMIT);
+    const temporary = `${filePath}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify(next), { mode: 0o600 });
+    fs.renameSync(temporary, filePath);
+}