switchroom 0.19.27 → 0.19.28

package/dist/cli/switchroom.js

@@ -2120,7 +2120,7 @@ var init_esm = __esm(() => {
 });
 
 // src/build-info.ts
-var VERSION = "0.19.27", COMMIT_SHA = "42779242";
+var VERSION = "0.19.28", COMMIT_SHA = "d9a5f4ae";
 
 // src/cli/resolve-version.ts
 import { existsSync, readFileSync } from "node:fs";
@@ -13966,7 +13966,10 @@ var init_schema = __esm(() => {
     admin_key: exports_external.string().optional().describe("LiteLLM master/admin key used at apply time to provision the team + " + "virtual key. Supports a vault reference (e.g. " + "'vault:litellm/master-key') \u2014 resolution happens at apply time via " + "the vault-broker. Never injected into the agent container."),
     team: exports_external.string().optional().describe("LiteLLM team alias the per-agent key is created under. Defaults to " + "'switchroom' (applied in code, not as a schema default)."),
     small_fast_model: exports_external.string().optional().describe("Model id exported as ANTHROPIC_SMALL_FAST_MODEL for the claude CLI's " + "background/fast lane, e.g. 'claude-haiku-4-5-20251001'."),
-    tags: exports_external.record(exports_external.string(), exports_external.string()).optional().describe("Extra key/value metadata tags attached to the provisioned LiteLLM " + "virtual key. Merged per-key across cascade layers (agent wins).")
+    tags: exports_external.record(exports_external.string(), exports_external.string()).optional().describe("Extra key/value metadata tags attached to the provisioned LiteLLM " + "virtual key. Merged per-key across cascade layers (agent wins)."),
+    max_budget: exports_external.number().positive().optional().describe("HARD spend cap in USD for this agent's virtual key over one " + "`budget_duration` window. LiteLLM refuses the request once the key's " + "tracked spend exceeds it, so a runaway loop costs at most this much " + "before it is stopped. Defaults to " + "DEFAULT_KEY_MAX_BUDGET_USD (see src/litellm/budget.ts) \u2014 deliberately " + "conservative; raise it per-agent rather than removing it. Set 0 or " + "omit `budget_duration` at your own risk: an uncapped key is only as " + "bounded as the upstream account balance."),
+    soft_budget: exports_external.number().positive().optional().describe("ADVISORY spend threshold in USD. LiteLLM keeps serving past it and " + "raises a budget alert instead. Must be < max_budget. NOTE: LiteLLM " + "accepts soft_budget only on POST /key/generate (GenerateKeyRequest); " + "UpdateKeyRequest does NOT carry it, so changing this value only takes " + "effect on a key that is (re)generated, not on an existing one."),
+    budget_duration: exports_external.string().regex(/^\d+(s|m|h|d|mo)$/, "budget_duration must be a LiteLLM duration like '30d', '24h', '1mo'").optional().describe("Rolling window the budget resets on, in LiteLLM duration syntax " + "('30d', '24h', '1mo'). Defaults to DEFAULT_KEY_BUDGET_DURATION. " + "WITHOUT a duration LiteLLM treats max_budget as a LIFETIME cap that " + "never resets \u2014 the key silently dies for good once it is hit.")
   }).optional().describe("LiteLLM routing config \u2014 opt-in per-agent virtual-key auto-provisioning " + "+ routing env. Default OFF. See LiteLLMConfigSchema doc for the full flow.");
   HindsightPerOpLlmSchema = exports_external.object({
     model: exports_external.string().min(1).optional().describe("Per-op model (upstream `HINDSIGHT_API_<OP>_LLM_MODEL`). Absent \u2192 " + "inherit the global `hindsight.llm.model`."),
@@ -13985,7 +13988,7 @@ var init_schema = __esm(() => {
       reflect: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `reflect` LLM op (synthesis / mental-model " + "refresh). Emits `HINDSIGHT_API_REFLECT_LLM_*`. Absent \u2192 uses global."),
       consolidation: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `consolidation` LLM op (background memory " + "merge). Emits `HINDSIGHT_API_CONSOLIDATION_LLM_*`. Absent \u2192 global.")
     }).optional().describe("LLM knob for the hindsight container. The flat `provider`/`model` set " + "the global default (backward-compatible); optional `retain`/`reflect`/" + "`consolidation` blocks override individual ops. All fields optional; " + "unset fields fall back to the hard-coded defaults."),
-    env: exports_external.record(exports_external.union([exports_external.string(), exports_external.number(), exports_external.boolean()])).optional().describe("Operator overrides for switchroom's capability-gated Hindsight " + "performance defaults. Only the keys switchroom actually manages are " + "honoured (`HINDSIGHT_PERF_ENV_KEYS` in " + "src/setup/hindsight-perf-defaults.ts: RERANKER_LOCAL_FP16, " + "RERANKER_LOCAL_BATCH_SIZE, LLM_MAX_CONCURRENT, " + "RETAIN/CONSOLIDATION_LLM_MAX_CONCURRENT, LLM_STRICT_SCHEMA, " + "LLM_MAX_RETRIES, CONSOLIDATION_LLM_PARALLELISM, " + "MAX_OBSERVATIONS_PER_SCOPE, " + "RECALL_MAX_CANDIDATES_PER_SOURCE, LINK_EXPANSION_PER_ENTITY_LIMIT, " + "LINK_EXPANSION_TIMEOUT, LLM_REASONING_EFFORT, " + "RERANKER_LOCAL_BUCKET_BATCHING, RERANKER_MAX_CANDIDATES, " + "RERANKER_LOCAL_MAX_CONCURRENT, RECALL_MAX_CONCURRENT, " + "REFLECT_WALL_TIMEOUT, WORKER_CONSOLIDATION_MAX_SLOTS, " + "WORKER_CONSOLIDATION_SLOT_LIMIT, " + "CONSOLIDATION_MAX_MEMORIES_PER_ROUND), the override-only keys " + "switchroom manages but ships NO default for " + "(`HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS`: " + "HINDSIGHT_API_WORKER_CONSOLIDATION_BANK_PRIORITY \u2014 a per-deployment " + "`bank-pattern:priority,...` map; unset means upstream's flat " + "created_at FIFO across banks; and " + "HINDSIGHT_CE_DECISIVE_RELATIVE_GAP \u2014 the rollback knob for " + "switchroom's CE-saturation damping patch, a float; >= ~0.65 backs the " + "damping out entirely, unset means the patch's own derived gap), plus the " + "embedded-PostgreSQL (pg0) sizing keys switchroom manages in " + "src/setup/hindsight-pg-defaults.ts (`HINDSIGHT_PG_ENV_KEYS`: " + "SWITCHROOM_HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE, " + "SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS \u2014 a postgres size string such " + "as `4GB`, or the sentinel `off` to leave pg0's own default for that " + "one knob). A value set here " + "REPLACES switchroom's default and is emitted even when the gating " + "capability is absent, so an operator can always force a knob. Other " + "`HINDSIGHT_API_*` keys are deliberately IGNORED \u2014 a blanket " + "passthrough would collide with the vars startHindsight() derives " + "itself (HINDSIGHT_API_PORT, the retain token/deadline budget).")
+    env: exports_external.record(exports_external.union([exports_external.string(), exports_external.number(), exports_external.boolean()])).optional().describe("Operator overrides for switchroom's capability-gated Hindsight " + "performance defaults. Only the keys switchroom actually manages are " + "honoured (`HINDSIGHT_PERF_ENV_KEYS` in " + "src/setup/hindsight-perf-defaults.ts: RERANKER_LOCAL_FP16, " + "RERANKER_LOCAL_BATCH_SIZE, LLM_MAX_CONCURRENT, " + "RETAIN/CONSOLIDATION_LLM_MAX_CONCURRENT, LLM_STRICT_SCHEMA, " + "LLM_MAX_RETRIES, CONSOLIDATION_LLM_PARALLELISM, " + "MAX_OBSERVATIONS_PER_SCOPE, " + "RECALL_MAX_CANDIDATES_PER_SOURCE, LINK_EXPANSION_PER_ENTITY_LIMIT, " + "LINK_EXPANSION_TIMEOUT, LLM_REASONING_EFFORT, " + "RERANKER_LOCAL_BUCKET_BATCHING, RERANKER_MAX_CANDIDATES, " + "RERANKER_LOCAL_MAX_CONCURRENT, RECALL_MAX_CONCURRENT, " + "REFLECT_WALL_TIMEOUT, WORKER_CONSOLIDATION_MAX_SLOTS, " + "WORKER_CONSOLIDATION_SLOT_LIMIT, " + "CONSOLIDATION_MAX_MEMORIES_PER_ROUND, RECENCY_DECAY_FUNCTION, " + "RECENCY_DECAY_HALFLIFE_DAYS \u2014 switchroom defaults recall's recency " + "curve to `exponential` with a 30-day half-life so a fact retained " + "today outranks a stale one, instead of upstream's near-flat " + "linear/365-day window), the override-only keys " + "switchroom manages but ships NO default for " + "(`HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS`: " + "HINDSIGHT_API_WORKER_CONSOLIDATION_BANK_PRIORITY \u2014 a per-deployment " + "`bank-pattern:priority,...` map; unset means upstream's flat " + "created_at FIFO across banks; and " + "HINDSIGHT_CE_DECISIVE_RELATIVE_GAP \u2014 the rollback knob for " + "switchroom's CE-saturation damping patch, a float; >= ~0.65 backs the " + "damping out entirely, unset means the patch's own derived gap; and " + "HINDSIGHT_API_RECENCY_DECAY_LINEAR_WINDOW_DAYS \u2014 only read when the " + "decay function is `linear`, so switchroom ships no default for it but " + "still honours an operator who flips the function back; and " + "HINDSIGHT_API_WORKER_MAX_SLOTS \u2014 the worker poller's TOTAL in-flight " + "task budget, the pool WORKER_CONSOLIDATION_MAX_SLOTS reserves out of; " + "unset means upstream's own default), plus the " + "embedded-PostgreSQL (pg0) sizing keys switchroom manages in " + "src/setup/hindsight-pg-defaults.ts (`HINDSIGHT_PG_ENV_KEYS`: " + "SWITCHROOM_HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE, " + "SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS \u2014 a postgres size string such " + "as `4GB`, or the sentinel `off` to leave pg0's own default for that " + "one knob). A value set here " + "REPLACES switchroom's default and is emitted even when the gating " + "capability is absent, so an operator can always force a knob. Other " + "`HINDSIGHT_API_*` keys are deliberately IGNORED \u2014 a blanket " + "passthrough would collide with the vars startHindsight() derives " + "itself (HINDSIGHT_API_PORT, the retain token/deadline budget).")
   });
   MicrosoftWorkspaceConfigSchema = exports_external.object({
     microsoft_client_id: exports_external.string().min(1).optional().describe("Microsoft OAuth application (client) ID from Entra portal " + "(literal string or vault reference e.g. " + "'vault:microsoft-oauth-client-id'). OPTIONAL \u2014 omit it to use " + "switchroom's shipped default Microsoft app (zero-config). " + "Set it only to bring your own Entra app (BYO)."),
@@ -15765,6 +15768,12 @@ var init_hindsight_pg_defaults = __esm(() => {
 });
 
 // src/setup/hindsight-perf-defaults.ts
+function hindsightConsolidationLlmMaxConcurrentDefault(globalMaxConcurrent = HINDSIGHT_DEFAULT_LLM_MAX_CONCURRENT, retainMaxConcurrent = HINDSIGHT_DEFAULT_RETAIN_LLM_MAX_CONCURRENT) {
+  const globalCap = Number.isFinite(globalMaxConcurrent) && globalMaxConcurrent >= 1 ? Math.floor(globalMaxConcurrent) : HINDSIGHT_DEFAULT_LLM_MAX_CONCURRENT;
+  const retainCap = Number.isFinite(retainMaxConcurrent) && retainMaxConcurrent >= 0 ? Math.floor(retainMaxConcurrent) : HINDSIGHT_DEFAULT_RETAIN_LLM_MAX_CONCURRENT;
+  const headroomBound = Math.max(1, globalCap - 1);
+  return Math.min(headroomBound, Math.max(1, globalCap - retainCap - 1));
+}
 function resolveHindsightPerfOverrides(configEnv, processEnv = process.env) {
   const out = new Map;
   for (const key of HINDSIGHT_PERF_ENV_KEYS) {
@@ -15791,6 +15800,14 @@ function hindsightPerfEnv(caps, overrides = new Map) {
     groups.push(HINDSIGHT_PERF_DEFAULTS_GPU);
   if (caps.localLlm === true)
     groups.push(HINDSIGHT_PERF_DEFAULTS_LOCAL_LLM);
+  const effectiveCap = (key, fallback) => {
+    const raw = overrides.get(key);
+    if (raw === undefined)
+      return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed >= 1 ? parsed : fallback;
+  };
+  const derivedConsolidationCap = String(hindsightConsolidationLlmMaxConcurrentDefault(effectiveCap("HINDSIGHT_API_LLM_MAX_CONCURRENT", HINDSIGHT_DEFAULT_LLM_MAX_CONCURRENT), effectiveCap("HINDSIGHT_API_RETAIN_LLM_MAX_CONCURRENT", HINDSIGHT_DEFAULT_RETAIN_LLM_MAX_CONCURRENT)));
   const out = [];
   const emitted = new Set;
   for (const group of groups) {
@@ -15798,7 +15815,8 @@ function hindsightPerfEnv(caps, overrides = new Map) {
       if (emitted.has(key))
         continue;
       emitted.add(key);
-      out.push([key, overrides.get(key) ?? value]);
+      const shipped = key === "HINDSIGHT_API_CONSOLIDATION_LLM_MAX_CONCURRENT" ? derivedConsolidationCap : value;
+      out.push([key, overrides.get(key) ?? shipped]);
     }
   }
   for (const key of [...overrides.keys()].sort()) {
@@ -15812,10 +15830,11 @@ function hindsightPerfEnv(caps, overrides = new Map) {
 function findUnmanagedHindsightEnvKeys(configEnv) {
   return Object.keys(configEnv ?? {}).filter((key) => !HINDSIGHT_PERF_ENV_KEYS.has(key) && !HINDSIGHT_PG_ENV_KEYS.has(key)).sort();
 }
-var HINDSIGHT_RERANKER_MAX_CANDIDATES_FOR_DERIVATION = 150, HINDSIGHT_DEFAULT_RECALL_MAX_CANDIDATES_PER_SOURCE, HINDSIGHT_DEFAULT_LINK_EXPANSION_PER_ENTITY_LIMIT = 50, HINDSIGHT_DEFAULT_LINK_EXPANSION_TIMEOUT_S = 2, HINDSIGHT_DEFAULT_LLM_REASONING_EFFORT = "low", HINDSIGHT_DEFAULT_LLM_MAX_CONCURRENT = 4, HINDSIGHT_DEFAULT_RETAIN_LLM_MAX_CONCURRENT = 1, HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_MAX_CONCURRENT = 1, HINDSIGHT_DEFAULT_RERANKER_LOCAL_FP16 = "true", HINDSIGHT_DEFAULT_RERANKER_LOCAL_BATCH_SIZE = 128, HINDSIGHT_DEFAULT_LLM_STRICT_SCHEMA = "true", HINDSIGHT_DEFAULT_LLM_MAX_RETRIES = 2, HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_PARALLELISM = 2, HINDSIGHT_DEFAULT_MAX_OBSERVATIONS_PER_SCOPE = 1000, HINDSIGHT_DEFAULT_RERANKER_BUCKET_BATCHING = "true", HINDSIGHT_DEFAULT_RERANKER_MAX_CANDIDATES = 150, HINDSIGHT_DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT = 4, HINDSIGHT_DEFAULT_RECALL_MAX_CONCURRENT = 8, HINDSIGHT_DEFAULT_REFLECT_WALL_TIMEOUT_S = 600, HINDSIGHT_DEFAULT_CONSOLIDATION_MAX_MEMORIES_PER_ROUND = 500, HINDSIGHT_DEFAULT_CONSOLIDATION_SLOT_LIMIT = 6, HINDSIGHT_DEFAULT_CONSOLIDATION_MAX_SLOTS = 1, HINDSIGHT_PERF_DEFAULTS_UNGATED, HINDSIGHT_PERF_DEFAULTS_GPU, HINDSIGHT_PERF_DEFAULTS_LOCAL_LLM, HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS, HINDSIGHT_PERF_ENV_KEYS;
+var HINDSIGHT_RERANKER_MAX_CANDIDATES_FOR_DERIVATION = 150, HINDSIGHT_DEFAULT_RECALL_MAX_CANDIDATES_PER_SOURCE, HINDSIGHT_DEFAULT_LINK_EXPANSION_PER_ENTITY_LIMIT = 50, HINDSIGHT_DEFAULT_LINK_EXPANSION_TIMEOUT_S = 2, HINDSIGHT_DEFAULT_LLM_REASONING_EFFORT = "low", HINDSIGHT_DEFAULT_LLM_MAX_CONCURRENT = 4, HINDSIGHT_DEFAULT_RETAIN_LLM_MAX_CONCURRENT = 1, HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_MAX_CONCURRENT, HINDSIGHT_DEFAULT_RERANKER_LOCAL_FP16 = "true", HINDSIGHT_DEFAULT_RERANKER_LOCAL_BATCH_SIZE = 128, HINDSIGHT_DEFAULT_LLM_STRICT_SCHEMA = "true", HINDSIGHT_DEFAULT_LLM_MAX_RETRIES = 2, HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_PARALLELISM = 2, HINDSIGHT_DEFAULT_MAX_OBSERVATIONS_PER_SCOPE = 1000, HINDSIGHT_DEFAULT_RERANKER_BUCKET_BATCHING = "true", HINDSIGHT_DEFAULT_RERANKER_MAX_CANDIDATES = 150, HINDSIGHT_DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT = 4, HINDSIGHT_DEFAULT_RECALL_MAX_CONCURRENT = 8, HINDSIGHT_DEFAULT_REFLECT_WALL_TIMEOUT_S = 600, HINDSIGHT_DEFAULT_CONSOLIDATION_MAX_MEMORIES_PER_ROUND = 500, HINDSIGHT_DEFAULT_CONSOLIDATION_SLOT_LIMIT = 6, HINDSIGHT_DEFAULT_CONSOLIDATION_MAX_SLOTS = 1, HINDSIGHT_DEFAULT_RECENCY_DECAY_FUNCTION = "exponential", HINDSIGHT_DEFAULT_RECENCY_DECAY_HALFLIFE_DAYS = 30, HINDSIGHT_PERF_DEFAULTS_UNGATED, HINDSIGHT_PERF_DEFAULTS_GPU, HINDSIGHT_PERF_DEFAULTS_LOCAL_LLM, HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS, HINDSIGHT_PERF_ENV_KEYS;
 var init_hindsight_perf_defaults = __esm(() => {
   init_hindsight_pg_defaults();
   HINDSIGHT_DEFAULT_RECALL_MAX_CANDIDATES_PER_SOURCE = Math.ceil(HINDSIGHT_RERANKER_MAX_CANDIDATES_FOR_DERIVATION * 0.4);
+  HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_MAX_CONCURRENT = hindsightConsolidationLlmMaxConcurrentDefault();
   HINDSIGHT_PERF_DEFAULTS_UNGATED = [
     [
       "HINDSIGHT_API_RECALL_MAX_CANDIDATES_PER_SOURCE",
@@ -15869,6 +15888,14 @@ var init_hindsight_perf_defaults = __esm(() => {
     [
       "HINDSIGHT_API_CONSOLIDATION_MAX_MEMORIES_PER_ROUND",
       String(HINDSIGHT_DEFAULT_CONSOLIDATION_MAX_MEMORIES_PER_ROUND)
+    ],
+    [
+      "HINDSIGHT_API_RECENCY_DECAY_FUNCTION",
+      HINDSIGHT_DEFAULT_RECENCY_DECAY_FUNCTION
+    ],
+    [
+      "HINDSIGHT_API_RECENCY_DECAY_HALFLIFE_DAYS",
+      String(HINDSIGHT_DEFAULT_RECENCY_DECAY_HALFLIFE_DAYS)
     ]
   ];
   HINDSIGHT_PERF_DEFAULTS_GPU = [
@@ -15893,7 +15920,9 @@ var init_hindsight_perf_defaults = __esm(() => {
   ];
   HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS = new Set([
     "HINDSIGHT_API_WORKER_CONSOLIDATION_BANK_PRIORITY",
-    "HINDSIGHT_CE_DECISIVE_RELATIVE_GAP"
+    "HINDSIGHT_CE_DECISIVE_RELATIVE_GAP",
+    "HINDSIGHT_API_RECENCY_DECAY_LINEAR_WINDOW_DAYS",
+    "HINDSIGHT_API_WORKER_MAX_SLOTS"
   ]);
   HINDSIGHT_PERF_ENV_KEYS = new Set([
     ...[
@@ -16983,22 +17012,35 @@ function isHindsightEnabled(config) {
     return false;
   return config?.memory?.backend === "hindsight";
 }
-function isUpgradableRetainMission(current) {
-  if (current == null || current.trim() === "")
-    return true;
-  return SUPERSEDED_RETAIN_MISSIONS.includes(current);
-}
 function decideRetainMissionUpgrade(configured, current) {
+  return decideMissionUpgrade(configured, current, DEFAULT_RETAIN_MISSION, SUPERSEDED_RETAIN_MISSIONS);
+}
+function decideMissionUpgrade(configured, current, desired, shipped) {
   if (configured)
     return { action: "config", mission: configured };
-  if (current === DEFAULT_RETAIN_MISSION)
+  if (current === desired)
     return { action: "none" };
-  if (isUpgradableRetainMission(current)) {
-    return { action: "upgrade", mission: DEFAULT_RETAIN_MISSION };
+  if (current == null || current.trim() === "" || shipped.includes(current)) {
+    return { action: "upgrade", mission: desired };
   }
   return { action: "none" };
 }
+function decideObservationsMissionUpgrade(configured, profileDefault, current) {
+  const desired = profileDefault ?? DEFAULT_OBSERVATIONS_MISSION;
+  const shipped = [
+    ...SUPERSEDED_OBSERVATIONS_MISSIONS,
+    DEFAULT_OBSERVATIONS_MISSION,
+    ...Object.values(PROFILE_MEMORY_DEFAULTS).map((d) => d.observations_mission).filter((m) => m != null)
+  ].filter((m) => m !== desired);
+  return decideMissionUpgrade(configured, current, desired, shipped);
+}
 async function fetchBankRetainMission(apiUrl, bankId, opts) {
+  return fetchBankMissionField(apiUrl, bankId, "retain_mission", opts);
+}
+async function fetchBankObservationsMission(apiUrl, bankId, opts) {
+  return fetchBankMissionField(apiUrl, bankId, "observations_mission", opts);
+}
+async function fetchBankMissionField(apiUrl, bankId, field, opts) {
   const fetchImpl = opts?.fetchImpl ?? fetch;
   const timeoutMs = opts?.timeoutMs ?? 5000;
   const base = apiUrl.replace(/\/mcp\/?$/, "").replace(/\/$/, "");
@@ -17015,10 +17057,10 @@ async function fetchBankRetainMission(apiUrl, bankId, opts) {
     if (config == null || typeof config !== "object") {
       return { ok: false, reason: "Unexpected shape" };
     }
-    if (!("retain_mission" in config)) {
+    if (!(field in config)) {
       return { ok: false, reason: "Unexpected shape" };
     }
-    const mission = config.retain_mission;
+    const mission = config[field];
     if (mission != null && typeof mission !== "string") {
       return { ok: false, reason: "Unexpected shape" };
     }
@@ -17570,7 +17612,7 @@ async function addMemoryTag(apiUrl, bankId, memoryId, tag, opts) {
     return { ok: false, reason: String(err) };
   }
 }
-var HINDSIGHT_SHIM_CLI_PATH = "/usr/local/bin/switchroom", HINDSIGHT_SHIM_AGENT_HOME = "/state/agent/home", DEFAULT_RETAIN_MISSION, SUPERSEDED_RETAIN_MISSIONS, PROFILE_MEMORY_DEFAULTS, USER_PROFILE_SOURCE_QUERY = "What are the key facts, preferences, context, and communication style about the user I talk to? Summarize what matters for making the agent feel like it knows them.", DEMOTE_FROM_RECALL_TAG = "[demote-from-recall]";
+var HINDSIGHT_SHIM_CLI_PATH = "/usr/local/bin/switchroom", HINDSIGHT_SHIM_AGENT_HOME = "/state/agent/home", DEFAULT_RETAIN_MISSION, SUPERSEDED_RETAIN_MISSIONS, DEFAULT_OBSERVATIONS_MISSION, SUPERSEDED_OBSERVATIONS_MISSIONS, PROFILE_MEMORY_DEFAULTS, USER_PROFILE_SOURCE_QUERY = "What are the key facts, preferences, context, and communication style about the user I talk to? Summarize what matters for making the agent feel like it knows them.", DEMOTE_FROM_RECALL_TAG = "[demote-from-recall]";
 var init_hindsight2 = __esm(() => {
   init_users();
   init_hindsight();
@@ -17599,6 +17641,16 @@ var init_hindsight2 = __esm(() => {
 ` + `- Hindsight's own errors, retries, backlogs, or internal state \u2014 the memory
 ` + `  system's self-reports are not memories.
 ` + `- Restatements of the user's current request or the task in progress.
+` + `- Volatile state written as a timeless assertion. A version, count, size,
+` + `  backlog, status, or any "X is running Y" / "X is at Y" / "X is currently Y"
+` + `  claim is true only at the instant it was said. Concretely, never produce a
+` + `  fact whose text resembles any of these: "Switchroom fleet is running image
+` + `  version v0.18.19", "The switchroom repo is at /path/to/fleet, version
+` + `  v0.19.5", "Bank overlord has 43155 pending consolidations", "The build is
+` + `  currently green". If the claim is worth keeping, put the date INSIDE the
+` + `  fact text ("As of 2026-07-19 the fleet was running v0.18.19"); if you
+` + `  cannot date it, drop it. An undated one is recalled forever as though it
+` + `  were still true, which is worse than not remembering it at all.
 ` + `- Transient state (unread counts, build status, what is running right now) unless
 ` + `  the fact is explicitly dated, in which case record it as a dated observation.
 ` + `- Greetings, acknowledgements, and routine operational chatter.
@@ -17620,18 +17672,108 @@ var init_hindsight2 = __esm(() => {
 ` + "- Transient state (unread counts, build status, what is running right now) " + "unless the fact is explicitly dated, in which case record it as a dated " + `observation.
 ` + `- Greetings, acknowledgements, and routine operational chatter.
 
-` + "If a candidate fact matches an exclusion, drop it rather than rewording " + "it. If nothing durable remains, return an empty facts list."
+` + "If a candidate fact matches an exclusion, drop it rather than rewording " + "it. If nothing durable remains, return an empty facts list.",
+    `Extract durable facts that will still be true and useful weeks from now: user preferences and standing rules, ongoing projects and recurring commitments, technical and architectural decisions with their rationale, and people/tool relationships. A preference revealed by a request is durable \u2014 record the preference (what the user likes, wants, or always does), not the request itself.
+` + `
+` + `A TOOL RESULT IS NOT A FACT. Before extracting, ask: is the subject of this
+` + `candidate a file path, a command/process/agent/session id, a temp directory, or
+` + `the location where some output was written? If yes, drop it \u2014 it is transcript
+` + `exhaust, not memory.
+` + `
+` + `NEVER extract:
+` + `- Tool results verbatim or paraphrased. Concretely, never produce a fact whose
+` + `  text resembles any of these: "File created successfully at /path/to/file",
+` + `  "A background command with ID bctz4yskm is running, and its output will be
+` + `  written to /tmp/...", "Async agent a745598ba84e71df1 was launched successfully
+` + `  and is running in the background", "User executed a Bash command to sleep for
+` + `  200 seconds", "The assistant used grep to locate 'truncateSync' in src/foo.ts".
+` + `- Anything mentioning a path under /tmp, a scratchpad directory, or a .tmp file.
+` + `- Agent tool-use traces or narration of what the assistant did (e.g. "the
+` + `  assistant used X to query Y", "ran a search", "sent the message").
+` + `- In-flight workflow/process narration (a sub-task started, paused, or is still
+` + `  running) \u2014 retain the outcome only once the task completes or a decision is made.
+` + `- Operation, request, batch, agent, command or session IDs, UUIDs, hashes, or error codes.
+` + `- Slash commands the user typed and their effects (e.g. "User issued /clear to
+` + `  reset assistant state").
+` + `- Hindsight's own errors, retries, backlogs, or internal state \u2014 the memory
+` + `  system's self-reports are not memories.
+` + `- Restatements of the user's current request or the task in progress.
+` + `- Transient state (unread counts, build status, what is running right now) unless
+` + `  the fact is explicitly dated, in which case record it as a dated observation.
+` + `- Greetings, acknowledgements, and routine operational chatter.
+` + `
+` + `If a candidate fact matches an exclusion, drop it rather than rewording it. If
+` + "nothing durable remains, return an empty facts list."
+  ];
+  DEFAULT_OBSERVATIONS_MISSION = `Synthesise durable, standing knowledge about the people, projects, and systems this agent works with: preferences and standing rules, roles and relationships, skills and recurring patterns, technical and operational decisions with their rationale, and the state of long-running work once it lands.
+` + `
+` + `The test is durability, not notability: an observation must still be worth reading weeks from now. A single dated event belongs in an observation only when it establishes or changes a standing fact.
+` + `
+` + `Do NOT synthesise observations from:
+` + `- Transcript exhaust \u2014 tool calls and their results, file paths, temp or scratchpad directories, where some output was written, or narration of what an assistant did.
+` + `- Identifiers with no standing meaning: session, agent, request, batch or command IDs, UUIDs, hashes, error codes.
+` + `- In-flight process narration \u2014 a task started, paused, or still running. Record the outcome once it lands, not the running state.
+` + `- The memory system's own errors, retries, backlogs, or internal state.
+` + `- Transient state (what is running right now, unread counts, build status) unless the fact is explicitly dated, in which case record it as dated.
+` + `
+` + "If the new facts contain nothing durable, record nothing rather than synthesising a weak observation.";
+  SUPERSEDED_OBSERVATIONS_MISSIONS = [
+    "Synthesise the person's wellbeing patterns, motivations, and emotional " + "context \u2014 how habits, setbacks, and encouragement connect over time."
   ];
   PROFILE_MEMORY_DEFAULTS = {
     "health-coach": {
       disposition: { skepticism: 2, literalism: 2, empathy: 5 },
-      observations_mission: "Synthesise the person's wellbeing patterns, motivations, and emotional " + "context \u2014 how habits, setbacks, and encouragement connect over time."
+      observations_mission: `You consolidate the memory of a health and fitness coach working with one person. This bank records how that person actually lives and trains.
+` + `
+` + `Synthesise into durable observations:
+` + `- Goals, targets, and the plan currently in force, with the reasoning behind each.
+` + `- Training, nutrition, sleep, and alcohol patterns as they hold over weeks \u2014 what the person reliably does, not what they did once.
+` + `- Constraints that shape the plan: injuries, medical guidance, schedule, equipment, foods and sessions they refuse.
+` + `- Motivations, and what actually helps or backfires when they slip.
+` + `- Trends in the numbers: direction and range over time, not any single reading.
+` + `- Corrections to earlier beliefs, recorded explicitly as corrections.
+` + `
+` + `A single day's log, weight reading, or session is evidence, not an observation. Record one only when it establishes or changes a standing pattern, target, or constraint \u2014 then fold it into the observation for that pattern and say what changed and roughly when.
+` + `
+` + `Granularity: one observation per habit, target, constraint, or trend. Aggregate repeated daily evidence into the observation for that pattern rather than creating one per day, and keep training, nutrition, and sleep as separate observations.
+` + `
+` + "Word observations as the person's own pattern and framing, never as a verdict on them."
     },
     "executive-assistant": {
-      disposition: { skepticism: 4, literalism: 4, empathy: 3 }
+      disposition: { skepticism: 4, literalism: 4, empathy: 3 },
+      observations_mission: `You consolidate the memory of an executive assistant working for one person. This bank records that person's commitments, people, and standing arrangements.
+` + `
+` + `Synthesise into durable observations:
+` + `- Standing rules and preferences: how they want things scheduled, written, and filed, and when they want to be interrupted.
+` + `- People and organisations, and the relationship: who they are, what they are involved in, how to reach them.
+` + `- Recurring commitments and routines, and the constraints around them.
+` + `- Obligations and their state: what was promised to whom, the deadline, and what is still outstanding.
+` + `- Decisions made and decisions deferred, with the reasoning and the trade accepted.
+` + `- Corrections to earlier beliefs, recorded explicitly as corrections.
+` + `
+` + `Live commitment state IS durable knowledge here, not ephemeral chatter. An outstanding obligation, a travel window, an unanswered request, a "currently X" arrangement \u2014 these are precisely what this agent must recall later. Keep them, and embed the date inside the observation text so a later reader can judge staleness. Do not drop them as ephemeral.
+` + `
+` + `Granularity: one observation per person, arrangement, or obligation. Aggregate repeated mentions into that observation rather than creating siblings; never merge two different people or two different commitments into one.
+` + `
+` + "Do not synthesise from transcript exhaust: tool calls and their results, message or event identifiers, or narration of what the assistant did."
     },
     coding: {
-      disposition: { skepticism: 4, literalism: 5, empathy: 2 }
+      disposition: { skepticism: 4, literalism: 5, empathy: 2 },
+      observations_mission: `You consolidate the memory of a software-engineering agent. This bank records real work on real codebases.
+` + `
+` + `Synthesise into durable observations:
+` + `- Architecture and design decisions, each with its rationale and the trade accepted.
+` + `- Root causes, with the evidence chain, and negative results \u2014 what was ruled out matters as much as what was found.
+` + `- How the repository works: build, test, and lint commands, conventions, CI gates, and where things live.
+` + `- Outcomes of code work: issue and PR numbers, what changed, whether it merged, what review found.
+` + `- The user's standing rules, preferences, and corrections to this agent's behaviour.
+` + `- Corrections to earlier beliefs, recorded explicitly as corrections.
+` + `
+` + `Repository and service state IS durable knowledge here, not ephemeral chatter. Versions, a failing gate, an open PR, a measured number, a "currently X" claim \u2014 these are precisely what this agent must recall later. Keep them, and embed the date inside the observation text so a later reader can judge staleness. Do not drop them as ephemeral.
+` + `
+` + `Granularity: one observation per distinct decision, cause, convention, or work item. Aggregate repeated evidence about the same one into that observation rather than creating siblings; never merge two separate decisions into a single summary.
+` + `
+` + "Do not synthesise from transcript exhaust: tool calls and their results, scratch paths, session or request identifiers, or narration of what the agent did. Prefer specific and falsifiable \u2014 naming the file, the number, the commit, or the decision beats summarising the topic."
     }
   };
 });
@@ -27998,6 +28140,21 @@ async function resolveRetainMissionPush(apiUrl, bankId, configured, label) {
   }
   return decision.mission;
 }
+async function resolveObservationsMissionPush(apiUrl, bankId, configured, profileName, label) {
+  if (configured)
+    return configured;
+  const profileDefault = PROFILE_MEMORY_DEFAULTS[profileName]?.observations_mission;
+  const current = await fetchBankObservationsMission(apiUrl, bankId, { timeoutMs: 5000 });
+  if (!current.ok) {
+    console.warn(`  ${source_default.yellow("\u26a0")} Could not read current observations_mission for ${label} (${current.reason}) \u2014 leaving it untouched`);
+    return;
+  }
+  const decision = decideObservationsMissionUpgrade(configured, profileDefault, current.mission);
+  if (decision.action === "upgrade") {
+    console.log(`  ${source_default.green("\u2713")} Seeding default observations_mission for ${label}`);
+  }
+  return decision.mission;
+}
 function parseDurationToSeconds(d) {
   if (!d)
     return;
@@ -29504,6 +29661,11 @@ ${body}
       if (seededRetainMission) {
         missions.retain_mission = seededRetainMission;
       }
+      delete missions.observations_mission;
+      const seededObservationsMission = await resolveObservationsMissionPush(apiUrl, hindsightBankId, agentConfig.memory?.observations_mission, agentConfig.extends ?? DEFAULT_PROFILE, formatAgentBankLabel(name, hindsightBankId));
+      if (seededObservationsMission) {
+        missions.observations_mission = seededObservationsMission;
+      }
       if (userBankMission) {
         missions.bank_mission = userBankMission;
       }
@@ -30574,6 +30736,10 @@ ${body}
       const retainMission = await resolveRetainMissionPush(apiUrl, hindsightBankId, agentConfig.memory?.retain_mission, formatAgentBankLabel(name, hindsightBankId));
       if (retainMission)
         missions.retain_mission = retainMission;
+      delete missions.observations_mission;
+      const observationsMission = await resolveObservationsMissionPush(apiUrl, hindsightBankId, agentConfig.memory?.observations_mission, agentConfig.extends ?? DEFAULT_PROFILE, formatAgentBankLabel(name, hindsightBankId));
+      if (observationsMission)
+        missions.observations_mission = observationsMission;
       if (Object.keys(missions).length > 0) {
         await updateBankMissions(apiUrl, hindsightBankId, missions, { timeoutMs: 5000 }).then((result) => {
           if (result.ok) {
@@ -45612,6 +45778,7 @@ var exports_provision = {};
 __export(exports_provision, {
   validateKey: () => validateKey,
   updateKeyModels: () => updateKeyModels,
+  updateKeyBudget: () => updateKeyBudget,
   ensureTeam: () => ensureTeam,
   ensureKey: () => ensureKey,
   bindKeyToTeam: () => bindKeyToTeam,
@@ -45733,6 +45900,12 @@ async function generateKeyOnce(opts, fetchFn) {
   if (opts.metadata && Object.keys(opts.metadata).length > 0) {
     payload.metadata = opts.metadata;
   }
+  if (opts.budget) {
+    payload.max_budget = opts.budget.maxBudget;
+    payload.budget_duration = opts.budget.budgetDuration;
+    if (opts.budget.softBudget != null)
+      payload.soft_budget = opts.budget.softBudget;
+  }
   let resp;
   try {
     resp = await fetchFn(url, {
@@ -45918,6 +46091,27 @@ async function safeText(resp) {
     return "";
   }
 }
+async function updateKeyBudget(opts, fetchFn = fetch) {
+  const url = `${normalizeBase(opts.baseUrl)}/key/update`;
+  let resp;
+  try {
+    resp = await fetchFn(url, {
+      method: "POST",
+      headers: authHeaders(opts.masterKey),
+      body: JSON.stringify({
+        key: opts.key,
+        max_budget: opts.budget.maxBudget,
+        budget_duration: opts.budget.budgetDuration
+      })
+    });
+  } catch (err) {
+    return { kind: "error", detail: err.message };
+  }
+  if (resp.ok)
+    return { kind: "ok" };
+  const body = await safeText(resp);
+  return { kind: "error", detail: `HTTP ${resp.status}: ${body.slice(0, 200)}` };
+}
 var LiteLLMProvisionError;
 var init_provision = __esm(() => {
   LiteLLMProvisionError = class LiteLLMProvisionError extends Error {
@@ -47312,6 +47506,176 @@ var init_doctor_webkite = __esm(() => {
   init_loader();
 });
 
+// src/openrouter/credit.ts
+function num(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+function parseKeySnapshot(body) {
+  if (body == null || typeof body !== "object")
+    return null;
+  const data = body.data;
+  if (data == null || typeof data !== "object")
+    return null;
+  const d = data;
+  if (num(d.usage) == null)
+    return null;
+  return {
+    label: typeof d.label === "string" ? d.label : null,
+    limit: num(d.limit),
+    limitRemaining: num(d.limit_remaining),
+    limitReset: typeof d.limit_reset === "string" ? d.limit_reset : null,
+    usage: num(d.usage),
+    isFreeTier: typeof d.is_free_tier === "boolean" ? d.is_free_tier : null
+  };
+}
+function evaluateCredit(snapshot) {
+  const usage = snapshot.usage ?? 0;
+  if (snapshot.limit == null || snapshot.limitRemaining == null) {
+    return {
+      status: "warn",
+      detail: `OpenRouter key has NO per-key credit limit set, so its remaining credit cannot be measured. ` + `GET /api/v1/key reports limit/limit_remaining as null when a key is uncapped, and the response ` + `carries no account-balance field \u2014 so there is nothing to threshold and this check CANNOT warn ` + `you before the account runs dry. (Key has spent $${usage.toFixed(2)} all-time.)`,
+      fix: `Set a per-key credit limit at ${OPENROUTER_KEYS_URL} (vault key: \`${OPENROUTER_VAULT_KEY}\`). ` + `That is what makes proactive monitoring possible at all, and it bounds the damage if the proxy ` + `key ever leaks. This is a manual console action \u2014 OpenRouter exposes no API to set it.`,
+      actionable: false
+    };
+  }
+  const { limit, limitRemaining } = snapshot;
+  const fraction = limit > 0 ? limitRemaining / limit : 0;
+  const reset = snapshot.limitReset ? ` (resets: ${snapshot.limitReset})` : " (never resets)";
+  const where = `$${limitRemaining.toFixed(2)} of $${limit.toFixed(2)} remaining${reset}`;
+  if (limitRemaining <= 0) {
+    return {
+      status: "fail",
+      detail: `OpenRouter key credit is EXHAUSTED \u2014 ${where}. Every request through it is answering HTTP 402.`,
+      fix: `Top up at ${OPENROUTER_CREDITS_URL} or raise the key's limit at ${OPENROUTER_KEYS_URL} (vault key: \`${OPENROUTER_VAULT_KEY}\`).`,
+      actionable: true
+    };
+  }
+  if (fraction < FAIL_REMAINING_FRACTION || limitRemaining < FAIL_REMAINING_USD) {
+    return {
+      status: "fail",
+      detail: `OpenRouter key credit is CRITICALLY low \u2014 ${where}. A single busy session can exhaust it.`,
+      fix: `Top up at ${OPENROUTER_CREDITS_URL} or raise the key's limit at ${OPENROUTER_KEYS_URL} (vault key: \`${OPENROUTER_VAULT_KEY}\`).`,
+      actionable: true
+    };
+  }
+  if (fraction < WARN_REMAINING_FRACTION || limitRemaining < WARN_REMAINING_USD) {
+    return {
+      status: "warn",
+      detail: `OpenRouter key credit is running low \u2014 ${where}.`,
+      fix: `Top up at ${OPENROUTER_CREDITS_URL} before it reaches zero (vault key: \`${OPENROUTER_VAULT_KEY}\`).`,
+      actionable: true
+    };
+  }
+  return {
+    status: "ok",
+    detail: `OpenRouter key credit healthy \u2014 ${where}.`,
+    actionable: false
+  };
+}
+async function fetchKeySnapshot(apiKey, fetchFn, signal) {
+  let resp;
+  try {
+    resp = await fetchFn(OPENROUTER_KEY_ENDPOINT, {
+      headers: { authorization: `Bearer ${apiKey}` },
+      signal
+    });
+  } catch (err) {
+    return { kind: "unreachable", detail: err.message };
+  }
+  if (resp.status === 401 || resp.status === 403) {
+    return { kind: "unauthorized", status: resp.status };
+  }
+  if (!resp.ok)
+    return { kind: "unreachable", detail: `HTTP ${resp.status}` };
+  let body;
+  try {
+    body = await resp.json();
+  } catch {
+    return { kind: "unexpected-shape" };
+  }
+  const snapshot = parseKeySnapshot(body);
+  if (snapshot == null)
+    return { kind: "unexpected-shape" };
+  return { kind: "ok", snapshot };
+}
+function assessFetchFailure(result) {
+  switch (result.kind) {
+    case "unauthorized":
+      return {
+        status: "fail",
+        detail: `OpenRouter rejected the credit query with HTTP ${result.status} \u2014 the key is invalid, revoked or disabled.`,
+        fix: `Re-issue the key at ${OPENROUTER_KEYS_URL} and update the vault entry \`${OPENROUTER_VAULT_KEY}\`.`,
+        actionable: true
+      };
+    case "unexpected-shape":
+      return {
+        status: "warn",
+        detail: `OpenRouter's GET /api/v1/key returned an unrecognised body, so credit could not be read. ` + `Treated as UNKNOWN, not as healthy \u2014 the API shape may have changed.`,
+        fix: `Re-check https://openrouter.ai/docs/api-reference/limits against src/openrouter/credit.ts.`,
+        actionable: false
+      };
+    case "unreachable":
+      return {
+        status: "skip",
+        detail: `Could not reach OpenRouter to check credit (${result.detail}).`,
+        actionable: false
+      };
+  }
+}
+var WARN_REMAINING_FRACTION = 0.25, WARN_REMAINING_USD = 10, FAIL_REMAINING_FRACTION = 0.1, FAIL_REMAINING_USD = 3, OPENROUTER_VAULT_KEY = "openrouter/api-key", OPENROUTER_KEYS_URL = "https://openrouter.ai/settings/keys", OPENROUTER_CREDITS_URL = "https://openrouter.ai/credits", OPENROUTER_KEY_ENDPOINT = "https://openrouter.ai/api/v1/key";
+
+// src/cli/doctor-openrouter-credit.ts
+async function runOpenRouterCreditChecks(deps) {
+  if (!deps.enabled) {
+    return [
+      {
+        name: CHECK_NAME2,
+        status: "skip",
+        detail: "No OpenRouter-backed model is configured in the LiteLLM proxy config."
+      }
+    ];
+  }
+  let apiKey;
+  try {
+    apiKey = await deps.readSecret(OPENROUTER_VAULT_KEY);
+  } catch (err) {
+    return [
+      {
+        name: CHECK_NAME2,
+        status: "skip",
+        detail: `Could not read vault key \`${OPENROUTER_VAULT_KEY}\` (${err.message}).`
+      }
+    ];
+  }
+  if (!apiKey) {
+    return [
+      {
+        name: CHECK_NAME2,
+        status: "warn",
+        detail: `The proxy routes through OpenRouter but vault key \`${OPENROUTER_VAULT_KEY}\` is not ` + `readable here, so credit cannot be monitored.`,
+        fix: `Grant read access to \`${OPENROUTER_VAULT_KEY}\`, or store it if it is missing.`
+      }
+    ];
+  }
+  const fetched = await fetchKeySnapshot(apiKey, deps.fetchFn);
+  const assessment = fetched.kind === "ok" ? evaluateCredit(fetched.snapshot) : assessFetchFailure(fetched);
+  return [
+    {
+      name: CHECK_NAME2,
+      status: assessment.status,
+      detail: assessment.detail,
+      ...assessment.fix ? { fix: assessment.fix } : {}
+    }
+  ];
+}
+function usesOpenRouter(litellmConfigText) {
+  if (!litellmConfigText)
+    return false;
+  return litellmConfigText.includes("openrouter/") || litellmConfigText.includes("OPENROUTER_API_KEY");
+}
+var CHECK_NAME2 = "OpenRouter credit";
+var init_doctor_openrouter_credit = () => {};
+
 // src/cli/doctor-cron-session.ts
 import { statSync as realStatSync } from "node:fs";
 import { resolve as resolve38 } from "node:path";
@@ -47388,18 +47752,18 @@ function parseEpisode(raw) {
   if (typeof raw !== "object" || raw === null)
     return null;
   const r = raw;
-  const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : null;
-  const firstTs = num(r.firstTs);
-  const untilTs = num(r.untilTs);
-  const peak = num(r.peakRetryAfterSec);
+  const num2 = (v) => typeof v === "number" && Number.isFinite(v) ? v : null;
+  const firstTs = num2(r.firstTs);
+  const untilTs = num2(r.untilTs);
+  const peak = num2(r.peakRetryAfterSec);
   if (firstTs === null || untilTs === null || peak === null)
     return null;
   return {
     firstTs,
-    lastTs: num(r.lastTs) ?? firstTs,
+    lastTs: num2(r.lastTs) ?? firstTs,
     peakRetryAfterSec: peak,
     untilTs,
-    count: num(r.count) ?? 1
+    count: num2(r.count) ?? 1
   };
 }
 function readFlood429LedgerResult(path6, readFile2 = (p) => readFileSync63(p, "utf-8")) {
@@ -47571,6 +47935,25 @@ var init_doctor_flood_pressure = __esm(() => {
   FIX2 = "A flood ban is server-side and cannot be cleared early \u2014 cut the outbound " + "rate that earns it. Check the gateway's `send-gate stats` and " + "`edit-flood-fuse` lines for the class doing the sending (progress cards and " + "the worker feed are the usual culprits), and see " + "`telegram-plugin/edit-flood-fuse.ts` for the per-class ceilings.";
 });
 
+// src/litellm/budget.ts
+function resolveKeyBudget(config) {
+  const raw = config?.max_budget;
+  const maxBudget = raw === undefined ? DEFAULT_KEY_MAX_BUDGET_USD : raw;
+  if (!Number.isFinite(maxBudget) || maxBudget <= 0)
+    return null;
+  const budgetDuration = config?.budget_duration && config.budget_duration.length > 0 ? config.budget_duration : DEFAULT_KEY_BUDGET_DURATION;
+  const rawSoft = config?.soft_budget ?? DEFAULT_KEY_SOFT_BUDGET_USD;
+  const softBudget = Number.isFinite(rawSoft) && rawSoft > 0 && rawSoft < maxBudget ? rawSoft : undefined;
+  return { maxBudget, softBudget, budgetDuration };
+}
+function describeKeyBudget(budget) {
+  if (budget == null)
+    return "no spend cap (uncapped key)";
+  const soft = budget.softBudget != null ? `, alert at $${budget.softBudget}` : "";
+  return `cap $${budget.maxBudget}/${budget.budgetDuration}${soft}`;
+}
+var DEFAULT_KEY_MAX_BUDGET_USD = 25, DEFAULT_KEY_SOFT_BUDGET_USD = 15, DEFAULT_KEY_BUDGET_DURATION = "30d";
+
 // examples/switchroom.yaml
 var switchroom_default = `# switchroom.yaml \u2014 Full example configuration
 #
@@ -48725,7 +49108,7 @@ async function provisionLiteLLMKeys(config, agentNames, switchroomConfigPath, ct
   let brokerKeyMaterialized = false;
   const [
     { getViaBrokerStructured: getViaBrokerStructured2, putViaBroker: putViaBroker2 },
-    { ensureTeam: ensureTeam2, ensureKey: ensureKey2, validateKey: validateKey2, bindKeyToTeam: bindKeyToTeam2, updateKeyModels: updateKeyModels2 },
+    { ensureTeam: ensureTeam2, ensureKey: ensureKey2, validateKey: validateKey2, bindKeyToTeam: bindKeyToTeam2, updateKeyModels: updateKeyModels2, updateKeyBudget: updateKeyBudget2 },
     { addAgentSecret: addAgentSecret2 }
   ] = await Promise.all([
     Promise.resolve().then(() => (init_client(), exports_client)),
@@ -48806,6 +49189,11 @@ async function provisionLiteLLMKeys(config, agentNames, switchroomConfigPath, ct
       const baseUrl = litellm.base_url ?? topLevel?.base_url;
       const team = litellm.team ?? topLevel?.team ?? "switchroom";
       const adminKeyRef = litellm.admin_key ?? topLevel?.admin_key;
+      const budget = resolveKeyBudget({
+        max_budget: litellm.max_budget ?? topLevel?.max_budget,
+        soft_budget: litellm.soft_budget ?? topLevel?.soft_budget,
+        budget_duration: litellm.budget_duration ?? topLevel?.budget_duration
+      });
       if (!baseUrl || !adminKeyRef) {
         failures.push({
           agent: name,
@@ -48887,6 +49275,16 @@ async function provisionLiteLLMKeys(config, agentNames, switchroomConfigPath, ct
           writeOut(source_default.gray(`  ~ litellm/${name}: key already provisioned (skipped)
 `));
         }
+        if (!driftReprovision && storedKey && masterKey && budget) {
+          const cap = await updateKeyBudget2({ baseUrl, masterKey, key: storedKey, budget });
+          if (cap.kind === "ok") {
+            writeOut(source_default.gray(`  ~ litellm/${name}: spend ${describeKeyBudget(budget)}${budget.softBudget != null ? " (soft budget applies to newly generated keys only)" : ""}
+`));
+          } else {
+            ctx.writeErr(source_default.yellow(`  ! litellm/${name}: could NOT apply the spend cap (${cap.detail}) \u2014 ` + `this key remains UNCAPPED and can spend the whole upstream account balance. Manual: POST ${baseUrl}/key/update {"key":"<key>","max_budget":${budget.maxBudget},"budget_duration":"${budget.budgetDuration}"}.
+`));
+          }
+        }
         if (!driftReprovision) {
           if (configText !== null) {
             const after = addAgentSecret2(configText, name, vaultKey);
@@ -48923,6 +49321,7 @@ async function provisionLiteLLMKeys(config, agentNames, switchroomConfigPath, ct
         alias,
         teamId,
         metadata,
+        ...budget ? { budget } : {},
         log: (m) => ctx.writeErr(source_default.gray(`  ~ litellm/${name}: ${m}
 `))
       });
@@ -52352,6 +52751,7 @@ __export(exports_doctor, {
   checkDepsCacheWritable: () => checkDepsCacheWritable,
   checkDeployMounts: () => checkDeployMounts,
   checkConfig: () => checkConfig,
+  checkBankObservationsMissions: () => checkBankObservationsMissions,
   checkBankIngestHealth: () => checkBankIngestHealth,
   checkAgents: () => checkAgents,
   buildPendingRetainsProbeScript: () => buildPendingRetainsProbeScript,
@@ -52372,6 +52772,20 @@ import {
 } from "node:fs";
 import { dirname as dirname31, join as join81, resolve as resolve44 } from "node:path";
 import { createPublicKey, createPrivateKey } from "node:crypto";
+function readLitellmConfigText() {
+  const candidates = [
+    process.env.LITELLM_CONFIG_PATH,
+    "/data/coolify/services/litellm/litellm-config.yaml",
+    join81(process.cwd(), "docker", "litellm-proxy", "litellm-config.yaml")
+  ].filter((p) => typeof p === "string" && p.length > 0);
+  for (const p of candidates) {
+    try {
+      if (existsSync77(p))
+        return readFileSync71(p, "utf-8");
+    } catch {}
+  }
+  return null;
+}
 function findInNvm(bin) {
   const nvmRoot = join81(process.env.HOME ?? "", ".nvm", "versions", "node");
   if (!existsSync77(nvmRoot))
@@ -53041,6 +53455,58 @@ function probeAuthBrokerSocket(consumerName) {
     return "unreachable";
   return "missing";
 }
+async function checkBankObservationsMissions(config, url, opts) {
+  const banks = new Map;
+  for (const [agentName, agentConfig] of Object.entries(config.agents)) {
+    const resolved = resolveAgentConfig(config.defaults, config.profiles, agentConfig);
+    const bankId = resolved.memory?.collection ?? agentName;
+    const existing = banks.get(bankId);
+    if (existing)
+      existing.agents.push(agentName);
+    else
+      banks.set(bankId, { agents: [agentName], config: resolved });
+  }
+  const inspected = await Promise.all([...banks].map(async ([bankId, entry]) => [
+    bankId,
+    entry,
+    await fetchBankObservationsMission(url, bankId, { fetchImpl: opts?.fetchImpl })
+  ]));
+  return inspected.map(([bankId, entry, read]) => {
+    const label = `bank ${bankId} observations_mission` + (entry.agents[0] !== bankId ? ` (${entry.agents.join(", ")})` : "");
+    const firstAgent = entry.agents[0];
+    if (!read.ok) {
+      return {
+        name: label,
+        status: "warn",
+        detail: `could not read observations_mission: ${read.reason}`
+      };
+    }
+    const profileDefault = PROFILE_MEMORY_DEFAULTS[entry.config.extends ?? DEFAULT_PROFILE]?.observations_mission;
+    const decision = decideObservationsMissionUpgrade(entry.config.memory?.observations_mission, profileDefault, read.mission);
+    if (decision.action === "upgrade") {
+      return {
+        name: label,
+        status: "warn",
+        detail: read.mission == null || read.mission.trim() === "" ? "unset \u2014 this bank consolidates under Hindsight's stock mission, not switchroom's" : "carrying a superseded switchroom default",
+        fix: `Run: switchroom agent reconcile ${firstAgent}`
+      };
+    }
+    if (decision.action === "config") {
+      return read.mission === decision.mission ? { name: label, status: "ok", detail: "set from switchroom.yaml" } : {
+        name: label,
+        status: "warn",
+        detail: "switchroom.yaml sets a different observations_mission than the bank carries",
+        fix: `Run: switchroom agent reconcile ${firstAgent}`
+      };
+    }
+    const isSwitchroomDefault = read.mission === (profileDefault ?? DEFAULT_OBSERVATIONS_MISSION);
+    return {
+      name: label,
+      status: "ok",
+      detail: isSwitchroomDefault ? profileDefault != null ? `switchroom ${entry.config.extends ?? DEFAULT_PROFILE}-profile default` : "switchroom fleet default" : "operator-authored (left untouched by the never-clobber rule)"
+    };
+  });
+}
 async function checkBankIngestHealth(config, url, opts) {
   const results = [];
   const now = opts?.now ?? new Date;
@@ -53200,6 +53666,7 @@ async function checkHindsight(config) {
   results.push(checkHnswPartialIndexes());
   results.push(await checkHindsightHealthEndpoint(url));
   results.push(...await checkBankIngestHealth(config, url, { includeConsolidationBacklog: true }));
+  results.push(...await checkBankObservationsMissions(config, url));
   const memoryAgentsDir = resolveAgentsDir(config);
   for (const agentName of Object.keys(config.agents)) {
     results.push(checkAgentRecallHealth(agentName, resolve44(memoryAgentsDir, agentName)));
@@ -53314,7 +53781,7 @@ function checkPendingRetainsQueues(config, opts) {
     }
   }
   const skippedNote = unreachable.length > 0 ? `; skipped (unreachable): ${unreachable.join(", ")}` : "";
-  const backlogFix = `Clear a backlog explicitly (the SessionStart drain cannot \u2014 its per-entry ` + `timeout is clamped to the hook budget, far below a real retain): ` + `\`docker exec switchroom-<agent> python3 ` + `/state/agent/.claude/plugins/hindsight-memory/scripts/drain_pending.py --backlog\`. ` + `Run \`--phase reconcile\` first \u2014 it costs nothing and typically clears most of ` + `the queue by confirming those documents already exist. PACE THE REST: the retain ` + `model pool is small and shared with live traffic, so drain ONE agent at a time at ` + `the default HINDSIGHT_DRAIN_CONCURRENCY=1, and keep HINDSIGHT_DRAIN_SLEEP_S set. ` + `Point HINDSIGHT_DRAIN_P95_CMD at the same figure the latency watchdog alarms on so ` + `the replay backs off instead of causing the alarm \u2014 on a LiteLLM deployment that is ` + `\`docker exec -i <postgres> psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -At -c ` + `"select coalesce((select round(percentile_cont(0.95) within group (order by ` + `request_duration_ms)) from \\"LiteLLM_SpendLogs\\" where \\"startTime\\" > now() ` + `- interval '10 minutes' and metadata->>'user_api_key_alias' like 'hindsight-%' and ` + `status='success' and request_duration_ms is not null), -1)"\` (must print a ` + `millisecond integer on stdout; unset = no backoff). Fix the upstream first (bank ` + `health rows above), or every retry just ages entries toward .dead. Entries the ` + `drain retires are MOVED to \`.hindsight/pending-reconciled/\` (bounded, so they ` + `expire), never deleted \u2014 every retire rests on an HTTP 200, which is an ack and ` + `not proof, so the payload stays recoverable. If that archive cannot be written ` + `(disk full, permissions) the entry STAYS QUEUED and the drain says so on stderr; ` + `a failure to archive is never a reason to delete. FIX THE DISK ANYWAY \u2014 "stays ` + `queued" is bounded: entries pile up, the queue hits ` + `HINDSIGHT_PENDING_MAX_ENTRIES/MAX_BYTES, and enqueue then sheds the OLDEST ` + `entries to keep accepting the newest. While the disk is full their archive move ` + `fails too, so those oldest turns are removed outright (the ledger line reads ` + `\`reason=...+archive-failed\`). Under sustained ENOSPC "keep it queued" degrades ` + `to "keep the newest, drop the oldest".`;
+  const backlogFix = `Clear a backlog explicitly (the SessionStart drain cannot \u2014 its per-entry ` + `timeout is clamped to the hook budget, far below a real retain): ` + `\`docker exec switchroom-<agent> python3 ` + `/state/agent/.claude/plugins/hindsight-memory/scripts/drain_pending.py --backlog\`. ` + `Run \`--phase reconcile\` first \u2014 it costs nothing and typically clears most of ` + `the queue by confirming those documents already exist. PACE THE REST: the retain ` + `model pool is small and shared with live traffic, so drain ONE agent at a time at ` + `the default HINDSIGHT_DRAIN_CONCURRENCY=1, and keep HINDSIGHT_DRAIN_SLEEP_S set. ` + `Point HINDSIGHT_DRAIN_P95_CMD at the same figure the latency watchdog alarms on so ` + `the replay backs off instead of causing the alarm \u2014 on a LiteLLM deployment that is ` + `\`docker exec -i <postgres> psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -At -c ` + `"select coalesce((select round(percentile_cont(0.95) within group (order by ` + `request_duration_ms)) from \\"LiteLLM_SpendLogs\\" where \\"startTime\\" > now() ` + `- interval '10 minutes' and metadata->>'user_api_key_alias' like 'hindsight-%' and ` + `status='success' and request_duration_ms is not null), -1)"\` (must print a ` + `millisecond integer on stdout; unset = no backoff). ` + `SAFE ALONGSIDE THE \`hindsight-drain\` SIDECAR and a session booting underneath ` + `you: drain_pending.py takes an exclusive lock on ` + `\`$HOME/.hindsight/drain-pending.lock\` for the whole run, so whichever drain ` + `starts second prints "another drain holds ..." and exits without touching the ` + `queue. Do NOT wrap this in \`flock\` on that path yourself \u2014 you would hold the ` + `lock the script then asks for, and it would skip every time. Entries past the ` + `attempt ceiling (HINDSIGHT_DRAIN_ATTEMPT_CEILING, default 20) are PARKED and ` + `reported rather than retried forever; add \`--force\` once the upstream is fixed ` + `to replay them. ` + `Fix the upstream first (bank ` + `health rows above), or every retry just ages entries toward .dead. Entries the ` + `drain retires are MOVED to \`.hindsight/pending-reconciled/\` (bounded, so they ` + `expire), never deleted \u2014 every retire rests on an HTTP 200, which is an ack and ` + `not proof, so the payload stays recoverable. If that archive cannot be written ` + `(disk full, permissions) the entry STAYS QUEUED and the drain says so on stderr; ` + `a failure to archive is never a reason to delete. FIX THE DISK ANYWAY \u2014 "stays ` + `queued" is bounded: entries pile up, the queue hits ` + `HINDSIGHT_PENDING_MAX_ENTRIES/MAX_BYTES, and enqueue then sheds the OLDEST ` + `entries to keep accepting the newest. While the disk is full their archive move ` + `fails too, so those oldest turns are removed outright (the ledger line reads ` + `\`reason=...+archive-failed\`). Under sustained ENOSPC "keep it queued" degrades ` + `to "keep the newest, drop the oldest".`;
   if (dead.length > 0 || dropped.length > 0 || evicted.length > 0) {
     const parts = [];
     if (dead.length > 0)
@@ -54506,6 +54973,25 @@ function registerDoctorCommand(program3) {
       },
       { title: "MFF Skill", results: await checkMff(passphrase, vaultPath, config) },
       { title: "Webkite", results: runWebkiteChecks(config) },
+      {
+        title: "OpenRouter Credit",
+        results: await runOpenRouterCreditChecks({
+          enabled: usesOpenRouter(readLitellmConfigText()),
+          readSecret: async (key) => {
+            try {
+              const { getViaBrokerStructured: getViaBrokerStructured2 } = await Promise.resolve().then(() => (init_client(), exports_client));
+              const result = await getViaBrokerStructured2(key);
+              if (result.kind === "ok" && result.entry.kind === "string") {
+                return result.entry.value;
+              }
+              return null;
+            } catch {
+              return null;
+            }
+          },
+          fetchFn: (url, init) => fetch(url, { headers: init?.headers, signal: init?.signal ?? AbortSignal.timeout(1e4) })
+        })
+      },
       { title: "Cron Session", results: runCronSessionChecks(config) },
       {
         title: "Generated-surface drift (KEN-130)",
@@ -54573,6 +55059,7 @@ var init_doctor = __esm(() => {
   init_scaffold();
   init_manager();
   init_accounts();
+  init_schema();
   init_manifest();
   init_hindsight2();
   init_hindsight();
@@ -54589,6 +55076,7 @@ var init_doctor = __esm(() => {
   init_doctor_hostd();
   init_doctor_drive();
   init_doctor_webkite();
+  init_doctor_openrouter_credit();
   init_doctor_cron_session();
   init_doctor_flood_pressure();
   init_doctor_drift();
@@ -101885,25 +102373,25 @@ function syncIssue(deps, repo, job_spec, iss) {
     }
     return;
   }
-  const num = String(iss.gh_issue);
-  const upd = deps.run(["issue", "edit", num, "-R", repo, "--body", body]);
+  const num2 = String(iss.gh_issue);
+  const upd = deps.run(["issue", "edit", num2, "-R", repo, "--body", body]);
   if (!upd.ok) {
-    deps.log(`fleet-health: gh issue edit #${num} failed: ${upd.stderr}`);
+    deps.log(`fleet-health: gh issue edit #${num2} failed: ${upd.stderr}`);
   }
   if (iss.status === "closed") {
     const c = deps.run([
       "issue",
       "close",
-      num,
+      num2,
       "-R",
       repo,
       "--comment",
       `Verified count-drop (frequency ${iss.frequency} \u2264 resolved threshold). Closed by the Fleet Health sensor.`
     ]);
     if (c.ok)
-      deps.log(`fleet-health: closed GH #${num} (count-drop) for ${iss.dedup_key}`);
+      deps.log(`fleet-health: closed GH #${num2} (count-drop) for ${iss.dedup_key}`);
     else
-      deps.log(`fleet-health: gh issue close #${num} failed: ${c.stderr}`);
+      deps.log(`fleet-health: gh issue close #${num2} failed: ${c.stderr}`);
   }
 }
 function syncLedgerIssues(ledger, repo, deps) {
@@ -103275,6 +103763,278 @@ async function notifyOperator(agentsDir, text, log) {
   return agent !== null;
 }
 
+// src/cli/openrouter-watch.ts
+init_source();
+import { existsSync as existsSync113, readdirSync as readdirSync46 } from "node:fs";
+import { homedir as homedir64 } from "node:os";
+import { join as join112, resolve as resolve65 } from "node:path";
+
+// src/openrouter/install-cron.ts
+import { existsSync as existsSync112, mkdirSync as mkdirSync63, readFileSync as readFileSync99, renameSync as renameSync28, writeFileSync as writeFileSync47 } from "node:fs";
+import { dirname as dirname42 } from "node:path";
+var CRON_PATH2 = "/etc/cron.d/openrouter-watch";
+var CRON_SCHEDULE2 = "17 * * * *";
+var CRON_LOG_PATH2 = "/var/log/openrouter-watch.log";
+var CRON_LOCK_PATH2 = "/run/lock/openrouter-watch.lock";
+function renderCron2(opts) {
+  return `# switchroom openrouter-watch \u2014 model-free OpenRouter credit watchdog.
+` + `# Managed by \`switchroom openrouter-watch --install-cron\`; edits are overwritten.
+` + `# Exit 0 = clean, 10 = credit signal firing (DM sent), 1 = the check could not complete.
+` + `SHELL=/bin/sh
+` + `PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+` + `${CRON_SCHEDULE2} ${opts.user} /usr/bin/flock -n ${CRON_LOCK_PATH2} ` + `${opts.binary} openrouter-watch >> ${CRON_LOG_PATH2} 2>&1
+`;
+}
+function installCron2(opts) {
+  const path10 = opts.path ?? CRON_PATH2;
+  const content = renderCron2(opts);
+  if (existsSync112(path10)) {
+    try {
+      if (readFileSync99(path10, "utf8") === content) {
+        return { status: "unchanged", path: path10, content };
+      }
+    } catch {}
+  }
+  mkdirSync63(dirname42(path10), { recursive: true });
+  const tmp = `${path10}.${process.pid}.tmp`;
+  writeFileSync47(tmp, content, { mode: 420 });
+  renameSync28(tmp, path10);
+  return { status: "installed", path: path10, content };
+}
+// src/openrouter/state.ts
+import { mkdirSync as mkdirSync64, readFileSync as readFileSync100, renameSync as renameSync29, writeFileSync as writeFileSync48 } from "node:fs";
+import { homedir as homedir63 } from "node:os";
+import { dirname as dirname43, resolve as resolve64 } from "node:path";
+function defaultStatePath3(home2 = process.env.SWITCHROOM_HOME ?? process.env.HOME ?? homedir63()) {
+  return resolve64(home2, ".switchroom", "openrouter-watch", "state.json");
+}
+function loadState2(path10) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync100(path10, "utf8"));
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== "object" || parsed === null)
+    return {};
+  const s = parsed;
+  if (s.v !== 1)
+    return {};
+  const out = {};
+  if (typeof s.lastNotifiedAt === "number" && Number.isFinite(s.lastNotifiedAt)) {
+    out.lastNotifiedAt = s.lastNotifiedAt;
+  }
+  if (typeof s.lastNotifiedStatus === "string")
+    out.lastNotifiedStatus = s.lastNotifiedStatus;
+  if (out.lastNotifiedAt === undefined)
+    delete out.lastNotifiedStatus;
+  return out;
+}
+function saveState2(path10, state) {
+  mkdirSync64(dirname43(path10), { recursive: true, mode: 448 });
+  const tmp = `${path10}.${process.pid}.tmp`;
+  const payload = { v: 1, ...state };
+  writeFileSync48(tmp, JSON.stringify(payload, null, 2) + `
+`, { mode: 384 });
+  renameSync29(tmp, path10);
+}
+
+// src/openrouter/watch.ts
+var RENOTIFY_MS2 = 6 * 60 * 60 * 1000;
+function decideNotification(assessment, state, now) {
+  if (!assessment.actionable) {
+    return { notice: null, nextState: {}, firing: false };
+  }
+  const escalated = state.lastNotifiedStatus != null && state.lastNotifiedStatus !== "fail" && assessment.status === "fail";
+  const cooled = state.lastNotifiedAt == null || now - state.lastNotifiedAt >= RENOTIFY_MS2;
+  if (!escalated && !cooled) {
+    return { notice: null, nextState: state, firing: true };
+  }
+  const repeat = state.lastNotifiedAt != null && !escalated;
+  return {
+    notice: renderNotice(assessment, { repeat, escalated }),
+    nextState: { lastNotifiedAt: now, lastNotifiedStatus: assessment.status },
+    firing: true
+  };
+}
+function renderNotice(assessment, opts) {
+  const head = assessment.status === "fail" ? opts.escalated ? "\uD83D\uDEA8 OpenRouter credit \u2014 ESCALATED" : "\uD83D\uDEA8 OpenRouter credit" : "\u26a0\ufe0f OpenRouter credit";
+  const suffix = opts.repeat && !opts.escalated ? " (still unresolved)" : "";
+  return [
+    `${head}${suffix}`,
+    assessment.detail,
+    assessment.fix ? `\u2192 ${assessment.fix}` : ""
+  ].filter((l) => l.length > 0).join(`
+`);
+}
+
+// src/openrouter/run.ts
+async function tick2(deps) {
+  const now = deps.now?.() ?? Date.now();
+  let apiKey = null;
+  try {
+    apiKey = await deps.readSecret(OPENROUTER_VAULT_KEY);
+  } catch (err2) {
+    deps.log(`openrouter-watch: vault read failed for \`${OPENROUTER_VAULT_KEY}\`: ${err2.message}`);
+  }
+  if (!apiKey) {
+    deps.log(`openrouter-watch: vault key \`${OPENROUTER_VAULT_KEY}\` is not readable \u2014 credit cannot be checked.`);
+    return {
+      assessment: {
+        status: "skip",
+        detail: `Vault key \`${OPENROUTER_VAULT_KEY}\` unreadable.`,
+        actionable: false
+      },
+      notice: null,
+      firing: false,
+      delivered: false,
+      exitCode: 1
+    };
+  }
+  const fetched = await fetchKeySnapshot(apiKey, deps.fetchFn);
+  const assessment = fetched.kind === "ok" ? evaluateCredit(fetched.snapshot) : assessFetchFailure(fetched);
+  const prior = loadState2(deps.statePath);
+  const decision = decideNotification(assessment, prior, now);
+  let delivered = false;
+  if (decision.notice && !deps.dryRun) {
+    delivered = await deps.notify(decision.notice);
+  }
+  if (!deps.dryRun && (decision.notice === null || delivered)) {
+    try {
+      saveState2(deps.statePath, decision.nextState);
+    } catch (err2) {
+      deps.log(`openrouter-watch: could not persist state: ${err2.message}`);
+      return { assessment, notice: decision.notice, firing: decision.firing, delivered, exitCode: 1 };
+    }
+  }
+  if (decision.notice && !deps.dryRun && !delivered) {
+    deps.log("openrouter-watch: alert reached no gateway \u2014 undelivered, will retry next tick");
+    return { assessment, notice: decision.notice, firing: decision.firing, delivered, exitCode: 1 };
+  }
+  const cannotComplete = fetched.kind === "unreachable";
+  const exitCode = cannotComplete ? 1 : decision.firing ? 10 : 0;
+  return { assessment, notice: decision.notice, firing: decision.firing, delivered, exitCode };
+}
+// src/cli/openrouter-watch.ts
+function registerOpenRouterWatchCommand(program3) {
+  program3.command("openrouter-watch").description("Model-free OpenRouter credit watchdog: warns before the key's credit runs out. " + "Alerts at most once per 6h, and escalates immediately.").option("--install-cron", `arm the watchdog: write ${CRON_PATH2} (${CRON_SCHEDULE2}, flock-guarded) and exit`, false).option("--cron-user <user>", "unix user the cron tick runs as (default: current user)").option("--dry-run", "evaluate and print; send no DM and write no state", false).option("--json", "emit machine-readable JSON", false).option("--state <path>", "state file path (default ~/.switchroom/openrouter-watch/state.json)").option("--agents-dir <path>", "agents scaffold dir (default ~/.switchroom/agents)").action(async (opts) => {
+    if (opts.installCron) {
+      process.exitCode = runInstallCron2(opts.cronUser);
+      return;
+    }
+    const agentsDir = opts.agentsDir ?? process.env.SWITCHROOM_AGENTS_DIR ?? join112(process.env.SWITCHROOM_HOME ?? process.env.HOME ?? homedir64(), ".switchroom", "agents");
+    const statePath = opts.state ?? defaultStatePath3();
+    const log = (m) => {
+      process.stderr.write(`${m}
+`);
+    };
+    const result = await tick2({
+      statePath,
+      dryRun: Boolean(opts.dryRun),
+      log,
+      readSecret: async (key) => {
+        const { getViaBrokerStructured: getViaBrokerStructured2 } = await Promise.resolve().then(() => (init_client(), exports_client));
+        const res = await getViaBrokerStructured2(key);
+        if (res.kind === "ok" && res.entry.kind === "string")
+          return res.entry.value;
+        return null;
+      },
+      fetchFn: (url, init) => fetch(url, {
+        headers: init?.headers,
+        signal: init?.signal ?? AbortSignal.timeout(1e4)
+      }),
+      notify: (text) => notifyOperator2(agentsDir, text, log)
+    });
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({
+        status: result.assessment.status,
+        detail: result.assessment.detail,
+        fix: result.assessment.fix ?? null,
+        actionable: result.assessment.actionable,
+        firing: result.firing,
+        notified: result.notice,
+        delivered: result.delivered,
+        exitCode: result.exitCode,
+        vaultKey: OPENROUTER_VAULT_KEY,
+        thresholds: {
+          warnRemainingFraction: WARN_REMAINING_FRACTION,
+          warnRemainingUsd: WARN_REMAINING_USD,
+          failRemainingFraction: FAIL_REMAINING_FRACTION,
+          failRemainingUsd: FAIL_REMAINING_USD,
+          renotifyMs: RENOTIFY_MS2
+        }
+      }, null, 2) + `
+`);
+    } else {
+      const mark = result.assessment.status === "fail" ? source_default.red("FAIL") : result.assessment.status === "warn" ? source_default.yellow("WARN") : result.assessment.status === "skip" ? source_default.gray("skip") : source_default.green("ok  ");
+      process.stdout.write(`${mark}  ${result.assessment.detail}
+`);
+      if (result.assessment.fix)
+        process.stdout.write(`      \u2192 ${result.assessment.fix}
+`);
+      if (result.notice) {
+        const header = opts.dryRun ? "would send" : result.delivered ? "sent" : "UNDELIVERED";
+        process.stdout.write(`
+${source_default.bold(`operator DM ${header}:`)}
+`);
+        process.stdout.write(result.notice.split(`
+`).map((l) => `  | ${l}`).join(`
+`) + `
+`);
+      } else if (result.firing) {
+        process.stdout.write(source_default.gray(`      (firing, but already reported within the ${RENOTIFY_MS2 / 3600000}h window)
+`));
+      }
+    }
+    process.exitCode = result.exitCode;
+  });
+}
+function runInstallCron2(cronUser) {
+  const user = cronUser ?? process.env.SUDO_USER ?? process.env.USER ?? process.env.LOGNAME;
+  if (!user || user === "root") {
+    process.stderr.write(source_default.red("openrouter-watch: refusing to install a cron for `root`.\n") + "  The state file and the agents scaffold live under the OPERATOR's " + "~/.switchroom, so a root tick would keep its re-notify ledger somewhere " + `nothing else reads.
+` + "  Re-run with `--cron-user <operator>`.\n");
+    return 1;
+  }
+  const binary = process.env.SWITCHROOM_BINARY ?? "/usr/local/bin/switchroom";
+  if (!binary.startsWith("/")) {
+    process.stderr.write(source_default.red(`openrouter-watch: SWITCHROOM_BINARY must be an absolute path (got ${binary})
+`));
+    return 1;
+  }
+  let res;
+  try {
+    res = installCron2({ user, binary });
+  } catch (e) {
+    process.stderr.write(source_default.red(`openrouter-watch: could not write ${CRON_PATH2}: ${e.message}
+`) + "  This path needs root; re-run under sudo with `--cron-user <operator>`.\n");
+    return 1;
+  }
+  const verb = res.status === "installed" ? "installed" : "already up to date";
+  process.stdout.write(`${source_default.green("\u2713")} openrouter-watch cron ${verb} at ${res.path} ` + `(${CRON_SCHEDULE2}, as ${user})
+` + `  Verify with: switchroom openrouter-watch --dry-run
+`);
+  return 0;
+}
+async function notifyOperator2(agentsDir, text, log) {
+  const candidates = [];
+  try {
+    for (const name of readdirSync46(agentsDir).sort()) {
+      const sock = resolve65(agentsDir, name, "telegram", "gateway.sock");
+      if (existsSync113(sock))
+        candidates.push({ agent: name, sock });
+    }
+  } catch (e) {
+    log(`openrouter-watch: agents dir unreadable (${e.message})`);
+  }
+  if (candidates.length === 0) {
+    log("openrouter-watch: no gateway socket found \u2014 alert undelivered, will retry next tick");
+    return false;
+  }
+  const agent = await postOperatorNoticeViaGateways(candidates, text, log, 5000, "openrouter-watch", "");
+  return agent !== null;
+}
+
 // src/cli/index.ts
 init_posthog();
 installGlobalErrorHandlers();
@@ -103334,6 +104094,7 @@ registerWebdCommand(program3);
 registerHostCommand(program3);
 registerFleetHealthCommand(program3);
 registerHindsightWatchCommand(program3);
+registerOpenRouterWatchCommand(program3);
 
 // bin/switchroom.ts
 program3.parse();