Skip to content

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.

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.example
index 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 = true
vault_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 listener
diff --git a/jarvis/core/config.py b/jarvis/core/config.py
index 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.py
new file mode 100644
index 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.py
index 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 dropped
silently. Runs only inside the CuratorScheduler's lock+cooldown gates
as 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 dataclass
from pathlib import Path, PurePosixPath
from typing import TYPE_CHECKING, Any
+from jarvis.brain.background_policy import BackgroundDeferred
from jarvis.brain.provider_registry import BrainProviderRegistry
from jarvis.brain.streaming import aggregate, is_length_truncated
from jarvis.core.protocols import BrainMessage, BrainRequest
+from jarvis.memory.wiki.background_guard import guard as background_guard
from 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_array
from jarvis.memory.wiki.intent import match_wiki_intent
from jarvis.memory.wiki.journal import JournalRow, normalise_subjects
from jarvis.memory.wiki.page import normalise_sources_section
@@ -154,6 +159,10 @@ class _BatchOutcome:
unavailable: bool = False
truncated: bool = False
rejected: 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 = False
def 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 = None
self._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: BLE001
log.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) // 2
left = await self._process_rows(rows[:midpoint])
+ if left.waiting:
+ return left
right = 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 reason
return 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 None
agg, 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.py
index 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 annotations
import asyncio
-import functools
import json
import logging
import time
@@ -454,7 +453,6 @@ class WikiCuratorLLM:
self._brain: Brain | None = None
self._resolved_provider: str | None = None
self._resolved_model: str | None = None
- self._lock = asyncio.Lock()
@property
def 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 guard
from 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.chain
rejection_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.py
index 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 Sequence
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any, Literal
+from jarvis.brain.background_policy import BackgroundDeferred
from jarvis.brain.provider_registry import BrainProviderRegistry
from jarvis.brain.streaming import aggregate, is_length_truncated
from jarvis.core.protocols import BrainMessage, BrainRequest
from jarvis.core.redact import safe_preview
+from jarvis.memory.wiki.background_guard import guard as background_guard
from 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_array
from jarvis.memory.wiki.grounding import classify_user_attitude_evidence
from jarvis.memory.wiki.journal import CandidateFact, normalise_subjects
from jarvis.memory.wiki.residence import detect_residence_slug
@@ -49,6 +57,7 @@ from jarvis.memory.wiki.telemetry import telemetry
if TYPE_CHECKING:
from jarvis.core.config import JarvisConfig
from jarvis.memory.wiki.journal import CandidateJournal
+ from jarvis.memory.wiki.provider_chain import WikiBackgroundChain
log = logging.getLogger(__name__)
@@ -289,9 +298,7 @@ class ConversationFactExtractor:
self._journal = journal
self._registry = registry if registry is not None else BrainProviderRegistry()
self._credential_filter = registry is None
- self._brain: Any = None
self._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")
+ raise
except Exception: # noqa: BLE001 - the conversation must never notice
log.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,
+ )
+ break
if 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,
+ )
+ break
except Exception: # noqa: BLE001
log.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_000
error_code = "provider-chain-failed"
@@ -1295,31 +1370,6 @@ class ConversationFactExtractor:
return False
return 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: BLE001
return 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.py
index 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 = None
self._last_index: dict[str, Any] | None = None
self._last_chain_failure: dict[str, Any] | None = None
+ self._background_wait: dict[str, Any] | None = None
self._journal_backlog: int = 0
def 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.py
index 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.py
index 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 had
credit. This module gives the wiki the SAME resilience, plus an HONEST signal
when the whole chain is exhausted (AP-22 single-provider brick / AP-23
maintainer-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 annotations
import asyncio
+import inspect
import logging
import re
import threading
import time
from collections.abc import Callable, Mapping
+from dataclasses import dataclass
from typing import Any
+from jarvis.brain.background_policy import (
+ BackgroundDeferred,
+ BackgroundProviders,
+ background_providers,
+ subscription_capable,
+)
from jarvis.core.redact import safe_preview
from jarvis.costs.ledger import usage_context
from 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 pipeline
log.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.py
index 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 BackgroundDeferred
from 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 None
if registry is None:
from jarvis.brain.provider_registry import BrainProviderRegistry
registry = 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 report
def _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.py
index 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-callback
logging 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 active
async 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 += 1
self._journal_dirty = False
result = await self.trigger(TriggerSource.JOURNAL)
return result
@@ -369,29 +397,42 @@ class CuratorScheduler:
return True
async 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
+ break
self._journal_dirty = False
result = 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 result
async def _do_trigger(
diff --git a/jarvis/memory/wiki/search_aliases.py b/jarvis/memory/wiki/search_aliases.py
index 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 with
a logged reason, because a page without aliases is merely as findable as
it 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: PLC0415
from jarvis.core.protocols import BrainMessage, BrainRequest # noqa: PLC0415
+ from jarvis.memory.wiki.background_guard import guard # noqa: PLC0415
from 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 write
log.warning("search_aliases: could not build a provider chain", exc_info=True)
return []
+ chain = background.chain
if 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 write
log.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"] += 1
diff --git a/jarvis/memory/wiki/session_rollup.py b/jarvis/memory/wiki/session_rollup.py
index 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.py
index 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"))
break
stage2 = 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 = label
break
diff --git a/tests/fakes/fake_background_billing.py b/tests/fakes/fake_background_billing.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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.fixture
def 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.py
new file mode 100644
index 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.py
index 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_module
monkeypatch.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