@ouro.bot/cli 0.1.0-alpha.955 → 0.1.0-alpha.957

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

@@ -259,8 +259,8 @@ exports.COMMAND_REGISTRY = {
     },
     auth: {
         category: "Auth",
-        description: "Set up or verify agent credentials",
-        usage: "ouro auth [verify] [--agent <name>] [--provider <provider>]",
+        description: "Set up or verify agent credentials. For Anthropic API-key mode (for example through a credit gateway), pass --api-key-file <path> (use /dev/stdin to pipe it) and optionally --base-url <url>; the key is never taken from the command line.",
+        usage: "ouro auth [verify] [--agent <name>] [--provider <provider>] [--api-key-file <path> [--base-url <url>]]",
         example: "ouro auth",
         subcommands: ["verify"],
     },
@@ -358,6 +358,13 @@ exports.COMMAND_REGISTRY = {
         example: "ouro session list",
         subcommands: ["list"],
     },
+    gateway: {
+        category: "System",
+        description: "Run the credit gateway: one master key for agents, upstream Anthropic API keys spent in a fixed order",
+        usage: "ouro gateway serve --keys-dir <dir> [--host <host>] [--port <port>]",
+        example: "ouro gateway serve --keys-dir /mnt/user/appdata/credit-gateway/keys",
+        subcommands: ["serve"],
+    },
     mcp: {
         category: "System",
         description: "Interact with MCP servers",
@@ -497,6 +504,11 @@ const SUBCOMMAND_HELP = {
         usage: "ouro a2a onboard [--agent <name>] (--card-url <url>|--did <did:key> --name <name>) [--trust <level>] [--name <name>]",
         example: "ouro a2a onboard --agent <agent> --card-url https://peer.example/.well-known/agent-card.json --trust friend",
     },
+    "gateway serve": {
+        description: "Run the credit gateway in the foreground. It accepts the master key from <keys-dir>/master.key and forwards each request to the Anthropic API with the first upstream *.key (by file name) whose credits are not exhausted; a key whose credit balance is too low is skipped for the cooldown (default 60 minutes). GET /health needs no key.",
+        usage: "ouro gateway serve --keys-dir <dir> [--host <host>] [--port <port>] [--state <path>] [--upstream <url>] [--cooldown-minutes <n>]",
+        example: "ouro gateway serve --keys-dir /mnt/user/appdata/credit-gateway/keys --port 8787",
+    },
     "a2a serve": {
         description: "Run this agent's local A2A JSON-RPC sense server",
         usage: "ouro a2a serve [--agent <name>] [--host <host>] [--port <port>] [--base-url <url>] [--path <path>]",

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

@@ -254,6 +254,7 @@ function usage() {
         "  ouro mailbox [--json]",
         "  ouro -v|--version",
         "  ouro auth [--agent <name>] [--provider <provider>]",
+        "  ouro auth --agent <name> --provider anthropic --api-key-file <path> [--base-url <url>]",
         "  ouro account ensure [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]",
         "  ouro connect [providers|perplexity|embeddings|teams|bluebubbles|mail|voice|a2a|telegram|workbench] [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]",
         "  ouro mail import-mbox --file <path> [--owner-email <email>] [--source <label>] [--agent <name>] [--foreground]",
@@ -303,6 +304,7 @@ function usage() {
         "  ouro a2a card [--agent <name>] [--base-url <url>] [--json]",
         "  ouro a2a onboard [--agent <name>] (--card-url <url>|--did <did:key> --name <name>) [--trust <level>] [--name <name>]",
         "  ouro a2a serve [--agent <name>] [--host <host>] [--port <port>] [--base-url <url>] [--path <path>]",
+        "  ouro gateway serve --keys-dir <dir> [--host <host>] [--port <port>] [--state <path>] [--upstream <url>] [--cooldown-minutes <n>]",
         "  ouro a2a identity [--identity-file <path>] [--json]",
         "  ouro a2a message --to <card-url> --text <text> [--context <id>] [--delegated] [--identity-file <path>] [--json]",
         "  ouro a2a outbox list --to <card-url> [--since <cursor>] [--identity-file <path>] [--json]",
@@ -834,6 +836,8 @@ function parseAuthCommand(args) {
     }
     const { agent, rest } = extractAgentFlag(args);
     let provider;
+    let apiKeyFile;
+    let baseUrl;
     for (let i = 0; i < rest.length; i += 1) {
         if (rest[i] === "--provider") {
             const value = rest[i + 1];
@@ -843,11 +847,33 @@ function parseAuthCommand(args) {
             i += 1;
             continue;
         }
+        // The API key itself is read from a file (or /dev/stdin), never from argv, so it stays out of
+        // shell history and process listings.
+        if (rest[i] === "--api-key-file" || rest[i] === "--base-url") {
+            const value = rest[i + 1];
+            if (!value || value.startsWith("--"))
+                throw new Error(`${rest[i]} requires a value.`);
+            if (rest[i] === "--api-key-file")
+                apiKeyFile = value;
+            else
+                baseUrl = value;
+            i += 1;
+            continue;
+        }
+    }
+    if ((apiKeyFile || baseUrl) && provider !== "anthropic") {
+        throw new Error("--api-key-file and --base-url are only for --provider anthropic (API-key mode).");
     }
+    if (baseUrl && !apiKeyFile)
+        throw new Error("--base-url requires --api-key-file.");
+    if (baseUrl && !/^https?:\/\//.test(baseUrl))
+        throw new Error("--base-url must be an http(s) URL.");
     return {
         kind: "auth.run",
         ...(agent ? { agent } : {}),
         ...(provider ? { provider } : {}),
+        ...(apiKeyFile ? { apiKeyFile } : {}),
+        ...(baseUrl ? { baseUrl } : {}),
     };
 }
 function isVaultUnlockStoreKind(value) {
@@ -1936,6 +1962,61 @@ function parseA2ACommand(args) {
     }
     throw new Error("Usage: ouro a2a card|onboard|serve|message|identity|outbox|escalation|delegated-commands ...");
 }
+const GATEWAY_SERVE_USAGE = "Usage: ouro gateway serve --keys-dir <dir> [--host <host>] [--port <port>] [--state <path>] [--upstream <url>] [--cooldown-minutes <n>]";
+function parseGatewayCommand(args) {
+    const [sub, ...rest] = args;
+    if (sub !== "serve")
+        throw new Error(GATEWAY_SERVE_USAGE);
+    let keysDir;
+    let host;
+    let port;
+    let statePath;
+    let upstream;
+    let cooldownMinutes;
+    for (let i = 0; i < rest.length; i += 1) {
+        const flag = rest[i];
+        const value = rest[i + 1];
+        if (!value || value.startsWith("--"))
+            throw new Error(GATEWAY_SERVE_USAGE);
+        i += 1;
+        if (flag === "--keys-dir")
+            keysDir = value;
+        else if (flag === "--host")
+            host = value;
+        else if (flag === "--state")
+            statePath = value;
+        else if (flag === "--upstream") {
+            if (!/^https?:\/\//.test(value))
+                throw new Error("--upstream must be an http(s) URL");
+            upstream = value;
+        }
+        else if (flag === "--port") {
+            const parsed = Number(value);
+            if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535)
+                throw new Error("Gateway port must be 0-65535");
+            port = parsed;
+        }
+        else if (flag === "--cooldown-minutes") {
+            const parsed = Number(value);
+            if (!Number.isFinite(parsed) || parsed <= 0)
+                throw new Error("--cooldown-minutes must be a positive number");
+            cooldownMinutes = parsed;
+        }
+        else
+            throw new Error(GATEWAY_SERVE_USAGE);
+    }
+    if (!keysDir)
+        throw new Error(GATEWAY_SERVE_USAGE);
+    return {
+        kind: "gateway.serve",
+        keysDir,
+        ...(host ? { host } : {}),
+        ...(port !== undefined ? { port } : {}),
+        ...(statePath ? { statePath } : {}),
+        ...(upstream ? { upstream } : {}),
+        ...(cooldownMinutes !== undefined ? { cooldownMinutes } : {}),
+    };
+}
 function parseConfigCommand(args) {
     const { agent, rest: afterAgent } = extractAgentFlag(args);
     const { facing, rest: cleaned } = extractFacingFlag(afterAgent);
@@ -3118,6 +3199,8 @@ function parseOuroCommand(args) {
         return parseFriendCommand(args.slice(1));
     if (head === "a2a")
         return parseA2ACommand(args.slice(1));
+    if (head === "gateway")
+        return parseGatewayCommand(args.slice(1));
     if (head === "config")
         return parseConfigCommand(args.slice(1));
     if (head === "mcp")

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/heart/identity.js

@@ -69,7 +69,7 @@ var autonomy_budget_2 = require("./autonomy-budget");
 Object.defineProperty(exports, "normalizeHabitPaidTurnsPerDay", { enumerable: true, get: function () { return autonomy_budget_2.normalizeHabitPaidTurnsPerDay; } });
 /** Single source of truth for per-provider credential field names, env var mappings, and prompt labels. */
 exports.PROVIDER_CREDENTIALS = {
-    anthropic: { required: ["setupToken"], envVars: { ANTHROPIC_API_KEY: "setupToken" }, promptLabels: { setupToken: "Anthropic setup-token" } },
+    anthropic: { required: ["setupToken"], alternativeRequired: [["apiKey"]], envVars: { ANTHROPIC_API_KEY: "setupToken" }, promptLabels: { setupToken: "Anthropic setup-token" } },
     "openai-codex": { required: ["oauthAccessToken"], envVars: { OPENAI_API_KEY: "oauthAccessToken" }, promptLabels: { oauthAccessToken: "OpenAI Codex OAuth token" } },
     azure: { required: ["apiKey", "endpoint", "deployment"], envVars: { AZURE_OPENAI_API_KEY: "apiKey", AZURE_OPENAI_KEY: "apiKey", AZURE_OPENAI_ENDPOINT: "endpoint", AZURE_OPENAI_DEPLOYMENT: "deployment" }, promptLabels: { apiKey: "Azure API key", endpoint: "Azure endpoint", deployment: "Azure deployment" } },
     minimax: { required: ["apiKey"], envVars: { MINIMAX_API_KEY: "apiKey" }, promptLabels: { apiKey: "MiniMax API key" } },

package/dist/heart/provider-credentials.js

@@ -59,8 +59,8 @@ const VAULT_ITEM_PREFIX = "providers/";
 exports.PROVIDER_CREDENTIAL_POOL_NOT_LOADED_ERROR = "provider credentials have not been loaded from vault";
 const PROVIDER_FIELD_SPLITS = {
     anthropic: {
-        credentials: ["setupToken", "refreshToken", "expiresAt"],
-        config: [],
+        credentials: ["setupToken", "refreshToken", "expiresAt", "apiKey"],
+        config: ["baseUrl"],
     },
     "openai-codex": {
         credentials: ["oauthAccessToken", "refreshToken", "expiresAt"],

package/dist/heart/provider-ping.js

@@ -157,7 +157,8 @@ function hasEmptyCredentials(provider, config) {
         if (hasManagedIdentity)
             return false;
     }
-    return identity_1.PROVIDER_CREDENTIALS[provider].required.some((key) => !record[key]);
+    const requirements = identity_1.PROVIDER_CREDENTIALS[provider];
+    return ![requirements.required, ...(requirements.alternativeRequired ?? [])].some((fields) => fields.every((key) => !!record[key]));
 }
 function createProviderRuntimeForConfig(provider, config, options = {}) {
     // Use the same provider defaults as auth switch and hatch so verification

package/dist/heart/providers/anthropic.js

@@ -225,7 +225,16 @@ function mergeAnthropicToolArguments(current, partial) {
     }
     return current + partial;
 }
+// An org whose prepaid API credits are used up gets HTTP 400 (or 402) with this phrase. That is a
+// usage limit, not a malformed request, so failover tells the human the right thing.
+const ANTHROPIC_CREDIT_LOW_PHRASE = "credit balance is too low";
+function isAnthropicCreditExhausted(error) {
+    const status = error.status;
+    return (status === 400 || status === 402) && error.message.toLowerCase().includes(ANTHROPIC_CREDIT_LOW_PHRASE);
+}
 function classifyAnthropicError(error) {
+    if (isAnthropicCreditExhausted(error))
+        return "usage-limit";
     return (0, error_classification_1.classifyHttpError)(error, {
         isAuthFailure: isAnthropicAuthFailure,
         isServerError: (e) => e.status === 529,
@@ -236,9 +245,10 @@ function isAnthropicAuthFailure(error) {
     return (lower.includes("oauth authentication") ||
         lower.includes("authentication failed") ||
         lower.includes("unauthorized") ||
-        lower.includes("invalid api key"));
+        lower.includes("invalid api key") ||
+        lower.includes("invalid x-api-key"));
 }
-async function streamAnthropicMessages(client, model, request) {
+async function streamAnthropicMessages(client, model, request, options = { claudeCodePreamble: true }) {
     const { system, messages } = toAnthropicMessages(request.messages);
     const additionalSystemParts = request.messages
         .filter((message) => message.role === "system")
@@ -260,13 +270,14 @@ async function streamAnthropicMessages(client, model, request) {
     // prompt when using OAuth setup tokens (sk-ant-oat01). Without it, Opus/Sonnet
     // 4.6 requests are rejected with 400. This is the API's validation that the
     // token is being used by a Claude Code client.
-    const preambleText = "You are Claude Code, Anthropic's official CLI for Claude.";
+    // API-key mode (a plain API key, for example through a credit gateway) needs no such block.
+    const preambleText = options.claudeCodePreamble ? "You are Claude Code, Anthropic's official CLI for Claude." : "";
     if (request.systemPrompt) {
         // Structured SystemPrompt: merge preamble + stable prefix into one cached block,
         // volatile suffix as a separate uncached block.
         const stableBlock = {
             type: "text",
-            text: preambleText + "\n\n" + request.systemPrompt.stable,
+            text: preambleText ? preambleText + "\n\n" + request.systemPrompt.stable : request.systemPrompt.stable,
             cache_control: { type: "ephemeral" },
         };
         params.system = [
@@ -279,9 +290,11 @@ async function streamAnthropicMessages(client, model, request) {
     }
     else if (system) {
         // Fallback: no structured prompt, extract from messages (legacy path)
-        params.system = [{ type: "text", text: preambleText }, { type: "text", text: system }];
+        params.system = preambleText
+            ? [{ type: "text", text: preambleText }, { type: "text", text: system }]
+            : [{ type: "text", text: system }];
     }
-    else {
+    else if (preambleText) {
         params.system = [{ type: "text", text: preambleText }];
     }
     if (anthropicTools.length > 0)
@@ -441,6 +454,48 @@ async function streamAnthropicMessages(client, model, request) {
         ...(settleFinalization ? { settleFinalization } : {}),
     };
 }
+const ANTHROPIC_PING_MODEL = "claude-haiku-4-5-20251001";
+/**
+ * API-key mode: a plain Anthropic API key, optionally against another base URL such as a credit
+ * gateway. No Claude Code identity headers, no Claude Code system preamble and no token refresh;
+ * prompt caching, thinking, tools and streaming work as in setup-token mode.
+ */
+function createAnthropicApiKeyRuntime(model, apiKey, baseUrl) {
+    const modelCaps = (0, model_capabilities_1.getModelCapabilities)(model);
+    const capabilities = new Set();
+    if (modelCaps.reasoningEffort)
+        capabilities.add("reasoning-effort");
+    // authToken: null keeps the SDK from also sending an ANTHROPIC_AUTH_TOKEN from the environment.
+    const client = new sdk_1.default({ apiKey, authToken: null, baseURL: baseUrl, maxRetries: 0 });
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.anthropic_api_key_mode",
+        message: "anthropic provider using API-key mode",
+        meta: { provider: "anthropic", customBaseUrl: baseUrl !== undefined },
+    });
+    return {
+        id: "anthropic",
+        model,
+        client,
+        capabilities,
+        supportedReasoningEfforts: modelCaps.reasoningEffort,
+        resetTurnState(_messages) {
+            // Anthropic request payload is derived from canonical messages each turn.
+        },
+        appendToolOutput(_callId, _output) {
+            // Anthropic uses canonical messages for tool_result tracking.
+        },
+        streamTurn(request) {
+            return streamAnthropicMessages(client, model, request, { claudeCodePreamble: false });
+        },
+        async ping(signal) {
+            await client.messages.create({ model: ANTHROPIC_PING_MODEL, max_tokens: 1, messages: [{ role: "user", content: "ping" }] }, { signal });
+        },
+        classifyError(error) {
+            return classifyAnthropicError(error);
+        },
+    };
+}
 function createAnthropicProviderRuntime(model, anthropicConfig = (0, config_1.getAnthropicConfig)()) {
     (0, runtime_1.emitNervesEvent)({
         component: "engine",
@@ -448,6 +503,9 @@ function createAnthropicProviderRuntime(model, anthropicConfig = (0, config_1.ge
         message: "anthropic provider init",
         meta: { provider: "anthropic" },
     });
+    const apiKey = anthropicConfig.apiKey?.trim();
+    if (apiKey)
+        return createAnthropicApiKeyRuntime(model, apiKey, anthropicConfig.baseUrl?.trim() || undefined);
     if (!anthropicConfig.setupToken) {
         throw new Error(getAnthropicReauthGuidance("provider 'anthropic' is selected but anthropic.setupToken is missing in the agent vault."));
     }
@@ -509,7 +567,7 @@ function createAnthropicProviderRuntime(model, anthropicConfig = (0, config_1.ge
         /* v8 ignore start -- ping: tested via provider-ping.test.ts @preserve */
         async ping(signal) {
             const freshClient = await ensureClient();
-            await freshClient.messages.create({ model: "claude-haiku-4-5-20251001", max_tokens: 1, messages: [{ role: "user", content: "ping" }] }, { signal, headers: { "anthropic-beta": "claude-code-20250219,oauth-2025-04-20" } });
+            await freshClient.messages.create({ model: ANTHROPIC_PING_MODEL, max_tokens: 1, messages: [{ role: "user", content: "ping" }] }, { signal, headers: { "anthropic-beta": "claude-code-20250219,oauth-2025-04-20" } });
         },
         /* v8 ignore stop */
         /* v8 ignore next 3 -- delegation: classification logic tested via classifyAnthropicError @preserve */

package/dist/heart/runtime-credentials.js

@@ -108,7 +108,8 @@ function isProviderCredentialRecord(value) {
     const provider = value.provider;
     const canonicalCredentials = (0, provider_credentials_1.splitProviderCredentialFields)(provider, credentials).credentials;
     const canonicalConfig = (0, provider_credentials_1.splitProviderCredentialFields)(provider, config).config;
-    if (!identity_1.PROVIDER_CREDENTIALS[provider].required.every((field) => (isPresentCredentialValue(canonicalCredentials[field]) || isPresentCredentialValue(canonicalConfig[field]))))
+    const requirements = identity_1.PROVIDER_CREDENTIALS[provider];
+    if (![requirements.required, ...(requirements.alternativeRequired ?? [])].some((fields) => fields.every((field) => (isPresentCredentialValue(canonicalCredentials[field]) || isPresentCredentialValue(canonicalConfig[field])))))
         return false;
     const provenance = value.provenance;
     if (!isRecord(provenance))

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,