harden: code fixes from the pre-launch audit

An adversarial pre-launch audit surfaced a cluster of correctness, cost,
and robustness issues. Fixes, with new/updated tests for each:

  - Incremental compile cost (CODE-5): `lore watch` re-ran the LLM over
    the entire corpus every interval against the user's BYO key. Add a
    per-session extraction cache (sessions are immutable -> id is a safe
    key) so only newly-ingested sessions hit the model; `--rebuild`
    ignores it. Output stays idempotent; cost is now incremental.

  - First-run works (BUILD-1): make `anthropic` (the default provider) a
    base dependency and guard SDK imports with an actionable message
    instead of a raw ModuleNotFoundError. `pipx install crewlore` then
    `lore compile` works with just a key.

  - Real local provider (DOC-4): `model.provider: local` + `base_url`
    routes to any OpenAI-compatible endpoint (Ollama/LM Studio/vLLM).
    Was advertised but unimplemented, with a dead-end error message.

  - `lore serve --mcp` (CODE-1): the documented MCP flag didn't exist;
    the copy-paste mcp.json failed to launch. Added.

  - Scrub tool-call args (SEC-1): secrets passed as tool-call arguments
    live in event `meta`, which bypassed the scrubber. Walk `meta`
    recursively. Broaden coverage: AWS ASIA + secret-key assignments,
    all `xox?-` Slack tokens, quoted multi-word secrets (SEC-2/3/4).

  - Usage sidecar (CODE-7): `lore query` rewrote the git-tracked
    claims.jsonl on every call (usage bump). Move volatile usage stats
    to a gitignored sidecar; committed claims.jsonl stays byte-stable.

  - Timezone safety (CODE-2): timestamps are always tz-aware, so a
    timestampless transcript no longer crashes the actuation loop.

  - Compile resilience (CODE-6): one failing session (429/oversized
    context) no longer aborts the whole pass — skip and continue.

  - Unify fidelity definition (CODE-4): replay reuses the gate's
    `_canonical_form`, so the reported number matches what the gate
    enforces.

  - `lore --version` (HYG-1); drop dead `superseded` status (CODE-9);
    remove misleading `_normalize` alias (CODE-10); add py3.13 classifier.

131 tests passing (was 103). Lint clean. Clean wheel installs and runs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: srijansk

pyproject.toml

@@ -22,23 +22,27 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Software Development :: Libraries :: Application Frameworks",
 ]
 dependencies = [
     "typer>=0.12,<1.0",
     "rich>=13.0,<16.0",
     "pydantic>=2.0,<3.0",
     "pyyaml>=6.0,<7.0",
+    # Anthropic is the default model provider, so it ships in the base install:
+    # `pipx install crewlore` then `lore compile` works with just an API key.
+    "anthropic>=0.39",
 ]
 
 [project.scripts]
 lore = "lore.cli:app"
 
 [project.optional-dependencies]
+# OpenAI SDK — for `model.provider: openai` and for `local` (OpenAI-compatible endpoints).
 openai = ["openai>=1.0"]
-anthropic = ["anthropic>=0.30"]
 serve = ["mcp>=1.0"]
