fix(registry): resolve relative includes against the declaring bundle's base_path

[Sam Schillace (ramparte)]

Problem

BundleRegistry resolves relative bundle includes (includes: - bundle: ./base.md) against Path.cwd() captured once at registry-construction time — the CLI process's invocation directory — instead of against the including bundle file's own directory.

• registry.py:193-195 — SimpleSourceResolver(..., base_path=Path.cwd()), captured once, never re-derived per bundle
• sources/file.py:43-44 — any .//../ source resolves against that single base_path
• _compose_includes never consulted the declaring bundle's base_path, which the registry already tracks via bundle.base_path (set in _load_from_path) and already uses for namespace resolution

Reproduced with a bundle at <repo>/bundles/child.md including ./base.md:

cd <repo>/bundles && load child.md  -> session populated, 13 tools / 15 hooks / 11 agents
cd /tmp/anywhere  && load child.md  -> "Include Failed (skipping): File not found: /tmp/anywhere/base.md"
                                        session {}, 0 tools / 0 hooks / 0 agents

The second case does not raise. It yields a bundle that "loads successfully" but is empty, detonating much later and elsewhere as ValueError: Configuration must specify session.orchestrator — an error naming nothing related to the cause. This cost a real debugging session to track down.

What this does

Anchors relative include sources to the declaring bundle's base_path, following the precedent set by b667815 (PR #279), which fixed the identical class of bug for session/providers/tools/hooks source: fields.

New _anchor_relative_include_source(source, base_path) mirrors _resolve_relative_source's semantics exactly: only literal .//../ strings are rewritten to an absolute path; URIs, git+, file://, and already-resolved namespace refs pass through untouched; base_path=None falls back to current behavior.

Design note — why this is in registry.py and not sources/file.py. Threading a per-call base_path override down into SimpleSourceResolver.resolve() / FileSourceHandler.resolve() was considered and rejected for two reasons:

1. Concurrency. _compose_includes Phase 2 loads includes in parallel via asyncio.gather, and nested composition can run concurrently for sibling chains with different declaring bundles. A mutate-then-restore override on the shared handler would be a genuine race.
2. Cache-key ambiguity. _load_single caches bundles and detects cycles keyed on the literal URI string. If two bundles in different directories both declare ./base.md and resolution became context-dependent, the same cache key would ambiguously refer to two different files — a latent bug the global-cwd design never had (it was globally consistent, if globally wrong).

Resolving to an absolute path before the value reaches _load_single avoids both: the cache/cycle key becomes the fully-resolved absolute path, unambiguous regardless of declaring bundle or concurrency. Smaller change, confined to one file.

Diagnosability

All include warn/raise sites now name the including bundle and the base_path used, via a new _describe_including_bundle():

Include not found (skipping): ./base.md (included by child @ /tmp/.../bundles)

Open question for reviewers — deliberately NOT implemented

Strict mode already raises BundleDependencyError; non-strict (the CLI default) warns. This PR does not change that. But a failed include silently producing an empty bundle is precisely what made this hard to diagnose. A bounded improvement — raise if the root bundle ends up with an empty session after all includes are processed, regardless of strict mode — would close the gap without making every include failure fatal. That is a semantics decision, so it is flagged here rather than bundled in.

Testing

1549 -> 1559 passing, zero regressions. 10 new tests in tests/test_include_relative_to_declaring_bundle.py: cwd matching the bundle dir (guards existing behavior), cwd unrelated (the bug), nested C->B->A across four directories, ../ includes, missing-include message content, and five cases proving git+/file:///namespace/no-base_path sources are untouched.

The bug was verified to reproduce without the fix: stashing registry.py yields session {}, tools [], and the "Include Failed (skipping)" warning.

Lint/type: pyright identical to baseline. One new PIE810 ruff warning at the new helper — the exact same pattern that b667815's _resolve_relative_source already triggers on origin/main; mirrored the precedent's style rather than diverging.

Related

Sibling fix for module source: fields: #279.