Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
feat(wiki): background wiki calls wait for the subscription and obey a runaway guard
rubenluetke10-beepbf4d9672db1c
diff --git a/jarvis.toml.example b/jarvis.toml.exampleindex a257ca1dee..23552823af 100644--- a/jarvis.toml.example+++ b/jarvis.toml.example@@ -205,6 +205,9 @@ data_dir = "./data" # per-user runtime data (gitignored)[wiki_integration]enabled = truevault_root = "wiki/obsidian-vault"+# Runaway guard: the most model calls the wiki may make on its own per day+# (it counts calls, it never shortens a prompt or an answer).+# max_background_llm_calls_per_day = 200# ── Login autostart — ON by default; toggle in Settings ──# Launches the full desktop app (voice + Orb) at login so the wake listenerdiff --git a/jarvis/core/config.py b/jarvis/core/config.pyindex dee0797da2..e8688217f1 100644--- a/jarvis/core/config.py+++ b/jarvis/core/config.py@@ -2990,6 +2990,15 @@ class WikiIntegrationConfig(BaseModel):# speaker, which is why this explicit list exists rather than a guess.search_alias_languages: list[str] = Field(default_factory=list)+ # Runaway guard on how OFTEN the wiki may call a model on its own per+ # local day (consolidator judge, split-and-retry halves, write-time search+ # aliases, explicitly saved turns' extraction). Read by+ # jarvis/memory/wiki/background_guard.py. It counts calls only — it never+ # shortens a prompt, a context window or an output budget. When reached,+ # the work waits until the next day and one log line says so. Generous on+ # purpose: a normal day needs a handful; values below 1 count as 1.+ max_background_llm_calls_per_day: int = 200+class WikiContextConfig(BaseModel):"""Configuration for the wiki context injector (B5 Agent C).diff --git a/jarvis/memory/wiki/background_guard.py b/jarvis/memory/wiki/background_guard.pynew file mode 100644index 0000000000..87fa059ed2--- /dev/null+++ b/jarvis/memory/wiki/background_guard.py@@ -0,0 +1,323 @@+"""Runaway guard for the model calls the wiki makes on its own.++The wiki calls a model without a user waiting on the answer in a few places:+the Stage-2 consolidator that files pending candidate facts, the search-alias+generator that runs for each page the consolidator writes, and the Stage-1+extractor when a turn is explicitly saved. Before this guard nothing bounded+them: a failing chain was re-tried every two minutes by the age flush and+every six hours by the auto-backfill, on whatever API key happened to be+stored. The cost ledger showed ~300 wiki calls on paid keys in 30 days, and+~5 EUR went in three hours while nobody was at the PC.++Two independent brakes live here, and both hold on key-only installs too:++* **Backoff.** When the work has to wait — the install runs on a subscription+ that is logged out, rate limited or otherwise not answering (see+ :mod:`jarvis.brain.background_policy`) — or the whole provider chain+ failed, the next attempt is pushed out exponentially (5 min, doubling,+ capped at one hour) instead of every trigger retrying at once.+* **Daily call cap.** A hard ceiling on the NUMBER of background wiki model+ calls per local day (``[wiki_integration] max_background_llm_calls_per_day``,+ default 200). Every provider attempt counts, including the split-and-retry+ halves of a truncated batch. This is purely a runaway guard on how OFTEN+ the wiki may call a model: it never shortens a prompt, a context window or+ an output budget. When the cap is reached the work waits for the next day+ and one log line says so.++The day's counter is persisted, so a crash-restart loop cannot reset it.+"""++from __future__ import annotations++import datetime as _dt+import json+import logging+import os+import tempfile+import threading+import time+from collections.abc import Callable+from pathlib import Path+from typing import Any++from jarvis.brain.background_policy import BackgroundDeferred++log = logging.getLogger(__name__)++#: Shipped default for ``[wiki_integration] max_background_llm_calls_per_day``.+#: Generous on purpose: a normal day files a handful of facts. The cap exists+#: to stop a runaway loop, never to ration ordinary use.+DEFAULT_DAILY_CALL_CAP = 200++#: First wait after a deferral or a failed chain, doubled per repeat.+_BACKOFF_BASE_S = 300.0+#: Longest wait between attempts, so a reconnected subscription is picked up+#: within the hour without anyone restarting the app.+_BACKOFF_MAX_S = 3600.0++#: Health states surfaced on the wiki health strip / ``GET /api/wiki/health``.+WAITING_FOR_SUBSCRIPTION = "waiting_for_subscription"+DAILY_CAP_REACHED = "daily_cap_reached"+++def daily_cap(config: Any) -> int:+ """The configured daily cap, never below one call.++ ``config`` is the root ``JarvisConfig``; anything without the field (a+ test double, ``None``) gets the shipped default.+ """+ section = getattr(config, "wiki_integration", None)+ raw = getattr(section, "max_background_llm_calls_per_day", None)+ if raw is None:+ return DEFAULT_DAILY_CALL_CAP+ try:+ value = int(raw)+ except (TypeError, ValueError):+ log.warning(+ "wiki background guard: unusable max_background_llm_calls_per_day %r "+ "— using the default %d",+ raw,+ DEFAULT_DAILY_CALL_CAP,+ )+ return DEFAULT_DAILY_CALL_CAP+ return max(1, value)+++def _record_wait(state: str, detail: str, retry_at: float | None) -> None:+ try:+ from jarvis.memory.wiki.health import health++ health.record_background_wait(state, detail=detail, retry_at=retry_at)+ except Exception: # noqa: BLE001 - health recording must never break the guard+ log.debug("wiki background guard: health.record_background_wait failed", exc_info=True)+++def _clear_wait() -> None:+ try:+ from jarvis.memory.wiki.health import health++ health.clear_background_wait()+ except Exception: # noqa: BLE001 - health recording must never break the guard+ log.debug("wiki background guard: health.clear_background_wait failed", exc_info=True)+++class WikiBackgroundGuard:+ """Daily call cap plus shared backoff for background wiki model calls."""++ def __init__(self) -> None:+ self._lock = threading.Lock()+ self._state_path_override: Path | None = None+ # (local day, calls) — the in-memory mirror of the persisted counter.+ # A failing disk only loses persistence, never the cap itself.+ self._day: str = ""+ self._calls: int = 0+ self._loaded = False+ self._cap_logged_day: str = ""+ self._setbacks = 0+ self._retry_at_monotonic = 0.0+ self._retry_at_wall: float | None = None+ self._last_reason = ""++ # ------------------------------------------------------------------+ # persisted daily counter+ # ------------------------------------------------------------------++ def _state_path(self) -> Path:+ if self._state_path_override is not None:+ return self._state_path_override+ from jarvis.core.paths import user_data_dir++ return user_data_dir() / "data" / "wiki_background_calls.json"++ @staticmethod+ def _today() -> str:+ return _dt.date.today().isoformat()++ def _load_locked(self) -> None:+ today = self._today()+ if self._loaded and self._day == today:+ return+ day, calls = today, 0+ try:+ raw = json.loads(self._state_path().read_text(encoding="utf-8"))+ except FileNotFoundError: # first call of the day on this install: nothing spent yet+ raw = None+ except (OSError, ValueError):+ log.warning("wiki background guard: unreadable call counter, starting at zero")+ raw = None+ if isinstance(raw, dict) and raw.get("day") == today:+ try:+ calls = max(0, int(raw.get("calls", 0)))+ except (TypeError, ValueError): # a corrupt count restarts at zero; the cap still holds+ calls = 0+ # Never lower an in-memory count for the same day: the file may be+ # read-only and lag behind what this process already spent.+ if self._day == today:+ calls = max(calls, self._calls)+ self._day, self._calls, self._loaded = day, calls, True++ def _persist_locked(self) -> None:+ path = self._state_path()+ try:+ path.parent.mkdir(parents=True, exist_ok=True)+ fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=".wiki_background_calls.")+ with os.fdopen(fd, "w", encoding="utf-8") as handle:+ json.dump({"day": self._day, "calls": self._calls}, handle)+ os.replace(tmp, path)+ except OSError:+ # The in-memory counter still enforces the cap for this process.+ log.warning(+ "wiki background guard: could not persist the call counter",+ exc_info=True,+ )++ def calls_today(self) -> int:+ with self._lock:+ self._load_locked()+ return self._calls++ # ------------------------------------------------------------------+ # gates+ # ------------------------------------------------------------------++ def _cap_deferred_locked(self, cap: int) -> BackgroundDeferred:+ detail = (+ f"{self._calls}/{cap} background wiki model calls used today; "+ "the rest waits until tomorrow"+ )+ if self._cap_logged_day != self._day:+ self._cap_logged_day = self._day+ log.warning(+ "wiki background guard: daily cap of %d background model calls "+ "reached — memory work waits until tomorrow "+ "([wiki_integration] max_background_llm_calls_per_day)",+ cap,+ )+ _record_wait(DAILY_CAP_REACHED, detail, retry_at=None)+ return BackgroundDeferred(detail)++ def check_ready(self, config: Any = None) -> None:+ """Raise :class:`BackgroundDeferred` while the wiki must not call a model.++ Cheap: no provider probe, no model call — only the cap and the backoff+ window. Callers run it before claiming work so a waiting install does+ not burn retry attempts on work it never started.+ """+ cap = daily_cap(config)+ with self._lock:+ self._load_locked()+ if self._calls >= cap:+ raise self._cap_deferred_locked(cap)+ remaining = self._retry_at_monotonic - time.monotonic()+ if remaining > 0:+ raise BackgroundDeferred(+ f"backing off for {remaining:.0f}s after "+ f"{self._setbacks} unsuccessful attempt(s): {self._last_reason}"+ )++ def ready(self, config: Any = None) -> bool:+ try:+ self.check_ready(config)+ except BackgroundDeferred: # a yes/no probe; the wait was logged when it began+ return False+ return True++ def reserve_call(self, config: Any = None, *, label: str = "wiki") -> None:+ """Count one model call, or raise :class:`BackgroundDeferred` at the cap."""+ cap = daily_cap(config)+ with self._lock:+ self._load_locked()+ if self._calls >= cap:+ raise self._cap_deferred_locked(cap)+ self._calls += 1+ self._persist_locked()+ log.debug(+ "wiki background guard: call %d/%d today (%s)", self._calls, cap, label+ )++ def hook(self, config: Any, label: str) -> Callable[[str], None]:+ """A ``before_attempt`` callback for ``complete_with_fallback``."""++ def _before_attempt(provider: str) -> None:+ self.reserve_call(config, label=f"{label}:{provider}")++ return _before_attempt++ # ------------------------------------------------------------------+ # outcomes+ # ------------------------------------------------------------------++ def _backoff_locked(self, reason: str) -> float:+ self._setbacks += 1+ delay = min(_BACKOFF_MAX_S, _BACKOFF_BASE_S * (2 ** (self._setbacks - 1)))+ self._retry_at_monotonic = time.monotonic() + delay+ self._retry_at_wall = time.time() + delay+ self._last_reason = reason+ return delay++ def note_waiting(self, detail: str) -> None:+ """The install runs on a subscription that cannot take the work now."""+ with self._lock:+ delay = self._backoff_locked(detail)+ retry_at = self._retry_at_wall+ log.info(+ "wiki background guard: waiting for the subscription (%s) — next "+ "attempt in %.0f min, never on an API key",+ detail,+ delay / 60,+ )+ _record_wait(WAITING_FOR_SUBSCRIPTION, detail, retry_at=retry_at)++ def note_failure(self, detail: str) -> None:+ """Every provider failed (key mode): retry later, not on every trigger."""+ with self._lock:+ delay = self._backoff_locked(detail)+ log.info(+ "wiki background guard: provider chain failed (%s) — next attempt "+ "in %.0f min",+ detail,+ delay / 60,+ )++ def note_progress(self) -> None:+ """A provider answered: clear the backoff and any waiting state."""+ with self._lock:+ had_setbacks = self._setbacks > 0+ self._setbacks = 0+ self._retry_at_monotonic = 0.0+ self._retry_at_wall = None+ self._last_reason = ""+ if had_setbacks:+ log.info("wiki background guard: provider answered again — backoff cleared")+ _clear_wait()++ # ------------------------------------------------------------------+ # tests+ # ------------------------------------------------------------------++ def reset_for_tests(self, *, state_path: Path | None = None) -> None:+ with self._lock:+ self._state_path_override = state_path+ self._day = ""+ self._calls = 0+ self._loaded = False+ self._cap_logged_day = ""+ self._setbacks = 0+ self._retry_at_monotonic = 0.0+ self._retry_at_wall = None+ self._last_reason = ""+++#: Process-wide singleton: every background wiki caller shares one budget.+guard = WikiBackgroundGuard()+++__all__ = [+ "DAILY_CAP_REACHED",+ "DEFAULT_DAILY_CALL_CAP",+ "WAITING_FOR_SUBSCRIPTION",+ "BackgroundDeferred",+ "WikiBackgroundGuard",+ "daily_cap",+ "guard",+]diff --git a/jarvis/memory/wiki/consolidator.py b/jarvis/memory/wiki/consolidator.pyindex 3c2b398573..8d4f599e70 100644--- a/jarvis/memory/wiki/consolidator.py+++ b/jarvis/memory/wiki/consolidator.py@@ -23,6 +23,13 @@ Every candidate leaves the batch with an explicit journal status —``consolidated`` / ``rejected`` / ``skipped`` — nothing is droppedsilently. Runs only inside the CuratorScheduler's lock+cooldown gatesas a background task (AP-9).++Nobody waits on the judge, so it bills only what background work may bill+(:mod:`jarvis.brain.background_policy`): once a subscription is connected,+subscriptions and local models only. When none of them can take the batch,+every candidate stays pending and the run reports ``judge-deferred``; the+shared runaway guard (:mod:`jarvis.memory.wiki.background_guard`) backs the+next attempt off and caps the number of judge calls per day."""from __future__ import annotations@@ -36,15 +43,13 @@ from dataclasses import dataclassfrom pathlib import Path, PurePosixPathfrom typing import TYPE_CHECKING, Any+from jarvis.brain.background_policy import BackgroundDeferredfrom jarvis.brain.provider_registry import BrainProviderRegistryfrom jarvis.brain.streaming import aggregate, is_length_truncatedfrom jarvis.core.protocols import BrainMessage, BrainRequest+from jarvis.memory.wiki.background_guard import guard as background_guardfrom jarvis.memory.wiki.constants import CURATOR_DECISIONS, INFERRED_MARKER-from jarvis.memory.wiki.curator_llm import (- _extract_json_array,- _resolve_provider_and_model,- instantiate_curator_brain,-)+from jarvis.memory.wiki.curator_llm import _extract_json_arrayfrom jarvis.memory.wiki.intent import match_wiki_intentfrom jarvis.memory.wiki.journal import JournalRow, normalise_subjectsfrom jarvis.memory.wiki.page import normalise_sources_section@@ -154,6 +159,10 @@ class _BatchOutcome:unavailable: bool = Falsetruncated: bool = Falserejected: int = 0+ # No provider background work may bill could take the batch (subscription+ # not usable, backoff window, daily cap): nothing was judged, every row+ # stays pending, and the caller must stop instead of retrying now.+ waiting: bool = Falsedef merge(self, other: _BatchOutcome) -> _BatchOutcome:return _BatchOutcome(@@ -163,6 +172,7 @@ class _BatchOutcome:unavailable=self.unavailable or other.unavailable,truncated=self.truncated or other.truncated,rejected=self.rejected + other.rejected,+ waiting=self.waiting or other.waiting,)@@ -175,8 +185,11 @@ class Consolidator:# live 2026-07-21 wedge re-judged three rows for ~16 hours. Bound it:# back off between rounds, and park the row as ``skipped`` after this# many judge-rejected rounds so the queue stays honest and cheap. A+ # single-row answer that hit the output cap and a judged row whose write+ # did not land count as rounds too: each retry is a full judge call. A# process restart grants a fresh set of rounds, so a code/prompt fix- # re-opens the row automatically.+ # re-opens the row automatically; the daily call cap in+ # ``background_guard`` bounds even a crash-restart loop._MAX_JUDGE_REJECTION_ROUNDS = 3_JUDGE_REJECTION_BACKOFF_S = 600.0@@ -211,7 +224,6 @@ class Consolidator:# Optional callback fired after a completed run (B7 wires the# self-documentation refresh here). Called best-effort.self._on_run_complete = on_run_complete- self._brain: Any = Noneself._resolved_provider: str | None = None# Per-row judge-rejection history: id -> (rounds, last monotonic ts).# In-memory by design: bounds the burn within one process life while@@ -254,6 +266,15 @@ class Consolidator:if not rows:return f"journal-rejection-backoff:{len(cooling)}"+ # Runaway guard pre-flight: inside a backoff window or past the daily+ # cap nothing is judged and nothing is marked — every candidate stays+ # pending for a later run. No provider probe, no model call.+ try:+ background_guard.check_ready(self._root_cfg)+ except BackgroundDeferred as exc:+ log.info("Consolidator: %d candidate(s) stay pending — %s", len(rows), exc)+ return "judge-deferred"+# A captured row without persisted user evidence predates the grounded# policy. It is unsafe to let Stage 2 guess, and a policy-v3 backfill can# recreate it from the transcript. Direct/internal journal rows without@@ -284,6 +305,8 @@ class Consolidator:except Exception as exc: # noqa: BLE001log.warning("Consolidator: on_run_complete hook failed: %s", exc)+ if outcome.waiting:+ return "judge-deferred"if outcome.truncated:return "judge-truncated"if outcome.unavailable:@@ -312,6 +335,10 @@ class Consolidator:# on the event loop.neighbours = await asyncio.to_thread(self._collect_neighbours, rows)decisions = await self._judge(rows, neighbours)+ if decisions == "deferred":+ # Nothing may bill right now: keep every candidate pending, and do+ # not bisect — each half would only be told to wait again.+ return _BatchOutcome(waiting=True)if decisions is None:# Provider timeout/unavailability is not a content verdict. Keep# every candidate pending for the next bounded trigger.@@ -320,29 +347,41 @@ class Consolidator:if len(rows) == 1:# A single overlong or judge-rejected result remains# observable and retryable; never convert it into terminal- # data loss. Retryable is still bounded: repeat rejections- # back off, then park the row (see _note_judge_rejection).+ # data loss. Retryable is still bounded: repeat rounds back+ # off, then park the row (see _note_judge_rejection). An+ # overlong single-row answer used to stay pending forever and+ # re-bill the whole chain on every trigger.+ await self._note_judge_rejection(rows[0])if decisions == "rejected":- await self._note_judge_rejection(rows[0])return _BatchOutcome(rejected=1)return _BatchOutcome(truncated=True)+ # Split-and-retry: every half is a new judge call and counts+ # against the daily cap like any other attempt.midpoint = len(rows) // 2left = await self._process_rows(rows[:midpoint])+ if left.waiting:+ return leftright = await self._process_rows(rows[midpoint:])return left.merge(right)- for row in rows:- self._judge_rejections.pop(row.id, None)deferred, transient = await self._execute(rows,decisions,f"journal-batch:{len(rows)}",neighbours=neighbours,)+ for row in rows:+ if row.id in transient:+ # Judged, but the write did not land (a recent human edit or+ # an incomplete writer outcome). It stays pending, and every+ # retry is another judge call — bounded like a rejection.+ await self._note_judge_rejection(row)+ else:+ self._judge_rejections.pop(row.id, None)return _BatchOutcome(- processed=len(rows) - deferred - transient,- deferred=deferred,- transient=transient,+ processed=len(rows) - len(deferred) - len(transient),+ deferred=len(deferred),+ transient=len(transient),)async def _mark(@@ -477,7 +516,9 @@ class Consolidator:Returns the decision list, ``"truncated"`` (output-cap hit),``"rejected"`` (every provider answered but failed validation),- or ``None`` (no provider reachable).+ ``"deferred"`` (nothing background work may bill can take it now —+ see :mod:`jarvis.brain.background_policy`), or ``None`` (no provider+ reachable on a key-only install)."""user_slug = resolve_user_entity_slug(getattr(@@ -499,25 +540,23 @@ class Consolidator:start_ns = time.time_ns()from jarvis.memory.wiki.provider_chain import (- background_wiki_providers,- build_wiki_provider_chain,+ build_background_wiki_chain,complete_with_fallback,)- available = set(self._registry.available())- chain = build_wiki_provider_chain(- primary=(self._curator_cfg.provider.strip() or self._root_cfg.brain.primary),- model_override=self._curator_cfg.model,- available=available,- credential_ready=(- background_wiki_providers(- available=available,- config=self._root_cfg,- )- if self._credential_filter- else available- ),- )+ try:+ background = build_background_wiki_chain(+ registry=self._registry,+ config=self._root_cfg,+ primary=(+ self._curator_cfg.provider.strip() or self._root_cfg.brain.primary+ ),+ model_override=self._curator_cfg.model,+ credential_filter=self._credential_filter,+ )+ except BackgroundDeferred as exc: # waiting is recorded on the health strip below+ background_guard.note_waiting(str(exc))+ return "deferred"rejection_reasons: list[str] = []# Reasons where the model produced WELL-FORMED JSON but the judged# decision merely violated a curation rule (companion page missing,@@ -549,16 +588,29 @@ class Consolidator:return reasonreturn None- result = await complete_with_fallback(- registry=self._registry,- chain=chain,- request=request,- timeout_s=float(self._curator_cfg.timeout_s),- label="Consolidator",- aggregate=aggregate,- validate=_validate_response,- content_verdict=lambda reason: reason in content_verdict_reasons,- )+ try:+ result = await complete_with_fallback(+ registry=self._registry,+ chain=background.chain,+ request=request,+ timeout_s=float(self._curator_cfg.timeout_s),+ label="Consolidator",+ aggregate=aggregate,+ validate=_validate_response,+ content_verdict=lambda reason: reason in content_verdict_reasons,+ provider_options=background.provider_options,+ before_attempt=background_guard.hook(self._root_cfg, "consolidator"),+ record_chain_failure=not background.subscription_mode,+ )+ except BackgroundDeferred as exc:+ # The daily cap was reached between two attempts; the guard has+ # already logged it and recorded the waiting state.+ log.info("Consolidator: judge deferred — %s", exc)+ return "deferred"+ if result is not None or rejection_reasons:+ # A provider answered (even if its answer was unusable): the+ # install is not waiting on anything.+ background_guard.note_progress()if result is None:if any(reason.startswith("truncated") for reason in rejection_reasons):log.warning(@@ -575,6 +627,12 @@ class Consolidator:# the queue keeps draining.telemetry.inc("wiki_writes_blocked_rejected")return "rejected"+ if background.subscription_mode:+ # Logged out, out of credit, rate limited — whatever it is, the+ # subscription did not take the batch. Wait; never a key.+ background_guard.note_waiting("the subscription did not answer")+ return "deferred"+ background_guard.note_failure("every wiki provider failed")return Noneagg, self._resolved_provider = result@@ -615,8 +673,8 @@ class Consolidator:label: str,*,neighbours: dict[str, str],- ) -> tuple[int, int]:- """Apply one judged batch and return ``(deferred, transient)`` counts."""+ ) -> tuple[set[int], set[int]]:+ """Apply one judged batch and return the ``(deferred, transient)`` row ids."""validation_error = self._validate_decisions(decisions,rows,@@ -631,7 +689,7 @@ class Consolidator:"leaving every candidate pending",validation_error,)- return 0, len(rows)+ return set(), {row.id for row in rows}by_id = {row.id: row for row in rows}row_order = {row.id: index for index, row in enumerate(rows)}@@ -911,7 +969,7 @@ class Consolidator:cid,)- return len(deferred_ids), len(transient_ids)+ return deferred_ids, transient_ids# ------------------------------------------------------------------# helpers@@ -1581,33 +1639,5 @@ class Consolidator:except ValueError:return abs_path.as_posix()- def _ensure_brain(self) -> Any:- if self._brain is not None:- return self._brain- provider, model = _resolve_provider_and_model(self._curator_cfg, self._root_cfg)- try:- # Thinking disabled for Gemini non-pro: the judge must spend its- # token budget on page bodies, not on internal reasoning (see- # instantiate_curator_brain).- self._brain = instantiate_curator_brain(- self._registry,- provider,- model,- cli_timeout_s=float(self._curator_cfg.timeout_s),- )- self._resolved_provider = provider- except Exception as exc: # noqa: BLE001- log.warning(- "Consolidator: provider %r unavailable (%s) — batch stays pending",- provider, exc,- )- self._brain = None- return self._brain-- def reset_brain(self) -> None:- """Drop the cached brain (provider switch via the Wiki settings card)."""- self._brain = None- self._resolved_provider = None-__all__ = ["Consolidator"]diff --git a/jarvis/memory/wiki/curator_llm.py b/jarvis/memory/wiki/curator_llm.pyindex 88f948b518..3e931e16a9 100644--- a/jarvis/memory/wiki/curator_llm.py+++ b/jarvis/memory/wiki/curator_llm.py@@ -25,7 +25,6 @@ config, timeout-via-wait_for, error-tolerant shape).from __future__ import annotationsimport asyncio-import functoolsimport jsonimport loggingimport time@@ -454,7 +453,6 @@ class WikiCuratorLLM:self._brain: Brain | None = Noneself._resolved_provider: str | None = Noneself._resolved_model: str | None = None- self._lock = asyncio.Lock()@propertydef provider_name(self) -> str | None:@@ -532,28 +530,31 @@ class WikiCuratorLLM:)start_ns = time.time_ns()+ from jarvis.brain.background_policy import BackgroundDeferred+ from jarvis.memory.wiki.background_guard import guardfrom jarvis.memory.wiki.provider_chain import (- background_wiki_providers,- build_wiki_provider_chain,+ build_background_wiki_chain,complete_with_fallback,)# Key-aware fallback (AP-22/23): cross to a reachable family instead of# dying on one dead / throttled provider (live 2026-06-30 silent brick).- available = set(self._registry.available())- chain = build_wiki_provider_chain(- primary=(self._cfg.provider.strip() or self._config.brain.primary),- model_override=self._cfg.model,- available=available,- credential_ready=(- background_wiki_providers(- available=available,- config=self._config,- )- if self._credential_filter- else available- ),- )+ # The curator runs after the turn with nobody waiting on it, so it+ # bills only what background work may bill: once a subscription is+ # connected, subscriptions and local models — never a key.+ try:+ background = build_background_wiki_chain(+ registry=self._registry,+ config=self._config,+ primary=(self._cfg.provider.strip() or self._config.brain.primary),+ model_override=self._cfg.model,+ credential_filter=self._credential_filter,+ )+ except BackgroundDeferred as exc:+ logger.warning("WikiCuratorLLM: nothing written now — %s", exc)+ guard.note_waiting(str(exc))+ return []+ chain = background.chainrejection_reasons: list[str] = []def _validate_response(agg: Any) -> str | None:@@ -589,7 +590,11 @@ class WikiCuratorLLM:label="WikiCuratorLLM",aggregate=aggregate,validate=_validate_response,+ provider_options=background.provider_options,+ record_chain_failure=not background.subscription_mode,)+ if result is None and background.subscription_mode and not rejection_reasons:+ guard.note_waiting("the subscription did not answer")if result is None:if any(reason.startswith("truncated") for reason in rejection_reasons):logger.warning(@@ -631,55 +636,6 @@ class WikiCuratorLLM:# Internals# ------------------------------------------------------------------- async def _ensure_brain(self) -> Brain | None:- """Instantiate the configured Brain once, cache the result.-- Returns ``None`` when the provider can't be created — the caller- treats that as "skip ingest, log warning".- """-- async with self._lock:- if self._brain is not None:- return self._brain-- try:- provider, model = _resolve_provider_and_model(self._cfg, self._config)- except Exception as exc: # noqa: BLE001- logger.warning(- "WikiCuratorLLM: provider resolution failed: %s", exc,- )- return None-- self._resolved_provider = provider- self._resolved_model = model-- try:- # Thinking disabled for the curator tier (Gemini non-pro):- # background JSON work must not burn the token budget on- # internal reasoning (see instantiate_curator_brain).- brain = await asyncio.to_thread(- functools.partial(- instantiate_curator_brain,- self._registry,- provider,- model,- cli_timeout_s=float(self._cfg.timeout_s),- ),- )- except Exception as exc: # noqa: BLE001- logger.warning(- "WikiCuratorLLM: cannot instantiate provider %r (model=%r): %s",- provider, model, exc,- )- return None-- self._brain = brain- logger.info(- "WikiCuratorLLM active (provider=%s model=%s timeout=%.1fs)",- provider, model or "<provider-default>", self._cfg.timeout_s,- )- return brain-async def _load_schema(self) -> str | None:"""Read ``schema.md`` from disk on a worker thread."""diff --git a/jarvis/memory/wiki/extractor.py b/jarvis/memory/wiki/extractor.pyindex e5a6c857a2..9ee699b8f3 100644--- a/jarvis/memory/wiki/extractor.py+++ b/jarvis/memory/wiki/extractor.py@@ -1,15 +1,25 @@"""Stage-1 conversation fact extractor (Wave 2, ADD-only).-One cheap LLM call per eligible conversation turn extracts 0..N atomic-candidate facts and appends them to the :class:`CandidateJournal`. This-stage NEVER touches the vault — a failing or over-eager extractor cannot-corrupt existing pages; the expensive judgment (ADD/UPDATE/NOOP/INVALIDATE-against real page bodies) happens later in the batched Stage-2 consolidator.--Provider/model resolve through the SAME hook as the curator-(``curator_llm._resolve_provider_and_model`` over ``[memory.wiki.curator]``),-so the Wiki settings card drives both stages — cheap router-tier model by-default, explicit override wins.+One cheap LLM call per reviewed turn extracts 0..N atomic candidate facts+and appends them to the :class:`CandidateJournal`. This stage NEVER touches+the vault — a failing or over-eager extractor cannot corrupt existing pages;+the expensive judgment (ADD/UPDATE/NOOP/INVALIDATE against real page bodies)+happens later in the batched Stage-2 consolidator.++Since 2026-09-30 a turn is reviewed only when the user explicitly asked for+it to be kept (the voice bridge's acknowledgement path) or when the user+starts a backfill. The automatic review of every turn, the end-of-call+sweep and the periodic auto-backfill were removed: they spent paid API keys+around the clock for little value.++Provider/model resolve through the SAME ``[memory.wiki.curator]`` pair as+the curator, so the Wiki settings card drives both stages — cheap+router-tier model by default, explicit override wins. Nobody waits on the+answer, so the call bills only what background work may bill+(:mod:`jarvis.brain.background_policy`) and counts against the wiki's daily+call cap (:mod:`jarvis.memory.wiki.background_guard`). When it has to wait,+:class:`~jarvis.brain.background_policy.BackgroundDeferred` reaches the+caller instead of a key being used.Stage-1 selection contract (spec §4.2, D1 "completeness with cleanliness"):recall-biased — when unsure whether something matters long-term, surface a@@ -30,16 +40,14 @@ from collections.abc import Sequencefrom dataclasses import dataclassfrom typing import TYPE_CHECKING, Any, Literal+from jarvis.brain.background_policy import BackgroundDeferredfrom jarvis.brain.provider_registry import BrainProviderRegistryfrom jarvis.brain.streaming import aggregate, is_length_truncatedfrom jarvis.core.protocols import BrainMessage, BrainRequestfrom jarvis.core.redact import safe_preview+from jarvis.memory.wiki.background_guard import guard as background_guardfrom jarvis.memory.wiki.constants import DEFAULT_SALIENCE-from jarvis.memory.wiki.curator_llm import (- _extract_json_array,- _resolve_provider_and_model,- instantiate_curator_brain,-)+from jarvis.memory.wiki.curator_llm import _extract_json_arrayfrom jarvis.memory.wiki.grounding import classify_user_attitude_evidencefrom jarvis.memory.wiki.journal import CandidateFact, normalise_subjectsfrom jarvis.memory.wiki.residence import detect_residence_slug@@ -49,6 +57,7 @@ from jarvis.memory.wiki.telemetry import telemetryif TYPE_CHECKING:from jarvis.core.config import JarvisConfigfrom jarvis.memory.wiki.journal import CandidateJournal+ from jarvis.memory.wiki.provider_chain import WikiBackgroundChainlog = logging.getLogger(__name__)@@ -289,9 +298,7 @@ class ConversationFactExtractor:self._journal = journalself._registry = registry if registry is not None else BrainProviderRegistry()self._credential_filter = registry is None- self._brain: Any = Noneself._resolved_provider: str | None = None- self._resolved_model: str | None = None# Wave-2 journal pressure: when attached, an append that pushes the# backlog past the threshold fires a background JOURNAL trigger so# the Stage-2 consolidator drains a batch (cooldown/lock gated there).@@ -325,13 +332,22 @@ class ConversationFactExtractor:) -> int:"""One LLM call -> 0..N facts -> journal. Returns the appended count.- Never raises: every failure (brain unavailable, timeout, malformed- JSON, truncation) degrades to 0 with a logged warning — the- conversation must never notice the memory pipeline.+ Every provider failure (brain unavailable, timeout, malformed JSON,+ truncation) degrades to 0 with a logged warning — the conversation+ must never notice the memory pipeline. The one exception is+ :class:`BackgroundDeferred`: nothing background work may bill can take+ the call right now, so the caller keeps the turn and retries later.+ It is raised BEFORE the review is claimed whenever that is known up+ front, so waiting never uses up a review attempt."""text = (user_text or "").strip()focus_turn_id = (turn_id or turn_hash).strip()key = review_key or f"turn:v2:{turn_hash}"+ background = (+ self._background_chain()+ if self._cfg.enabled and len(text) >= int(self._cfg.min_user_chars)+ else None+ )if not await self._claim_review(review_key=key,source_label=source_label,@@ -347,7 +363,7 @@ class ConversationFactExtractor:key, status="filtered", error_code="extractor-disabled")return 0- if len(text) < int(self._cfg.min_user_chars):+ if len(text) < int(self._cfg.min_user_chars) or background is None:await self._finish_review(key, status="filtered", error_code="below-min-chars")return 0@@ -360,6 +376,7 @@ class ConversationFactExtractor:try:outcome = await self._extract(prompt,+ background=background,system_prompt=self._with_user_slug(_SYSTEM_PROMPT),allowed_evidence={focus_turn_id},fallback_evidence="",@@ -379,6 +396,12 @@ class ConversationFactExtractor:except asyncio.CancelledError:await self._finish_review(key, status="failed", error_code="cancelled")raise+ except BackgroundDeferred:+ # The daily cap was reached or the subscription stopped answering+ # mid-chain: the review stays retryable and the caller keeps the+ # turn for a later attempt.+ await self._finish_review(key, status="failed", error_code="deferred")+ raiseexcept Exception: # noqa: BLE001 - the conversation must never noticelog.exception("ConversationFactExtractor: unexpected extraction failure")await self._finish_review(key, status="failed", error_code="unexpected")@@ -399,7 +422,13 @@ class ConversationFactExtractor:source_label: str,review_key: str | None = None,) -> int:- """Sweep every Realtime turn in stable, independently retryable chunks."""+ """Sweep every Realtime turn in stable, independently retryable chunks.++ Used only by the user-started backfill. When the wiki has to wait+ (subscription not usable, backoff, daily cap) the remaining chunks+ are left unclaimed — or, if the wait started mid-call, marked+ ``failed`` with ``deferred`` — so a later backfill picks them up.+ """usable = tuple(t for t in turns if t.turn_id and t.user_text.strip())base_key = review_key or f"session:v3:{session_id}"chunks = self._session_chunks(usable)@@ -429,6 +458,19 @@ class ConversationFactExtractor:seen_facts: set[str] = set()for index, (key, chunk) in enumerate(zip(keys, chunks, strict=True)):transcript = self._build_session_prompt(chunk)+ background: WikiBackgroundChain | None = None+ if self._cfg.enabled:+ try:+ background = self._background_chain()+ except BackgroundDeferred as exc:+ log.info(+ "ConversationFactExtractor: session %s sweep paused at "+ "chunk %d — %s",+ session_id,+ index,+ exc,+ )+ breakif not await self._claim_review(review_key=key,source_label=f"{source_label}:chunk:{index}",@@ -438,7 +480,7 @@ class ConversationFactExtractor:turn_id="",):continue- if not self._cfg.enabled:+ if background is None:await self._finish_review(key,status="filtered",@@ -448,6 +490,7 @@ class ConversationFactExtractor:try:outcome = await self._extract(transcript,+ background=background,system_prompt=self._with_user_slug(_SESSION_SYSTEM_PROMPT),allowed_evidence={t.turn_id for t in chunk.focus},fallback_evidence="",@@ -462,6 +505,15 @@ class ConversationFactExtractor:except asyncio.CancelledError:await self._finish_review(key, status="failed", error_code="cancelled")raise+ except BackgroundDeferred as exc:+ await self._finish_review(key, status="failed", error_code="deferred")+ log.info(+ "ConversationFactExtractor: session %s sweep paused at chunk %d — %s",+ session_id,+ index,+ exc,+ )+ breakexcept Exception: # noqa: BLE001log.exception("ConversationFactExtractor: session chunk failed")await self._finish_review(key, status="failed", error_code="unexpected")@@ -833,10 +885,35 @@ class ConversationFactExtractor:await self._maybe_trigger_consolidation()return appended+ def _background_chain(self) -> WikiBackgroundChain:+ """The provider chain this extraction may bill, or raise to make it wait.++ Checks the runaway guard (backoff window, daily cap) and the+ background billing policy BEFORE any review is claimed, so an install+ waiting on its subscription never spends a retry attempt.+ """+ from jarvis.memory.wiki.provider_chain import build_background_wiki_chain++ background_guard.check_ready(self._root_cfg)+ try:+ return build_background_wiki_chain(+ registry=self._registry,+ config=self._root_cfg,+ primary=(+ self._curator_cfg.provider.strip() or self._root_cfg.brain.primary+ ),+ model_override=self._curator_cfg.model,+ credential_filter=self._credential_filter,+ )+ except BackgroundDeferred as exc:+ background_guard.note_waiting(str(exc))+ raise+async def _extract(self,user_prompt: str,*,+ background: WikiBackgroundChain,system_prompt: str,allowed_evidence: set[str],fallback_evidence: str,@@ -854,29 +931,12 @@ class ConversationFactExtractor:)start_ns = time.time_ns()- from jarvis.memory.wiki.provider_chain import (- background_wiki_providers,- build_wiki_provider_chain,- complete_with_fallback,- )+ from jarvis.memory.wiki.provider_chain import complete_with_fallback- # Key-aware fallback (AP-22/23): try the configured provider, then cross- # to whatever family is reachable, instead of silently dropping the turn+ # Key-aware fallback (AP-22/23): the background chain tries the+ # configured provider, then crosses to whatever family is reachable+ # AND may bill background work, instead of silently dropping the turn# when one provider is throttled / keyless (live 2026-06-30).- available = set(self._registry.available())- chain = build_wiki_provider_chain(- primary=(self._curator_cfg.provider.strip() or self._root_cfg.brain.primary),- model_override=self._curator_cfg.model,- available=available,- credential_ready=(- background_wiki_providers(- available=available,- config=self._root_cfg,- )- if self._credential_filter- else available- ),- )rejection_reasons: list[str] = []def _validate_response(agg: Any) -> str | None:@@ -920,10 +980,15 @@ class ConversationFactExtractor:result = await complete_with_fallback(registry=self._registry,- chain=chain,+ chain=background.chain,request=request,timeout_s=float(self._cfg.timeout_s),label="ConversationFactExtractor",+ provider_options=background.provider_options,+ # Every attempt counts against the daily runaway cap; reaching it+ # raises BackgroundDeferred to the caller (nothing is spent).+ before_attempt=background_guard.hook(self._root_cfg, "extractor"),+ record_chain_failure=not background.subscription_mode,aggregate=aggregate,validate=_validate_response,# Both reasons are CONTENT verdicts ("this turn holds nothing@@ -944,6 +1009,16 @@ class ConversationFactExtractor:reason == "empty-needs-second-opinion"),)+ if result is not None or rejection_reasons:+ # A provider answered: nothing is waiting on a subscription.+ background_guard.note_progress()+ elif background.subscription_mode:+ # Logged out, out of credit, rate limited: the subscription did+ # not take the turn. Wait and retry later; never a key.+ background_guard.note_waiting("the subscription did not answer")+ raise BackgroundDeferred("the subscription did not answer")+ else:+ background_guard.note_failure("every wiki provider failed")if result is None:duration_ms = (time.time_ns() - start_ns) // 1_000_000error_code = "provider-chain-failed"@@ -1295,31 +1370,6 @@ class ConversationFactExtractor:return Falsereturn True- def _ensure_brain(self) -> Any:- """Lazily instantiate the cheap brain; ``None`` when unavailable."""- if self._brain is not None:- return self._brain- provider, model = _resolve_provider_and_model(self._curator_cfg, self._root_cfg)- try:- # Thinking disabled for Gemini non-pro: extraction is small,- # deterministic JSON output (see instantiate_curator_brain).- self._brain = instantiate_curator_brain(- self._registry,- provider,- model,- cli_timeout_s=float(self._cfg.timeout_s),- )- self._resolved_provider = provider- self._resolved_model = model- except Exception as exc: # noqa: BLE001- log.warning(- "ConversationFactExtractor: provider %r unavailable (%s) — "- "extraction disabled until next attempt",- provider, exc,- )- self._brain = None- return self._brain-def seen_turn(self, turn_hash: str) -> bool:"""Durable dedupe: True when this turn hash is already journaled."""try:@@ -1327,15 +1377,5 @@ class ConversationFactExtractor:except Exception: # noqa: BLE001return False- def reset_brain(self) -> None:- """Drop the cached brain so the next turn re-resolves provider/model.-- Mirrors the live-apply contract of the Wiki settings route, which- clears the curator's cached brain on a provider switch.- """- self._brain = None- self._resolved_provider = None- self._resolved_model = None-__all__ = ["ConversationContextTurn", "ConversationFactExtractor"]diff --git a/jarvis/memory/wiki/health.py b/jarvis/memory/wiki/health.pyindex 78d44d4384..deb5be9a40 100644--- a/jarvis/memory/wiki/health.py+++ b/jarvis/memory/wiki/health.py@@ -24,6 +24,7 @@ class WikiHealth:self._last_write: dict[str, Any] | None = Noneself._last_index: dict[str, Any] | None = Noneself._last_chain_failure: dict[str, Any] | None = None+ self._background_wait: dict[str, Any] | None = Noneself._journal_backlog: int = 0def record_bootstrap(self, ok: bool, error: str | None = None) -> None:@@ -64,6 +65,37 @@ class WikiHealth:with self._lock:self._last_chain_failure = None+ def record_background_wait(+ self, state: str, *, detail: str, retry_at: float | None = None,+ ) -> None:+ """Background memory work is waiting on purpose, not broken.++ ``state`` is ``waiting_for_subscription`` (the install runs on a+ subscription that cannot take the work right now, and it never slides+ onto an API key) or ``daily_cap_reached`` (the runaway guard stopped+ background model calls until tomorrow). Deliberately separate from+ ``last_chain_failure``: waiting is the designed behaviour, so it must+ not paint the red provider-failure banner.+ """+ from jarvis.core.redact import safe_preview++ with self._lock:+ since = (+ self._background_wait["since"]+ if self._background_wait and self._background_wait.get("state") == state+ else time.time()+ )+ self._background_wait = {+ "state": state,+ "detail": safe_preview(detail, max_chars=300),+ "since": since,+ "retry_at": retry_at,+ }++ def clear_background_wait(self) -> None:+ with self._lock:+ self._background_wait = None+def record_index(self,ok: bool,@@ -103,6 +135,9 @@ class WikiHealth:dict(self._last_chain_failure)if self._last_chain_failure else None),+ "background_wait": (+ dict(self._background_wait) if self._background_wait else None+ ),"journal_backlog": self._journal_backlog,}diff --git a/jarvis/memory/wiki/journal.py b/jarvis/memory/wiki/journal.pyindex 38af65fb0a..8dd49a98e0 100644--- a/jarvis/memory/wiki/journal.py+++ b/jarvis/memory/wiki/journal.py@@ -59,6 +59,10 @@ _CAPTURE_STATUSES = frozenset({"started", "filtered", "empty", "candidates", "fa_CAPTURE_TERMINAL_STATUSES = frozenset({"filtered", "empty", "candidates"})_CAPTURE_FINISH_STATUSES = frozenset({"filtered", "empty", "candidates", "failed"})_CAPTURE_STALE_AFTER_MS = 5 * 60 * 1000+# A review that keeps failing is retried at most this many times in total.+# Every retry is a paid model call; before the bound the periodic+# auto-backfill re-claimed failed reviews forever.+_MAX_CAPTURE_ATTEMPTS = 5_MAX_FACT_CHARS = 2_000_MAX_EVIDENCE_CHARS = 1_200_MAX_SUBJECTS = 12@@ -449,8 +453,9 @@ class CandidateJournal:"""Atomically claim one extraction review.A new key is claimed immediately. ``failed`` rows and ``started`` rows- older than five minutes are retried with an incremented attempt count.- Fresh in-flight or terminal rows are left untouched and return ``False``.+ older than five minutes are retried with an incremented attempt count,+ up to :data:`_MAX_CAPTURE_ATTEMPTS` attempts in total. Fresh in-flight,+ terminal, or exhausted rows are left untouched and return ``False``."""key = _safe_identifier(review_key, allow_empty=False)now_ms = self._now_ms()@@ -482,9 +487,10 @@ class CandidateJournal:updated_ms = excluded.updated_ms,started_ms = excluded.started_ms,finished_ms = NULL- WHERE wiki_extraction_audit.status = 'failed'- OR (wiki_extraction_audit.status = 'started'- AND wiki_extraction_audit.updated_ms <= ?)+ WHERE wiki_extraction_audit.attempts < ?+ AND (wiki_extraction_audit.status = 'failed'+ OR (wiki_extraction_audit.status = 'started'+ AND wiki_extraction_audit.updated_ms <= ?))""",(key,@@ -496,6 +502,7 @@ class CandidateJournal:now_ms,now_ms,now_ms,+ _MAX_CAPTURE_ATTEMPTS,stale_before_ms,),)diff --git a/jarvis/memory/wiki/provider_chain.py b/jarvis/memory/wiki/provider_chain.pyindex 9abe364464..cbf01c976e 100644--- a/jarvis/memory/wiki/provider_chain.py+++ b/jarvis/memory/wiki/provider_chain.py@@ -18,18 +18,33 @@ chain and a working provider existed. The wiki looked dead while the user hadcredit. This module gives the wiki the SAME resilience, plus an HONEST signalwhen the whole chain is exhausted (AP-22 single-provider brick / AP-23maintainer-config coupling).++Which providers may join a chain is not only a question of credentials. Wiki+calls run with nobody waiting on them, so :func:`build_background_wiki_chain`+admits only what background work may bill+(:mod:`jarvis.brain.background_policy`): once a subscription is connected,+subscriptions and keyless local models — and an empty set means the caller+waits, never that it falls back to a key."""from __future__ import annotationsimport asyncio+import inspectimport loggingimport reimport threadingimport timefrom collections.abc import Callable, Mapping+from dataclasses import dataclassfrom typing import Any+from jarvis.brain.background_policy import (+ BackgroundDeferred,+ BackgroundProviders,+ background_providers,+ subscription_capable,+)from jarvis.core.redact import safe_previewfrom jarvis.costs.ledger import usage_contextfrom jarvis.memory.wiki.telemetry import telemetry@@ -218,30 +233,129 @@ def credential_ready_wiki_providers(return ready+def background_wiki_decision(+ *,+ available: set[str] | frozenset[str],+ config: Any,+ credential_filter: bool = True,+) -> BackgroundProviders:+ """The background billing verdict over the wiki's credential-ready providers.++ Delegates to :func:`jarvis.brain.background_policy.background_providers`,+ the one rule for work nobody is waiting on: once a subscription is+ connected (sticky for 30 days) only subscriptions and keyless local models+ may bill, and an empty allowed set means WAIT, never "use a key". An+ install that never connected a subscription keeps its keys, so a+ single-key download still has a working wiki (AP-21/AP-22).++ ``credential_filter=False`` skips the credential probe (tests inject a+ scripted registry); the billing rule itself always applies.+ """+ ready = (+ credential_ready_wiki_providers(available=available, config=config)+ if credential_filter+ else set(available)+ )+ return background_providers(sorted(ready))++def background_wiki_providers(*,available: set[str] | frozenset[str],config: Any,- is_subscription: Callable[[str], bool] | None = None,) -> set[str]:- """Providers wiki background work may bill: subscriptions before any key.-- Memory curation is background work the user never waits on, so while any- subscription login is connected it runs ONLY on subscriptions plus keyless- local providers and never touches a per-token key (live 2026-09-29: an- OpenAI key added for voice paid ~$0.30 of wiki calls after a two-minute- chat). With no subscription connected the full credential-ready set stays- in play, so a single-key install keeps a working wiki (AP-21/AP-22).+ """Providers wiki background work may bill right now (see the decision above).++ Before 2026-09-30 this admitted every stored key whenever no login probe+ answered ``True`` at that moment — so an expired OAuth token, a crashed+ CLI probe or a spent plan silently moved memory curation onto paid keys+ (~300 wiki calls on keys in 30 days). It now returns exactly the policy's+ allowed set; an empty set in subscription mode means the caller waits."""- from jarvis.core.config import PROVIDER_SECRET_CANDIDATES+ return set(background_wiki_decision(available=available, config=config).allowed)- ready = credential_ready_wiki_providers(available=available, config=config)- probe = is_subscription or (lambda name: subscription_login_ready(name) is True)- subscriptions = {name for name in ready if probe(name)}- if not subscriptions:- return ready- keyless = {name for name in ready if name not in PROVIDER_SECRET_CANDIDATES}- return subscriptions | keyless++def subscription_provider_options(+ decision: BackgroundProviders,+ registry: Any,+) -> dict[str, dict[str, Any]]:+ """Constructor options that pin allowed subscriptions to their login.++ A dual-billed provider (a subscription login plus an API-key slot, e.g.+ the ChatGPT-subscription card) decides per call which one it spends; a+ login that drops between the policy check and the call would otherwise+ fall through to the key. In subscription mode every allowed provider whose+ constructor accepts ``prefer_subscription`` gets it, so it fails instead+ of billing its key. Capability probe on the constructor, never a provider+ name (AP-21).+ """+ if not decision.subscription_mode:+ return {}+ options: dict[str, dict[str, Any]] = {}+ for name in decision.allowed:+ if not subscription_capable(name):+ continue+ get_class = getattr(registry, "get_class", None)+ if not callable(get_class):+ continue+ try:+ parameters = inspect.signature(get_class(name)).parameters+ except Exception: # noqa: BLE001 - an unknown constructor gets no pin+ log.debug(+ "wiki background chain: cannot inspect %s for prefer_subscription",+ name,+ exc_info=True,+ )+ continue+ if "prefer_subscription" in parameters:+ options[name] = {"prefer_subscription": True}+ return options+++@dataclass(frozen=True, slots=True)+class WikiBackgroundChain:+ """An ordered provider chain that background wiki work may bill."""++ chain: list[tuple[str, str | None]]+ subscription_mode: bool+ provider_options: dict[str, dict[str, Any]]+++def build_background_wiki_chain(+ *,+ registry: Any,+ config: Any,+ primary: str,+ model_override: str,+ credential_filter: bool = True,+) -> WikiBackgroundChain:+ """Build the chain for one background wiki call, or raise to make it wait.++ Raises :class:`BackgroundDeferred` when the install is in subscription+ mode and no subscription (or keyless local model) can take the work right+ now: the caller keeps its work pending and retries later. In key mode an+ empty chain is returned as before, so the caller's honest chain-failure+ path still reports "no provider configured".+ """+ available = set(registry.available())+ decision = background_wiki_decision(+ available=available,+ config=config,+ credential_filter=credential_filter,+ )+ chain = build_wiki_provider_chain(+ primary=primary,+ model_override=model_override,+ available=available,+ credential_ready=set(decision.allowed),+ )+ if decision.subscription_mode and not chain:+ raise BackgroundDeferred(decision.reason)+ return WikiBackgroundChain(+ chain=chain,+ subscription_mode=decision.subscription_mode,+ provider_options=subscription_provider_options(decision, registry),+ )def build_wiki_provider_chain(@@ -292,6 +406,8 @@ async def complete_with_fallback(provider_options: Mapping[str, Mapping[str, Any]] | None = None,record_health: bool = True,failure_scope: str = "wiki",+ before_attempt: Callable[[str], None] | None = None,+ record_chain_failure: bool = True,) -> tuple[Any, str] | None:"""Try each ``(provider, model)`` until one returns an aggregated response.@@ -327,6 +443,19 @@ async def complete_with_fallback(nor has authority to clear a real capture failure after a later success.``failure_scope`` likewise isolates the short provider cooldown: an image-specific 400 must not demote that same provider for ordinary text curation.++ ``before_attempt(provider)`` runs before each provider is instantiated.+ Background callers pass the runaway guard's call counter here, so every+ attempt — second opinions and split-and-retry halves included — counts+ against the daily cap. It may raise+ :class:`~jarvis.brain.background_policy.BackgroundDeferred`; that+ propagates unchanged (nothing was spent, the work waits) instead of being+ treated as a provider failure.++ ``record_chain_failure=False`` keeps a total chain failure off the red+ health banner while successes still clear it: a subscription-mode caller+ records a "waiting for your subscription" state instead, because waiting+ is the designed behaviour there, not a broken wiki."""from jarvis.memory.wiki.curator_llm import instantiate_curator_brain@@ -352,6 +481,10 @@ async def complete_with_fallback()for index, (provider, model) in enumerate(ordered):+ if before_attempt is not None:+ # Outside every provider try-block on purpose: a runaway-guard+ # deferral is not a provider failure and must reach the caller.+ before_attempt(provider)try:brain = instantiate_curator_brain(registry,@@ -625,7 +758,7 @@ async def complete_with_fallback()except Exception: # noqa: BLE001 — telemetry must never break the pipelinelog.debug("%s: telemetry inc failed", label, exc_info=True)- if record_health:+ if record_health and record_chain_failure:try:from jarvis.memory.wiki.health import health@@ -643,10 +776,14 @@ async def complete_with_fallback(__all__ = [+ "WikiBackgroundChain",+ "background_wiki_decision","background_wiki_providers",+ "build_background_wiki_chain","build_wiki_provider_chain","complete_with_fallback","credential_ready_wiki_providers","reset_provider_failure_memory","subscription_login_ready",+ "subscription_provider_options",]diff --git a/jarvis/memory/wiki/recurate.py b/jarvis/memory/wiki/recurate.pyindex aebbbb5654..184201e5b6 100644--- a/jarvis/memory/wiki/recurate.py+++ b/jarvis/memory/wiki/recurate.py@@ -178,31 +178,33 @@ async def recurate_profile(stream=True,)+ from jarvis.brain.background_policy import BackgroundDeferredfrom jarvis.memory.wiki.provider_chain import (- background_wiki_providers,- build_wiki_provider_chain,+ build_background_wiki_chain,complete_with_fallback,)# An injected registry (tests) skips the credential filter — the same# convention as WikiCuratorLLM/Consolidator: production uses a fresh- # registry and only keeps key-ready provider families in the chain.+ # registry and only keeps key-ready provider families in the chain. The+ # background billing policy applies either way: once a subscription is+ # connected this runs on subscriptions and local models only.credential_filter = registry is Noneif registry is None:from jarvis.brain.provider_registry import BrainProviderRegistryregistry = BrainProviderRegistry()- available = set(registry.available())- chain = build_wiki_provider_chain(- primary=(wiki_cfg.curator.provider.strip() or config.brain.primary),- model_override=wiki_cfg.curator.model,- available=available,- credential_ready=(- background_wiki_providers(available=available, config=config)- if credential_filter- else available- ),- )+ try:+ background = build_background_wiki_chain(+ registry=registry,+ config=config,+ primary=(wiki_cfg.curator.provider.strip() or config.brain.primary),+ model_override=wiki_cfg.curator.model,+ credential_filter=credential_filter,+ )+ except BackgroundDeferred as exc: # reported to the caller through report.error+ report.error = f"waiting for the subscription: {exc}"+ return reportdef _validate_response(agg: Any) -> str | None:if is_length_truncated(agg.finish_reason, agg.text):@@ -217,12 +219,14 @@ async def recurate_profile(result = await complete_with_fallback(registry=registry,- chain=chain,+ chain=background.chain,request=request,timeout_s=float(wiki_cfg.curator.timeout_s),label="RecurateProfile",aggregate=aggregate,validate=_validate_response,+ provider_options=background.provider_options,+ record_chain_failure=not background.subscription_mode,)if result is None:report.error = "no provider produced a valid re-curation proposal"diff --git a/jarvis/memory/wiki/scheduler.py b/jarvis/memory/wiki/scheduler.pyindex 1a1d794b50..bd35959627 100644--- a/jarvis/memory/wiki/scheduler.py+++ b/jarvis/memory/wiki/scheduler.py@@ -50,7 +50,28 @@ if TYPE_CHECKING:log = logging.getLogger(__name__)-_MAX_DEFERRED_DRAIN_PASSES = 20+#: Upper bound on follow-up passes of one journal drain (coalesced requests+#: plus same-target serialisation). Each pass is a judge call; the drain used+#: to repeat for as long as new requests kept marking it dirty.+_MAX_DRAIN_PASSES = 20++#: Consolidator labels after which another pass may run at once: the pass+#: moved candidates, or found the journal empty (no model call was made, and+#: a request that arrived meanwhile must still be served). Anything else —+#: judge deferred/unavailable/truncated/rejected, rows in backoff — ends the+#: drain: repeating it now would only re-bill the same failure.+_PROGRESS_LABEL_PREFIXES = (+ "journal-batch:",+ "journal-deferred:",+ "journal-evidence-rejected:",+ "journal-empty",+)+++def _made_progress(result: SchedulerResult) -> bool:+ return result.triggered and result.curator_output_label.startswith(+ _PROGRESS_LABEL_PREFIXES+ )class TriggerSource(StrEnum):@@ -76,11 +97,12 @@ def fire_journal_trigger(``scheduler.trigger(TriggerSource.JOURNAL)`` call and its done-callbacklogging cannot drift apart between them:- * the per-turn count-threshold trigger+ * the extractor's count-threshold trigger after an explicitly saved turn(``extractor.ConversationFactExtractor._maybe_trigger_consolidation``),* the boot-time backlog drain (``integration.kick_journal_backlog``), and* the below-threshold age-based flush- (``integration._journal_age_flush_loop``).+ (``integration._journal_age_flush_loop``), which also waits out the+ runaway guard's backoff (``background_guard``).Lives here (a runtime-stdlib-only leaf, next to ``TriggerSource``) so``extractor`` and ``integration`` can both import it without an import@@ -310,9 +332,15 @@ class CuratorScheduler:return activeasync def _run_scheduled_journal_trigger(self) -> SchedulerResult:- """Run one shared fire task until every late request is observed."""+ """Run one shared fire task until every late request is observed.++ Bounded by :data:`_MAX_DRAIN_PASSES`; a request still pending after+ that is served by the next trigger.+ """result = await self.trigger(TriggerSource.JOURNAL)- while self._journal_dirty:+ passes = 0+ while self._journal_dirty and passes < _MAX_DRAIN_PASSES:+ passes += 1self._journal_dirty = Falseresult = await self.trigger(TriggerSource.JOURNAL)return result@@ -369,29 +397,42 @@ class CuratorScheduler:return Trueasync def _drain_journal(self) -> SchedulerResult:- """Drain coalesced work and safely serialized same-target candidates."""+ """Drain coalesced work and safely serialized same-target candidates.++ Bounded twice over: at most :data:`_MAX_DRAIN_PASSES` follow-up+ passes, and a pass that moved nothing (judge deferred, unavailable,+ truncated or rejected; rows in backoff; lock held) ends the drain even+ if new requests arrived meanwhile. The next trigger retries under the+ runaway guard's backoff instead of this loop re-billing the failure.+ """result = await self._do_trigger(TriggerSource.JOURNAL,episode_paths=None,review_keys=None,)- deferred_passes = 0- while True:- deferred = (- result.triggered- and result.curator_output_label.startswith("journal-deferred:")- and deferred_passes < _MAX_DEFERRED_DRAIN_PASSES+ for _pass in range(_MAX_DRAIN_PASSES):+ deferred = result.triggered and result.curator_output_label.startswith(+ "journal-deferred:")if not self._journal_dirty and not deferred:break- if deferred:- deferred_passes += 1+ if not _made_progress(result):+ # Late requests are answered by this failed pass: running the+ # same judge again now cannot succeed where it just did not.+ self._journal_dirty = False+ breakself._journal_dirty = Falseresult = await self._do_trigger(TriggerSource.JOURNAL,episode_paths=None,review_keys=None,)+ else:+ log.info(+ "CuratorScheduler: journal drain stopped after %d passes; the "+ "remaining candidates wait for the next trigger",+ _MAX_DRAIN_PASSES,+ )return resultasync def _do_trigger(diff --git a/jarvis/memory/wiki/search_aliases.py b/jarvis/memory/wiki/search_aliases.pyindex dcf4e77626..29ad9d0d42 100644--- a/jarvis/memory/wiki/search_aliases.py+++ b/jarvis/memory/wiki/search_aliases.py@@ -248,6 +248,7 @@ async def generate_aliases(registry: Any,languages: tuple[str, ...] | None = None,timeout_s: float = 30.0,+ count_against_daily_cap: bool = True,) -> list[str]:"""Search terms for one page, or ``[]`` when no provider is reachable.@@ -255,38 +256,48 @@ async def generate_aliases(the whole chain exhausted, a malformed answer — returns an empty list witha logged reason, because a page without aliases is merely as findable asit is today, while a raising generator would block the write itself.++ Nobody waits on this call, so it bills only what background work may bill+ (:mod:`jarvis.brain.background_policy`): in subscription mode with no+ usable subscription the page is simply written without aliases. Write-time+ calls count against the wiki's daily call cap+ (:mod:`jarvis.memory.wiki.background_guard`); the explicit, user-started+ vault backfill passes ``count_against_daily_cap=False``."""if not title.strip() and not body.strip():return []langs = languages or target_languages(cfg)+ from jarvis.brain.background_policy import BackgroundDeferred # noqa: PLC0415from jarvis.core.protocols import BrainMessage, BrainRequest # noqa: PLC0415+ from jarvis.memory.wiki.background_guard import guard # noqa: PLC0415from jarvis.memory.wiki.provider_chain import ( # noqa: PLC0415- background_wiki_providers,- build_wiki_provider_chain,+ build_background_wiki_chain,complete_with_fallback,)# Same key-aware chain the curator uses: lead with the configured wiki# provider, then every other registered provider that actually holds a- # credential (AP-22 — never a single-provider brick).+ # credential (AP-22 — never a single-provider brick) and may bill+ # background work.try:- available = set(registry.available())curator = getattr(getattr(getattr(cfg, "memory", None), "wiki", None), "curator", None)primary = str(getattr(curator, "provider", "") or "").strip() or str(getattr(getattr(cfg, "brain", None), "primary", "") or "")- chain = build_wiki_provider_chain(+ background = build_background_wiki_chain(+ registry=registry,+ config=cfg,primary=primary,model_override="",- available=available,- credential_ready=background_wiki_providers(- available=available, config=cfg- ),)+ except BackgroundDeferred as exc:+ log.info("search_aliases: no aliases for %r now — %s", title, exc)+ return []except Exception: # noqa: BLE001 — a broken chain build must not block a writelog.warning("search_aliases: could not build a provider chain", exc_info=True)return []+ chain = background.chainif not chain:log.info("search_aliases: no credential-ready provider — page indexed "@@ -315,7 +326,17 @@ async def generate_aliases(timeout_s=timeout_s,label="wiki-search-aliases",aggregate=aggregate,+ provider_options=background.provider_options,+ before_attempt=(+ guard.hook(cfg, "search-aliases") if count_against_daily_cap else None+ ),+ # Aliases are optional: a subscription that is busy right now is+ # not a broken wiki and must not paint the red banner.+ record_chain_failure=not background.subscription_mode,)+ except BackgroundDeferred as exc:+ log.info("search_aliases: no aliases for %r now — %s", title, exc)+ return []except Exception: # noqa: BLE001 — degrade to no aliases, never fail the writelog.warning("search_aliases: alias call raised", exc_info=True)return []@@ -460,8 +481,15 @@ async def backfill_vault(title_match = re.search(r"^\s{0,3}#\s+(.+)", body, re.MULTILINE)title = title_match.group(1).strip() if title_match else path.stem+ # Started explicitly by the user (route/CLI), so it does not eat+ # the daily cap that protects unattended background work; the+ # billing policy still applies to every page.generated = await generate_aliases(- title=title, body=body, cfg=cfg, registry=registry+ title=title,+ body=body,+ cfg=cfg,+ registry=registry,+ count_against_daily_cap=False,)if not generated:summary["no_aliases"] += 1diff --git a/jarvis/memory/wiki/session_rollup.py b/jarvis/memory/wiki/session_rollup.pyindex 56ae955688..975134738b 100644--- a/jarvis/memory/wiki/session_rollup.py+++ b/jarvis/memory/wiki/session_rollup.py@@ -436,19 +436,51 @@ class SessionRollupWorker:self._cfg, self._config)+ # The rollup is background work nobody waits on (and dead by default:+ # ``wiki_write_enabled`` is off and no built-in watcher publishes+ # ``IdleEntered``). Should it ever fire, it obeys the same rules as+ # the rest of the wiki: the background billing policy and the daily+ # runaway cap. A provider that may not bill now skips the digest.+ from jarvis.brain.background_policy import (+ BackgroundDeferred,+ background_providers,+ )+ from jarvis.memory.wiki.background_guard import guard+ from jarvis.memory.wiki.curator_llm import instantiate_curator_brain+ from jarvis.memory.wiki.provider_chain import subscription_provider_options++ try:+ guard.check_ready(self._config)+ decision = background_providers([provider_name])+ if not decision.permits(provider_name):+ raise BackgroundDeferred(decision.reason)+ guard.reserve_call(self._config, label="session-rollup")+ except BackgroundDeferred as exc:+ log.info("SessionRollupWorker: digest skipped — %s", exc)+ return None+ pinned = subscription_provider_options(decision, self._registry).get(+ provider_name+ )+try:async with self._brain_lock:- if self._brain is None:+ if pinned:+ # A subscription pin must reach the live instance; never+ # reuse one built before the install ran on a subscription.+ self._brain = await asyncio.to_thread(+ instantiate_curator_brain,+ self._registry,+ provider_name,+ model,+ provider_options=pinned,+ )+ elif self._brain is None:# Same curator-tier instantiation as the extractor/judge:# disables Gemini thinking AND flags structured prompts so# a subscription-CLI brain forwards the digest instructions# verbatim instead of the conversational "1-3 short# sentences" wrapper that contradicts the requested# flowing paragraph.- from jarvis.memory.wiki.curator_llm import (- instantiate_curator_brain,- )-self._brain = await asyncio.to_thread(instantiate_curator_brain,self._registry,diff --git a/jarvis/ui/web/wiki_routes.py b/jarvis/ui/web/wiki_routes.pyindex 9008ca639b..f03defd06d 100644--- a/jarvis/ui/web/wiki_routes.py+++ b/jarvis/ui/web/wiki_routes.py@@ -841,9 +841,13 @@ async def backfill_wiki(skip_reason = str(getattr(scheduler_result, "skip_reason", "unknown"))breakstage2 = runtime.journal.capture_decision_summary(review_keys)- if label in {"judge-unavailable", "judge-truncated"} or label.startswith(- "journal-transient:"- ):+ # ``judge-deferred``: the wiki must wait (subscription not usable,+ # runaway-guard backoff or daily cap). Repeating now changes nothing.+ if label in {+ "judge-unavailable",+ "judge-truncated",+ "judge-deferred",+ } or label.startswith("journal-transient:"):skip_reason = labelbreakdiff --git a/tests/fakes/fake_background_billing.py b/tests/fakes/fake_background_billing.pynew file mode 100644index 0000000000..42d19b3fa5--- /dev/null+++ b/tests/fakes/fake_background_billing.py@@ -0,0 +1,83 @@+"""Deterministic background-billing state for wiki tests.++Two pieces of process-wide state decide what a background wiki model call may+bill: the subscription policy (``jarvis.brain.background_policy`` — a login+probe plus a sticky "a subscription was seen" marker on disk) and the wiki's+runaway guard (``jarvis.memory.wiki.background_guard`` — a persisted daily+call counter and a backoff window). Both read the developer's real user-data+directory by default, so a suite run on a machine with a signed-in CLI would+silently switch every wiki test into subscription mode.++:class:`BackgroundBilling` pins both to a temporary directory and a scripted+login table. The default is a key-only install: no subscription signed in,+nothing remembered, zero calls spent.+"""++from __future__ import annotations++from dataclasses import dataclass, field+from pathlib import Path++import pytest++from jarvis.brain import background_policy+from jarvis.memory.wiki.background_guard import guard+++@dataclass+class BackgroundBilling:+ """Scripted login states plus isolated marker/counter files."""++ root: Path+ logins: dict[str, bool | None] = field(default_factory=dict)++ def sign_in(self, provider: str) -> None:+ """Make *provider*'s subscription login answer ``True`` from now on."""+ self.logins[provider] = True+ background_policy._probe_cache.pop(provider, None) # noqa: SLF001 - test seam++ def sign_out(self, provider: str) -> None:+ """The login now answers ``False``; the sticky marker is kept."""+ self.logins[provider] = False+ background_policy._probe_cache.pop(provider, None) # noqa: SLF001 - test seam++ def remember_subscription(self, provider: str = "claude-cli") -> None:+ """Record that a subscription was seen connected (subscription mode)."""+ background_policy.note_connected(provider)++ @property+ def calls_today(self) -> int:+ return guard.calls_today()+++def isolate_background_billing(+ monkeypatch: pytest.MonkeyPatch,+ root: Path,+) -> BackgroundBilling:+ """Point the policy and the guard at *root* and script the login probe."""+ root.mkdir(parents=True, exist_ok=True)+ billing = BackgroundBilling(root=root)+ marker = root / "subscription_seen.json"+ monkeypatch.setattr(background_policy, "_marker_path", lambda: marker)+ background_policy.reset_for_tests()+ background_policy._probe_override = billing.logins.get # noqa: SLF001 - test seam+ guard.reset_for_tests(state_path=root / "wiki_background_calls.json")+ from jarvis.memory.wiki.health import health++ health.clear_background_wait()+ return billing+++def reset_background_billing() -> None:+ from jarvis.memory.wiki.health import health++ background_policy.reset_for_tests()+ guard.reset_for_tests()+ health.clear_background_wait()+++__all__ = [+ "BackgroundBilling",+ "isolate_background_billing",+ "reset_background_billing",+]diff --git a/tests/integration/memory/conftest.py b/tests/integration/memory/conftest.pynew file mode 100644index 0000000000..46e5e7ed31--- /dev/null+++ b/tests/integration/memory/conftest.py@@ -0,0 +1,24 @@+"""Shared fixtures for the memory integration suites."""++from __future__ import annotations++import pytest++[email protected](autouse=True)+def background_billing(tmp_path_factory, monkeypatch): # noqa: ANN001, ANN201+ """Key-only install by default: no subscription, nothing spent today.++ Keeps the background billing policy and the wiki's runaway guard away from+ the developer's real subscription marker and daily call counter.+ """+ from tests.fakes.fake_background_billing import (+ isolate_background_billing,+ reset_background_billing,+ )++ billing = isolate_background_billing(+ monkeypatch, tmp_path_factory.mktemp("background-billing")+ )+ yield billing+ reset_background_billing()diff --git a/tests/unit/memory/wiki/conftest.py b/tests/unit/memory/wiki/conftest.pyindex d5eda49bfa..9ecd623669 100644--- a/tests/unit/memory/wiki/conftest.py+++ b/tests/unit/memory/wiki/conftest.py@@ -164,6 +164,26 @@ def _reset_provider_failure_memory():reset_provider_failure_memory()[email protected](autouse=True)+def background_billing(tmp_path_factory, monkeypatch): # noqa: ANN001, ANN201+ """Key-only install by default: no subscription, nothing spent today.++ The background billing policy and the wiki's runaway guard would+ otherwise read the developer's real subscription marker and call counter.+ Tests that need subscription mode script it through the returned fake.+ """+ from tests.fakes.fake_background_billing import (+ isolate_background_billing,+ reset_background_billing,+ )++ billing = isolate_background_billing(+ monkeypatch, tmp_path_factory.mktemp("background-billing")+ )+ yield billing+ reset_background_billing()++@pytest.fixturedef fake_repo() -> FakePageRepository:"""A fresh ``FakePageRepository`` per test."""diff --git a/tests/unit/memory/wiki/test_background_guard.py b/tests/unit/memory/wiki/test_background_guard.pynew file mode 100644index 0000000000..25e4a5b134--- /dev/null+++ b/tests/unit/memory/wiki/test_background_guard.py@@ -0,0 +1,448 @@+"""Background wiki model calls obey the billing rule and a runaway guard.++Live 2026-09-30: ~5 EUR went in three hours while nobody was at the PC — the+wiki kept calling paid keys in the background (~300 calls on keys in 30+days). These tests pin the fix:++* In subscription mode no keyed provider is ever instantiated; a subscription+ that cannot take the work makes it WAIT (candidates stay pending) and the+ next attempt backs off instead of spinning.+* A hard daily cap on the NUMBER of background calls holds even on key-only+ installs, counts every attempt (split-and-retry halves included) and+ survives a restart.+* Drain loops, the age flush and review retries are bounded.+"""+from __future__ import annotations++import asyncio+import datetime as dt+import json+from collections.abc import AsyncIterator+from pathlib import Path+from typing import Any++import pytest+import pytest_asyncio++from jarvis.brain.background_policy import BackgroundDeferred+from jarvis.core.config import (+ BrainConfig,+ BrainProviderConfig,+ JarvisConfig,+ MemoryConfig,+ SchedulerConfig,+ WikiIntegrationConfig,+ WikiMemoryConfig,+)+from jarvis.core.protocols import BrainDelta, BrainRequest+from jarvis.memory.wiki.atomic_writer import AtomicWriter+from jarvis.memory.wiki.background_guard import (+ DAILY_CAP_REACHED,+ DEFAULT_DAILY_CALL_CAP,+ WAITING_FOR_SUBSCRIPTION,+ WikiBackgroundGuard,+ daily_cap,+ guard,+)+from jarvis.memory.wiki.consolidator import Consolidator+from jarvis.memory.wiki.curator import WikiCurator+from jarvis.memory.wiki.curator_llm import WikiCuratorLLM+from jarvis.memory.wiki.health import health+from jarvis.memory.wiki.journal import CandidateFact, CandidateJournal+from jarvis.memory.wiki.lock import VaultLock+from jarvis.memory.wiki.log_writer import LogWriter+from jarvis.memory.wiki.page import MarkdownPageRepository+from jarvis.memory.wiki.scheduler import (+ CuratorScheduler,+ TriggerSource,+ fire_journal_trigger,+)+from jarvis.memory.wiki.vault_index import VaultIndex++KEYED = {"gemini", "openrouter", "grok", "openai"}+++class _ScriptedBrain:+ name = "scripted-brain"+ context_window = 100_000+ supports_tools = False+ supports_vision = False++ def __init__(self, *, text: str = "[]", finish_reason: str = "stop", fail: bool = False):+ self._text = text+ self._finish_reason = finish_reason+ self._fail = fail+ self.calls = 0++ async def complete(self, req: BrainRequest) -> AsyncIterator[BrainDelta]:+ self.calls += 1+ if self._fail:+ raise RuntimeError("provider down")+ yield BrainDelta(content=self._text)+ yield BrainDelta(finish_reason=self._finish_reason)++ def estimate_cost(self, req: BrainRequest) -> float: # pragma: no cover+ return 0.0+++class _RecordingRegistry:+ """Records every ``available()`` probe and every instantiation."""++ def __init__(self, providers: set[str], brain: Any) -> None:+ self._providers = set(providers)+ self._brain = brain+ self.available_calls = 0+ self.instantiated: list[str] = []++ def available(self) -> set[str]:+ self.available_calls += 1+ return set(self._providers)++ def instantiate(self, name: str, **_kwargs: Any) -> Any:+ self.instantiated.append(name)+ return self._brain+++def _config(*, cap: int | None = None) -> JarvisConfig:+ integration = (+ WikiIntegrationConfig(max_background_llm_calls_per_day=cap)+ if cap is not None+ else WikiIntegrationConfig()+ )+ return JarvisConfig(+ brain=BrainConfig(+ primary="gemini",+ providers={"gemini": BrainProviderConfig(model="gemini-3.1-pro-preview")},+ ),+ memory=MemoryConfig(wiki=WikiMemoryConfig()),+ wiki_integration=integration,+ )+++@pytest_asyncio.fixture+async def wiki(tmp_path: Path):+ vault_root = tmp_path / "vault"+ for sub in ("entities", "concepts", "projects", "sessions", "_archive"):+ (vault_root / sub).mkdir(parents=True)+ (vault_root / "schema.md").write_text("# stub schema\n", encoding="utf-8")+ (vault_root / "log.md").write_text("# Wiki Log\n", encoding="utf-8")+ repo = MarkdownPageRepository()+ vault = VaultIndex(repo=repo)+ await vault.scan(vault_root)+ curator = WikiCurator(+ repo=repo,+ vault=vault,+ writer=AtomicWriter(vault_root=vault_root, backup_dir=tmp_path / "backups"),+ llm=WikiCuratorLLM.__new__(WikiCuratorLLM),+ log_writer=LogWriter(log_path=vault_root / "log.md"),+ vault_root=vault_root,+ )+ journal = CandidateJournal(tmp_path / "jarvis.db")+ yield vault_root, curator, journal+ journal.close()+++def _consolidator(wiki_tuple, registry: Any, *, config: JarvisConfig) -> Consolidator:+ vault_root, curator, journal = wiki_tuple+ return Consolidator(+ config=config,+ journal=journal,+ curator=curator,+ search=None,+ vault_root=vault_root,+ registry=registry,+ )+++def _journal_facts(journal: CandidateJournal, count: int) -> None:+ for index in range(count):+ journal.append(+ [+ CandidateFact(+ fact=f"Lena fact number {index} about Hamburg.",+ kind="person",+ subjects=("lena",),+ )+ ],+ source_label="test",+ turn_hash=f"turn-{index}",+ )++[email protected](autouse=True)+def _isolated(monkeypatch: pytest.MonkeyPatch): # noqa: ANN202+ """Keep write-time alias lookups out of the judge call counts and start+ every test without a chain-failure record from an earlier one."""++ async def _passthrough(page_text: str, **_kwargs: Any) -> str:+ return page_text++ monkeypatch.setattr(+ "jarvis.memory.wiki.consolidator.ensure_page_aliases", _passthrough+ )+ health.record_chain_success()+ yield+ health.record_chain_success()+++# --- subscription mode -------------------------------------------------------+++async def test_subscription_mode_never_instantiates_a_keyed_provider(+ wiki, background_billing, # noqa: ANN001+) -> None:+ background_billing.remember_subscription("claude-cli")+ background_billing.sign_out("claude-cli")+ brain = _ScriptedBrain()+ registry = _RecordingRegistry(KEYED | {"claude-cli"}, brain)+ consolidator = _consolidator(wiki, registry, config=_config())+ _journal_facts(wiki[2], 2)++ label = await consolidator.run_once()++ assert label == "judge-deferred"+ assert registry.instantiated == [], "a waiting install must never build a keyed judge"+ assert brain.calls == 0+ assert len(wiki[2].pending()) == 2, "candidates stay pending while waiting"+ snapshot = health.snapshot()+ assert snapshot["background_wait"]["state"] == WAITING_FOR_SUBSCRIPTION+ assert snapshot["last_chain_failure"] is None, "waiting is not a red chain failure"+++async def test_deferral_backs_off_instead_of_retrying_every_trigger(+ wiki, background_billing, # noqa: ANN001+) -> None:+ background_billing.remember_subscription("claude-cli")+ background_billing.sign_out("claude-cli")+ registry = _RecordingRegistry(KEYED | {"claude-cli"}, _ScriptedBrain())+ consolidator = _consolidator(wiki, registry, config=_config())+ _journal_facts(wiki[2], 1)++ assert await consolidator.run_once() == "judge-deferred"+ probes_after_first = registry.available_calls+ for _ in range(5):+ assert await consolidator.run_once() == "judge-deferred"++ assert registry.available_calls == probes_after_first, (+ "inside the backoff window no provider is even looked up"+ )+ assert guard.ready(_config()) is False+ assert len(wiki[2].pending()) == 1+++async def test_failing_subscription_waits_instead_of_raising_the_red_banner(+ wiki, background_billing, # noqa: ANN001+) -> None:+ """Signed in but not answering (rate limited, out of credit): still wait."""+ background_billing.sign_in("claude-cli")+ brain = _ScriptedBrain(fail=True)+ registry = _RecordingRegistry(KEYED | {"claude-cli"}, brain)+ consolidator = _consolidator(wiki, registry, config=_config())+ _journal_facts(wiki[2], 1)++ assert await consolidator.run_once() == "judge-deferred"+ assert registry.instantiated == ["claude-cli"], "only the subscription was tried"+ assert health.snapshot()["last_chain_failure"] is None+ assert health.snapshot()["background_wait"]["state"] == WAITING_FOR_SUBSCRIPTION+ assert len(wiki[2].pending()) == 1+++# --- key-only installs -------------------------------------------------------+++async def test_key_only_install_keeps_using_its_key(wiki) -> None: # noqa: ANN001+ brain = _ScriptedBrain(text=json.dumps([]))+ registry = _RecordingRegistry({"gemini"}, brain)+ consolidator = _consolidator(wiki, registry, config=_config())+ _journal_facts(wiki[2], 1)++ await consolidator.run_once()++ assert registry.instantiated == ["gemini"]+ assert guard.calls_today() == 1+++async def test_failed_chain_backs_off_on_a_key_only_install(wiki) -> None: # noqa: ANN001+ registry = _RecordingRegistry({"gemini"}, _ScriptedBrain(fail=True))+ consolidator = _consolidator(wiki, registry, config=_config())+ _journal_facts(wiki[2], 1)++ assert await consolidator.run_once() == "judge-unavailable"+ for _ in range(3):+ assert await consolidator.run_once() == "judge-deferred"++ assert registry.instantiated == ["gemini"], "no spin while the chain is down"+ assert len(wiki[2].pending()) == 1+++# --- daily cap ---------------------------------------------------------------+++def test_daily_cap_default_is_a_generous_runaway_guard() -> None:+ assert DEFAULT_DAILY_CALL_CAP == 200+ assert daily_cap(JarvisConfig()) == 200+ assert daily_cap(None) == 200+ assert daily_cap(_config(cap=0)) == 1, "a cap below one still allows one call"+++def test_daily_cap_stops_calls_and_survives_a_restart() -> None:+ config = _config(cap=2)+ guard.reserve_call(config)+ guard.reserve_call(config)+ with pytest.raises(BackgroundDeferred):+ guard.reserve_call(config)++ state_path = guard._state_path() # noqa: SLF001 - test seam+ guard.reset_for_tests(state_path=state_path) # a fresh process+ assert guard.calls_today() == 2+ with pytest.raises(BackgroundDeferred):+ guard.check_ready(config)+ assert health.snapshot()["background_wait"]["state"] == DAILY_CAP_REACHED+++def test_daily_cap_resets_on_the_next_day(monkeypatch: pytest.MonkeyPatch) -> None:+ config = _config(cap=1)+ guard.reserve_call(config)+ assert guard.ready(config) is False++ tomorrow = (dt.date.today() + dt.timedelta(days=1)).isoformat()+ monkeypatch.setattr(WikiBackgroundGuard, "_today", staticmethod(lambda: tomorrow))+ assert guard.calls_today() == 0+ assert guard.ready(config) is True+++async def test_daily_cap_stops_the_judge_and_counts_split_and_retry(wiki) -> None: # noqa: ANN001+ """The cap holds on key-only installs; each bisected half is a call."""+ brain = _ScriptedBrain(text="[", finish_reason="length")+ registry = _RecordingRegistry({"gemini"}, brain)+ consolidator = _consolidator(wiki, registry, config=_config(cap=2))+ _journal_facts(wiki[2], 4)++ label = await consolidator.run_once()++ # Call 1: the whole batch truncates -> split. Call 2: the left half+ # truncates -> split again. The next half would be call 3: over the cap.+ assert label == "judge-deferred"+ assert brain.calls == 2+ assert guard.calls_today() == 2+ assert len(wiki[2].pending()) == 4, "nothing is lost when the cap stops the work"+ assert await consolidator.run_once() == "judge-deferred"+ assert brain.calls == 2, "no further call until tomorrow"+++# --- bounded loops and retries ----------------------------------------------+++async def test_drain_stops_on_a_pass_that_made_no_progress(tmp_path: Path) -> None:+ class _AlwaysDirty:+ def __init__(self) -> None:+ self.runs = 0+ self.scheduler: CuratorScheduler | None = None++ async def run_once(self, *, review_keys=None) -> str: # noqa: ANN001+ self.runs += 1+ assert self.scheduler is not None+ self.scheduler._journal_dirty = True # noqa: SLF001 - a new append+ return "judge-deferred"++ consolidator = _AlwaysDirty()+ scheduler = CuratorScheduler(+ curator=object(), # type: ignore[arg-type]+ lock=VaultLock(tmp_path / "curator.lock"),+ config=SchedulerConfig(),+ consolidator=consolidator,+ )+ consolidator.scheduler = scheduler++ await scheduler.trigger(TriggerSource.JOURNAL)+ assert consolidator.runs == 1++ await fire_journal_trigger(scheduler)+ assert consolidator.runs == 2, "a waiting judge is not re-run in a loop"+++async def test_age_flush_waits_out_the_backoff() -> None:+ from jarvis.memory.wiki.integration import _journal_age_flush_tick++ class _Journal:+ def oldest_pending_ms(self) -> int:+ return 0 # ancient++ class _Scheduler:+ def __init__(self) -> None:+ self.fired = 0++ def schedule_journal_trigger(self, *, name: str) -> asyncio.Task[Any]:+ self.fired += 1+ return asyncio.create_task(asyncio.sleep(0), name=name)++ scheduler = _Scheduler()+ guard.note_failure("every wiki provider failed")+ assert await _journal_age_flush_tick(_Journal(), scheduler, max_age_min=10) is False+ assert scheduler.fired == 0++ guard.note_progress()+ assert await _journal_age_flush_tick(_Journal(), scheduler, max_age_min=10) is True+ assert scheduler.fired == 1+ await asyncio.sleep(0)+++def test_failed_reviews_are_retried_a_bounded_number_of_times(tmp_path: Path) -> None:+ now_s = [1_000.0]+ journal = CandidateJournal(tmp_path / "jarvis.db", clock=lambda: now_s[0])+ key = "live:v2:session:turn-1"+ try:+ claims = 0+ while journal.claim_capture(key, "voice-fact:1", "voice-fact", "a" * 40):+ claims += 1+ assert journal.finish_capture(key, "failed", error_code="provider_timeout")+ assert claims < 50, "retries must be bounded"+ assert claims == 5+ finally:+ journal.close()+++# --- search aliases ----------------------------------------------------------+++async def test_search_aliases_wait_for_the_subscription(+ monkeypatch: pytest.MonkeyPatch, background_billing, # noqa: ANN001+) -> None:+ from jarvis.memory.wiki.search_aliases import generate_aliases++ monkeypatch.setattr(+ "jarvis.memory.wiki.provider_chain.credential_ready_wiki_providers",+ lambda *, available, config: set(available),+ )+ background_billing.remember_subscription("claude-cli")+ background_billing.sign_out("claude-cli")+ registry = _RecordingRegistry(KEYED | {"claude-cli"}, _ScriptedBrain(text="Hund"))++ aliases = await generate_aliases(+ title="Dog", body="The user's dog.", cfg=_config(), registry=registry,+ )++ assert aliases == []+ assert registry.instantiated == []+ assert health.snapshot()["last_chain_failure"] is None+++async def test_search_aliases_respect_the_daily_cap(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ from jarvis.memory.wiki.search_aliases import generate_aliases++ monkeypatch.setattr(+ "jarvis.memory.wiki.provider_chain.credential_ready_wiki_providers",+ lambda *, available, config: set(available),+ )+ config = _config(cap=1)+ guard.reserve_call(config)+ registry = _RecordingRegistry({"gemini"}, _ScriptedBrain(text="Hund"))++ aliases = await generate_aliases(+ title="Dog", body="The user's dog.", cfg=config, registry=registry,+ )++ assert aliases == []+ assert registry.instantiated == []diff --git a/tests/unit/memory/wiki/test_provider_chain.py b/tests/unit/memory/wiki/test_provider_chain.pyindex 52b11cc476..473ba89583 100644--- a/tests/unit/memory/wiki/test_provider_chain.py+++ b/tests/unit/memory/wiki/test_provider_chain.py@@ -173,20 +173,26 @@ def test_credential_probe_uses_core_portable_storage_and_keeps_oauth(assert ready == {"nvidia", "future-oauth"}-def test_background_work_skips_paid_keys_while_a_subscription_is_connected(- monkeypatch: pytest.MonkeyPatch,-) -> None:+def _stub_ready(monkeypatch: pytest.MonkeyPatch, ready: set[str]) -> None:import jarvis.memory.wiki.provider_chain as chain_modulemonkeypatch.setattr(chain_module,"credential_ready_wiki_providers",- lambda *, available, config: {"openai", "gemini", "codex", "ollama"},+ lambda *, available, config: set(ready),)+++def test_background_work_skips_paid_keys_while_a_subscription_is_connected(+ monkeypatch: pytest.MonkeyPatch, background_billing, # noqa: ANN001+) -> None:+ import jarvis.memory.wiki.provider_chain as chain_module++ _stub_ready(monkeypatch, {"openai", "gemini", "codex", "ollama"})+ background_billing.sign_in("codex")ready = chain_module.background_wiki_providers(available={"openai", "gemini", "codex", "ollama"},config=object(),- is_subscription=lambda name: name == "codex",)assert ready == {"codex", "ollama"} # subscription + keyless local only@@ -196,17 +202,83 @@ def test_background_work_keeps_keys_when_no_subscription_exists() -> None:import jarvis.memory.wiki.provider_chain as chain_module- monkeypatch.setattr(- chain_module,- "credential_ready_wiki_providers",- lambda *, available, config: {"openai"},- )+ _stub_ready(monkeypatch, {"openai"})ready = chain_module.background_wiki_providers(- available={"openai"}, config=object(), is_subscription=lambda _name: False+ available={"openai"}, config=object())assert ready == {"openai"} # a single-key install keeps a working wiki+def test_signed_out_subscription_waits_instead_of_using_keys(+ monkeypatch: pytest.MonkeyPatch, background_billing, # noqa: ANN001+) -> None:+ """The 5-EUR leak: one ``False`` probe used to hand the chain every key."""+ import jarvis.memory.wiki.provider_chain as chain_module+ from jarvis.brain.background_policy import BackgroundDeferred++ _stub_ready(monkeypatch, {"openai", "gemini", "grok"})+ background_billing.remember_subscription("claude-cli")+ background_billing.sign_out("claude-cli")+ assert chain_module.background_wiki_providers(+ available={"openai", "gemini", "grok", "claude-cli"}, config=object()+ ) == set()++ class _Registry:+ instantiated: list[str] = []++ def available(self) -> set[str]:+ return {"openai", "gemini", "grok", "claude-cli"}++ def instantiate(self, name: str, **_kwargs: Any) -> Any: # pragma: no cover+ self.instantiated.append(name)+ raise AssertionError("no provider may be built while waiting")++ with pytest.raises(BackgroundDeferred):+ chain_module.build_background_wiki_chain(+ registry=_Registry(),+ config=object(),+ primary="openai",+ model_override="",+ )+++def test_subscription_mode_pins_a_dual_billed_provider_to_its_login(+ monkeypatch: pytest.MonkeyPatch, background_billing, # noqa: ANN001+) -> None:+ """A card with a login AND a key slot must never fall through to the key."""+ import jarvis.memory.wiki.provider_chain as chain_module++ class _DualBilled:+ def __init__(self, model: str | None = None, prefer_subscription: bool = False):+ self.prefer_subscription = prefer_subscription++ class _KeyOnly:+ def __init__(self, model: str | None = None):+ self.model = model++ class _Registry:+ def available(self) -> set[str]:+ return {"codex", "openai"}++ def get_class(self, name: str) -> type:+ return _DualBilled if name == "codex" else _KeyOnly++ def instantiate(self, name: str, **_kwargs: Any) -> Any: # pragma: no cover+ raise AssertionError("building the chain instantiates nothing")++ _stub_ready(monkeypatch, {"codex", "openai"})+ background_billing.sign_in("codex")+ background = chain_module.build_background_wiki_chain(+ registry=_Registry(),+ config=object(),+ primary="openai",+ model_override="",+ )+ assert background.subscription_mode is True+ assert [name for name, _model in background.chain] == ["codex"]+ assert background.provider_options == {"codex": {"prefer_subscription": True}}++# --- the fallback loop -------------------------------------------------------@@ -965,3 +1037,53 @@ def test_exception_summary_carries_known_safe_diagnosis_only() -> None:RuntimeError("request failed ?key=sk-proj-XYZ at C:/Users/private"))assert raw == "RuntimeError"+++async def test_before_attempt_deferral_stops_the_chain_before_any_call():+ """The runaway guard raising at the cap is not a provider failure."""+ from jarvis.brain.background_policy import BackgroundDeferred+ from jarvis.memory.wiki.health import health++ health.record_chain_success()+ reg = _FakeRegistry(fail_providers=set())+ chain = build_wiki_provider_chain(+ primary="gemini", model_override="", available=reg.available()+ )++ def _cap_reached(_provider: str) -> None:+ raise BackgroundDeferred("daily cap reached")++ with pytest.raises(BackgroundDeferred):+ await complete_with_fallback(+ registry=reg,+ chain=chain,+ request=object(),+ timeout_s=5.0,+ label="test",+ aggregate=_aggregate,+ before_attempt=_cap_reached,+ )+ assert reg.tried == []+ assert health.snapshot()["last_chain_failure"] is None+++async def test_chain_failure_can_stay_off_the_red_banner():+ """Subscription-mode callers record a waiting state instead."""+ from jarvis.memory.wiki.health import health++ health.record_chain_success()+ reg = _FakeRegistry(fail_providers=set(_ALL))+ chain = build_wiki_provider_chain(+ primary="gemini", model_override="", available=reg.available()+ )+ result = await complete_with_fallback(+ registry=reg,+ chain=chain,+ request=object(),+ timeout_s=5.0,+ label="test",+ aggregate=_aggregate,+ record_chain_failure=False,+ )+ assert result is None+ assert health.snapshot()["last_chain_failure"] is None