-dev = ["pytest>=8.0", "pytest-cov", "ruff"]
+dev = ["pytest>=8.0", "pytest-cov", "ruff", "openai>=1.0"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/lore"]

src/lore/actuation.py

@@ -14,13 +14,18 @@
 
 from __future__ import annotations
 
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 
 from lore.schemas import Claim
 
 _REINFORCE_PER_INFLUENCE = 0.1
 
 
+def _as_utc(dt: datetime) -> datetime:
+    """Coerce a possibly-naive datetime to UTC so aware/naive subtraction can't crash."""
+    return dt if dt.tzinfo is not None else dt.replace(tzinfo=timezone.utc)
+
+
 def apply_lifecycle(
     claims: list[Claim],
     *,
@@ -44,7 +49,11 @@ def _step(c: Claim, now: datetime, max_unused_age: timedelta, override_threshold
         return c.model_copy(update={"status": "archived"})
 
     # Never used and stale -> decay out of the active set.
-    if u.times_served == 0 and c.observed_at is not None and (now - c.observed_at) > max_unused_age:
+    if (
+        u.times_served == 0
+        and c.observed_at is not None
+        and (_as_utc(now) - _as_utc(c.observed_at)) > max_unused_age
+    ):
         return c.model_copy(update={"status": "archived"})
 
     # Used and valued -> reinforce.

src/lore/capture/adapters/claude_code.py

@@ -8,7 +8,7 @@
 
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 
 from lore.schemas import NSFEvent
@@ -22,9 +22,17 @@
 
 
 def _parse_ts(raw: str | None) -> datetime:
+    """Always return a timezone-aware UTC datetime.
+
+    A transcript record may omit `timestamp` (older/edited/third-party files), and
+    a present timestamp may lack a zone. Both must yield an aware datetime, or the
+    actuation lifecycle (which subtracts `now` in UTC) crashes with a naive-vs-aware
+    TypeError downstream.
+    """
     if not raw:
-        return datetime.fromtimestamp(0)
-    return datetime.fromisoformat(raw.replace("Z", "+00:00"))
+        return datetime.fromtimestamp(0, tz=timezone.utc)
+    dt = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    return dt if dt.tzinfo is not None else dt.replace(tzinfo=timezone.utc)
 
 
 class ClaudeCodeAdapter:

src/lore/cli.py

@@ -15,6 +15,7 @@
 
 import typer
 
+from lore import __version__
 from lore.serve.server import KnowledgeServer
 from lore.store import LoreStore
 
@@ -24,6 +25,22 @@
 TranscriptsOpt = typer.Option(None, "--transcripts", help="Override the transcripts dir.")
 
 
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"crewlore {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _main(
+    version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True,
+        help="Show the crewlore version and exit.",
+    ),
+) -> None:
+    """Compile coding-agent sessions into team tribal knowledge, locally."""
+
+
 def _transcript_dir(store: LoreStore, override: Path | None) -> Path:
     if override is not None:
         return override
@@ -86,19 +103,25 @@ def query(text: str, repo: Path = RepoOpt, limit: int = 5):
             typer.echo(f"    -> {c.action}")
 
 
-def _compile_once(store: LoreStore, transcript_dir: Path) -> dict:
+def _compile_once(store: LoreStore, transcript_dir: Path, *, rebuild: bool = False) -> dict:
     from lore.capture.adapters.claude_code import ClaudeCodeAdapter
     from lore.compile.run import auto_compile
 
     extractor = _build_extractor(store)
-    return auto_compile(store, extractor, ClaudeCodeAdapter(), transcript_dir)
+    return auto_compile(store, extractor, ClaudeCodeAdapter(), transcript_dir, rebuild=rebuild)
 
 
 @app.command()
-def compile(repo: Path = RepoOpt, transcripts: Path = TranscriptsOpt):  # noqa: A001
+def compile(  # noqa: A001
+    repo: Path = RepoOpt,
+    transcripts: Path = TranscriptsOpt,
+    rebuild: bool = typer.Option(
+        False, "--rebuild", help="Ignore the extraction cache and re-extract all sessions."
+    ),
+):
     """Ingest new transcripts, distill to claims + book, and prune (one pass)."""
     store = LoreStore(repo)
-    stats = _compile_once(store, _transcript_dir(store, transcripts))
+    stats = _compile_once(store, _transcript_dir(store, transcripts), rebuild=rebuild)
     typer.echo(
         f"ingested {stats['ingested']} new sessions "
         f"({stats['redactions']} redactions); "
@@ -112,12 +135,19 @@ def watch(
     transcripts: Path = TranscriptsOpt,
     interval: int = typer.Option(300, "--interval", help="Seconds between passes."),
     once: bool = typer.Option(False, "--once", help="Run a single pass and exit (cron mode)."),
+    rebuild: bool = typer.Option(
+        False, "--rebuild", help="Ignore the extraction cache and re-extract all sessions."
+    ),
 ):
-    """Automatically compile on an interval — so nobody has to remember to."""
+    """Automatically compile on an interval — so nobody has to remember to.
+
+    Extraction is cached per session, so each pass only sends newly-ingested
+    sessions to the model; cost is incremental, not per-corpus-per-interval.
+    """
     store = LoreStore(repo)
     tdir = _transcript_dir(store, transcripts)
     while True:
-        stats = _compile_once(store, tdir)
+        stats = _compile_once(store, tdir, rebuild=rebuild)
         typer.echo(
             f"[watch] +{stats['ingested']} sessions, "
             f"{stats['active']} active claims, {stats['conflicts']} conflicts"
@@ -132,8 +162,16 @@ def watch(
 
 
 @app.command()
-def serve(repo: Path = RepoOpt):
-    """Start the MCP server exposing query-time retrieval."""
+def serve(
+    repo: Path = RepoOpt,
+    mcp: bool = typer.Option(
+        True, "--mcp", help="Run as an MCP server over stdio (the only mode today)."
+    ),
+):
+    """Start the MCP server exposing query-time retrieval to any MCP client."""
+    if not mcp:  # reserved for future non-MCP serve modes
+        typer.echo("Only MCP serving is supported today; run without --no-mcp.")
+        raise typer.Exit(1)
     try:
         from lore.serve.mcp_server import run_mcp
     except ImportError:

src/lore/compile/extractor.py

@@ -85,10 +85,6 @@ def _canonical_form(text: str) -> str:
     return text.strip().lower()
 
 
-# Back-compat alias for the call sites that used _normalize() during build-up.
-_normalize = _canonical_form
-
-
 class LLMExtractor:
     def __init__(
         self, complete: Complete, *, author: str = "unknown", harness: str = "claude-code"
@@ -122,7 +118,7 @@ def extract(
         #    when a long agent reply is split by a tool_call between segments)
         # The result: a quote that spans an agent reply punctuated by tool
         # calls still validates against the continuous prose.
-        haystack = _normalize(
+        haystack = _canonical_form(
             "\n".join(e.content for e in events if e.kind != "tool_call")
         )
         provenance = Provenance(session=session_id, author=self._author, harness=self._harness)
@@ -152,7 +148,7 @@ def _build_claim(self, item, provenance, observed_at, haystack) -> Claim | None:
                 quote=a["quote"],
             )
             for a in item.get("anchors", [])
-            if a.get("quote") and _normalize(a["quote"]) in haystack
+            if a.get("quote") and _canonical_form(a["quote"]) in haystack
         ]
         if not verified:  # fidelity gate: no verbatim anchor -> reject
             return None

src/lore/compile/llm.py

@@ -1,9 +1,12 @@
 """Provider abstraction so lore is genuinely BYO-key / local-first: point it at
-Anthropic, OpenAI, or anything that can answer a `complete(prompt) -> str` call.
-Nothing routes through any lore-operated infrastructure because there is none.
-
-SDKs are imported lazily so the package installs without them, and a missing key
-fails loudly with a clear message rather than silently producing no claims.
+Anthropic, OpenAI, or any OpenAI-compatible endpoint you run yourself (Ollama,
+LM Studio, vLLM, …) via `provider: local` + `base_url`. Nothing routes through
+any lore-operated infrastructure because there is none.
+
+The default provider (Anthropic) ships as a base dependency so the headline
+`pipx install crewlore` → `lore compile` path works with just a key. The OpenAI
+SDK is an optional extra; if a provider needs an SDK that isn't installed, we
+raise a clear, actionable error instead of a raw ImportError traceback.
 """
 
 from __future__ import annotations
@@ -14,30 +17,49 @@
 
 
 class CredentialsError(RuntimeError):
-    """Raised when no usable model credentials are configured."""
+    """Raised when model credentials / config are missing or a provider is unknown."""
 
 
 def build_complete(config: dict) -> Complete:
     model_cfg = (config or {}).get("model", {}) or {}
     provider = model_cfg.get("provider", "anthropic")
     name = model_cfg.get("name")
+    base_url = model_cfg.get("base_url")
 
     if provider == "anthropic":
         return _anthropic_complete(name or "claude-sonnet-4-6")
     if provider == "openai":
         return _openai_complete(name or "gpt-4o")
-    raise CredentialsError(f"Unknown model provider '{provider}'.")
+    if provider in ("local", "openai-compatible"):
+        if not base_url:
+            raise CredentialsError(
+                "Provider 'local' needs `model.base_url` in .lore/config.yaml — point it at "
+                "any OpenAI-compatible endpoint (e.g. http://localhost:11434/v1 for Ollama, "
+                "or your LM Studio / vLLM server)."
+            )
+        return _openai_complete(name or "local-model", base_url=base_url)
+    raise CredentialsError(
+        f"Unknown model provider '{provider}'. Use 'anthropic', 'openai', or 'local' "
+        "(an OpenAI-compatible endpoint configured via `model.base_url`)."
+    )
 
 
 def _anthropic_complete(model: str) -> Complete:
     if not os.environ.get("ANTHROPIC_API_KEY"):
         raise CredentialsError(
-            "No ANTHROPIC_API_KEY set. Export an API key, or set model.provider to a "
-            "local provider in .lore/config.yaml. lore is BYO-key; nothing routes through us."
+            "No ANTHROPIC_API_KEY set. Export an API key, switch to `model.provider: openai` "
+            "(with OPENAI_API_KEY), or run a local model with `model.provider: local` + "
+            "`model.base_url` in .lore/config.yaml. crewlore is BYO-key; nothing routes through us."
         )
 
     def complete(prompt: str) -> str:
-        import anthropic
+        try:
+            import anthropic
+        except ImportError as exc:  # pragma: no cover - anthropic is a base dependency
+            raise CredentialsError(
+                "The Anthropic SDK isn't importable. Reinstall crewlore, or: "
+                "pip install 'anthropic>=0.39'."
+            ) from exc
 
         client = anthropic.Anthropic()
         msg = client.messages.create(
@@ -51,17 +73,32 @@ def complete(prompt: str) -> str:
     return complete
 
 
-def _openai_complete(model: str) -> Complete:
-    if not os.environ.get("OPENAI_API_KEY"):
+def _openai_complete(model: str, *, base_url: str | None = None) -> Complete:
+    local = base_url is not None
+    if not local and not os.environ.get("OPENAI_API_KEY"):
         raise CredentialsError(
-            "No OPENAI_API_KEY set. Export an API key, or set model.provider to a "
-            "local provider in .lore/config.yaml. lore is BYO-key; nothing routes through us."
+            "No OPENAI_API_KEY set. Export an API key, or run a local OpenAI-compatible model "
+            "by setting `model.provider: local` and `model.base_url` in .lore/config.yaml. "
+            "crewlore is BYO-key; nothing routes through us."
         )
 
     def complete(prompt: str) -> str:
-        import openai
-
-        client = openai.OpenAI()
+        try:
+            import openai
+        except ImportError as exc:
+            raise CredentialsError(
+                "The OpenAI SDK isn't installed (needed for the 'openai' and 'local' "
+                "providers). Install it with: pipx inject crewlore openai   "
+                "(or pip install 'crewlore[openai]')."
+            ) from exc
+
+        if base_url:
+            # Local OpenAI-compatible servers usually ignore the key, but the SDK requires one.
+            client = openai.OpenAI(
+                base_url=base_url, api_key=os.environ.get("OPENAI_API_KEY", "not-needed")
+            )
+        else:
+            client = openai.OpenAI()
         resp = client.chat.completions.create(
             model=model,
             temperature=0,  # deterministic — extraction is structured-output, not creative

src/lore/compile/pipeline.py

@@ -46,10 +46,18 @@ def compile_sessions(
     # genuinely-conflicting claims never group. Seed from prior claims, then grow.
     known_topics: set[str] = {c.topic for c in candidates if c.topic}
     for session_id, events in sessions.items():
-        if session_has_signal(events):  # C0 lever 3: skip trivial sessions
+        if not session_has_signal(events):  # C0 lever 3: skip trivial sessions
+            continue
+        try:
             extracted = extractor.extract(events, session_id, sorted(known_topics))
-            candidates.extend(extracted)
-            known_topics.update(c.topic for c in extracted if c.topic)
+        except Exception:
+            # One problematic session (oversized context, transient 429/500) must
+            # not abort the whole compile — skip it and continue. Nothing is cached
+            # on failure, so the next pass retries it. Mirrors ingest's defensive
+            # per-file posture.
+            continue
+        candidates.extend(extracted)
+        known_topics.update(c.topic for c in extracted if c.topic)
 
     claims = _dedup_and_score(candidates)
     conflicts = _detect_conflicts(claims)