Fix #196: SDK bootstrap honors TJ_CONFIG for config discovery

[anilmurty]

The Python SDK bootstrap ignored TJ_CONFIG, so a process pointing it at a project/custom config could silently initialize against the global config and write spans into the global DuckDB — a data-isolation hazard observed in an instrumentation pilot.

Summary

• load_config() now honors TJ_CONFIG (then the documented search-path order: tokenjam.toml → .tj/config.toml → ~/.config/tj/config.toml) when no explicit path is passed.
• Fixes the SDK bootstrap (ensure_initialised()) and, by living in the shared discovery function, the other bare load_config() SDK callers (nemoclaw, openai_agents_sdk, llamaindex) — same bug class.
• CLI behavior unchanged; explicit paths still win; out-of-scope litellm.py untouched.

Root cause

ensure_initialised() (reached by @watch() / any patch_*()) called load_config() with no path. The CLI resolves TJ_CONFIG via Click's envvar="TJ_CONFIG" and passes the path into load_config(path); the SDK path passed nothing, so find_config_file(None) fell straight through to the search paths and picked the global config.

Fix — in load_config(), not ensure_initialised()

if path is None:
    path = os.environ.get("TJ_CONFIG") or None
config_path = find_config_file(path)

I chose load_config() (the single discovery function the SDK and CLI share) over patching ensure_initialised():

• It keeps CLI and SDK consistent — the env var is honored in one place, not re-read separately in the SDK.
• It also fixes the other SDK integrations that call load_config() bare (nemoclaw / openai_agents_sdk / llamaindex), which had the identical leak.
• An explicit path argument still wins over the env var (so CLI --config beats TJ_CONFIG, via Click precedence → load_config(path) → env-read skipped).
• A TJ_CONFIG pointing at a missing file now raises FileNotFoundError instead of silently falling back to the global config — matching the CLI and closing the exact silent-fallback hazard.
• Bare find_config_file() CLI callers (onboard / doctor / budget / mcp) are deliberately untouched to keep the blast radius narrow.

Tests / Verification (tests/integration/test_sdk_config_discovery.py)

• load_config() honors TJ_CONFIG; an explicit path beats it; a missing TJ_CONFIG file raises.
• End-to-end SUBPROCESS test (@watch() with TJ_CONFIG set, run in a fresh process so the OTel global TracerProvider + bootstrap singleton start clean — the real "a process sets TJ_CONFIG" scenario, with PYTHONPATH pinned to this checkout): asserts spans land in the TJ_CONFIG-pointed DB and zero spans reach a decoy global DB.
• Confirmed the suite fails without the fix (3/4 fail; the intended DB is never created) and passes with it.
• Full suite: pytest tests/unit/ tests/synthetic/ tests/agents/ tests/integration/ → 827 passed. ruff check tokenjam/ + mypy tokenjam/core/config.py clean. CLI config tests (test_cli.py, test_config.py) unaffected.

What's NOT in this PR

• The LiteLLM integration ([bug] LiteLLM integration records provider as "litellm" → wrong pricing + NULL billing_account + suppressed dollars #194/[bug] LiteLLM integration captures no prompt/completion content or cache tokens #195) — litellm.py untouched (parallel agent owns it).
• Bare find_config_file() CLI callers — left as-is (the SDK fix doesn't need them, and changing them would alter onboard/doctor/budget/mcp discovery).
• No change to the search-path order or find_config_file() itself.

Closes #196

🤖 Generated with Claude Code

[anilmurty]

Verdict: ✅ APPROVE — ready to merge

Reviewed the diff independently. CI all 4 green (827 tests), MERGEABLE, tight scope (core/config.py + one integration test, 146/0).

Per-criterion (#196)

1. ensure_initialised() honors TJ_CONFIG — fixed at the root: load_config(path=None) now reads TJ_CONFIG before search-path discovery. This also fixes the other bare-load_config() SDK callers (nemoclaw / openai_agents_sdk / llamaindex) — same bug class, one place. Correct choice over patching just the one call site. ✅
2. Spans land in the intended DB — the subprocess end-to-end test (@watch() in a fresh process, clean OTel global + bootstrap singleton, decoy global DB, asserts zero spans reach it) is the right design for this, and the agent verified it fails without the fix (3/4) and passes with it. ✅

Verified the safety properties

• Explicit path wins — env is read only when path is None. No double-read; CLI (which passes the resolved path) is unaffected. Empty TJ_CONFIG → or None → discovery, handled.
• Missing TJ_CONFIG file now raises (via find_config_file's existing override check) instead of silently falling back to the global DB — this is the #196 hazard, and raising matches the CLI's --config behavior. Correct, intentional behavior change.
• No CLI regression — green CLI integration tests confirm; bare find_config_file() CLI callers (onboard/doctor/budget/mcp) correctly left untouched (narrowest blast radius; onboard's global-config behavior is intentional).

One note for release notes (not a blocker)

The "missing TJ_CONFIG → raise" is a (correct, minor) behavior change worth a one-line mention when this ships — anyone with a stale TJ_CONFIG pointing at a deleted file will now get a clear error instead of silent global fallback.

Ready to merge. Independent of #198 (different files), so it can land anytime.