feat: auth-aware source model resolution

[marcusrbrown]

Source category model defaults adapt to the user's authenticated providers. A user authenticated only to OpenAI gets OpenAI-backed agents; a user authenticated to Copilot and Anthropic gets a different selection from the same source defaults. No config required.

What changes

SOURCE_CATEGORY_MODEL_DEFAULTS becomes Record<CategoryId, readonly string[]> — an ordered preference list per agent category instead of a single string. At plugin config(cfg) time, Systematic reads OpenCode's auth.json and picks the first array entry whose provider is authenticated. Falls back to array[0] when no entry's provider is authenticated.

Category	Preference order
design	openai/gpt-5.5, anthropic/claude-opus-4.7
docs	openai/gpt-5.4-mini, anthropic/claude-haiku-4-5
document-review	anthropic/claude-opus-4.7, openai/gpt-5.5
research	openai/gpt-5.5, anthropic/claude-opus-4.7
review	anthropic/claude-opus-4.7, openai/gpt-5.5
workflow	openai/gpt-5.4-mini, anthropic/claude-haiku-4-5

User overlays (agents.<key>.model, categories.<id>.model) remain scalar strings — arrays are not accepted in user-supplied config in this iteration. User overlays still win over source defaults regardless of auth state.

Why this and not error-driven fallback

The published reference plugins (@cortexkit/opencode-magic-context, oh-my-opencode-slim, @kodrunhq/opencode-autopilot) all considered multi-model defaults and all settled for array[0] selection plus runtime error fallback. Brainstorm research established that OpenCode's plugin lifecycle does NOT expose a hook between config and chat.params where auth-aware mutation is possible — but a synchronous read of auth.json at config(cfg) time produces correct results for the explicit-credential case (API/OAuth/WellKnown providers), which is the common shape. This is the smallest mechanism that picks the right model the first time.

The arrays are a preference list, not a runtime fallback chain. Systematic still does not support fallback_models; runtime model failures are still surfaced by OpenCode.

Security boundaries

• The auth-file reader calls Object.keys() only — nested values (API keys, OAuth tokens) are never inspected, logged, persisted, or transmitted. This is enforced by a regression test that writes a known secret-shaped token into a fixture and asserts the literal substring does NOT appear in captured stderr/stdout AND that no [A-Za-z0-9_-]{30,} pattern appears.
• The plugin never writes to auth.json and never repairs/normalizes/migrates it. A regression test compares the file's mtime + sha256 before and after.
• Missing auth file is silently treated as "no providers authenticated." Unreadable or malformed files emit one stderr diagnostic naming the path and failure category — no file contents leaked.
• XDG_DATA_HOME is trusted as user-controlled; the resolver does not validate path containment.

Documented limitations

1. Autoload-true providers (e.g., AWS Bedrock loaded from environment variables) may not appear in auth.json and may be skipped by the resolver. Mitigation: pin via category or exact overlay.
2. Race window with opencode auth login — a partial write during plugin load collapses to malformed/empty-set behavior (safe). Restart OpenCode to refresh.

Both limitations are documented in the configuration docs.

Trace

5 commits, mapping cleanly to the plan units:

Commit	Unit	What
977f6c9	—	Plan doc
6f14d53	1	Source-default array shape + validator updates (+ 4 tests)
4b50475	2	getAuthenticatedProviders + auth-aware resolver (+ 15 tests)
4df3727	3	Wire resolver into config hook (+ 6 unit tests + 2 integration tests)
d41e345	4	README + configuration.mdx documentation

Verification

Check	Result
bun run typecheck	clean
bun run lint	clean (4 warnings, 14 infos — all pre-existing)
bun run build	clean
Node ESM smoke	dist/index.js default export is a function
content-integrity	clean (160 md + 16 ts scanned, 0 warnings)
registry:drift	up to date (101 components)
Unit tests	559 pass / 0 fail (was 534, +25)
Integration tests (config hook)	10 pass / 0 fail (was 8, +2)
Plan-taxonomy grep	0 hits in source/test files

Plan / Brainstorm

• Plan: docs/plans/2026-05-09-004-feat-auth-aware-source-model-resolution-plan.md (committed)
• Brainstorm: docs/brainstorms/2026-05-09-auth-aware-source-model-resolution-requirements.md (gitignored, local-only per project convention)
• Document review on the plan: 3 reviewers (coherence, feasibility, security-lens), 10 findings synthesized before commit. Confidence check passed without deepening — local patterns abundant, brainstorm research exhaustive.

Suggested release

Minor version bump (v2.11.0) — additive feature, fully backward compatible. Existing user configs continue to work unchanged.

[fro-bot]

Verdict: PASS

Clean, well-scoped additive feature with excellent test coverage and thoughtful security boundaries.

Blocking issues

None

Non-blocking concerns

1. isSystemError type assertion — agent-overlays.ts:738 uses as Record<string, unknown> to access .code after 'code' in err narrowing. Functionally correct, but a narrower cast (as { code: unknown }) or an intermediate variable would be marginally cleaner.

2. Nested-form provider test — agent-overlays.test.ts:797-805 tests provider extraction logic inline rather than exercising getSourceCategoryModel with an actual nested-form entry in a source-defaults array. The function logic is correct, but the test is more of a logic demonstration than an integration assertion.

3. XDG_DATA_HOME branch coverage — No unit test exercises the XDG_DATA_HOME → absolute path branch or the relative-path fallback in getAuthenticatedProviders. The os.homedir() fallback is covered by integration tests, but the XDG branch is not.

Missing tests

None blocking. The gaps noted above are minor and the existing coverage (25 new tests across unit + integration) is already strong.

Risk assessment (LOW) + rationale

• Regression likelihood: Low. The change is purely additive — existing single-string behavior is preserved as array[0] fallback. User overlays continue to win unconditionally.
• Security exposure: Very low. The auth-file reader is read-only, accesses Object.keys() exclusively, and has regression tests asserting no credential leakage via stderr/stdout or file mutation. The threat model is well-documented.
• Blast radius: Confined to source model default selection for bundled agents. No changes to skill loading, tool registration, or the bootstrap hook.

Additional notes

• All changed files pass lsp_diagnostics with zero errors.
• bun run typecheck clean.
• bun run lint clean (only pre-existing warnings).
• 132 tests pass across the affected test files.
• The plan document is exemplary — requirements trace, scope boundaries, security analysis, and risk matrix all present.

---

Run Summary

Field	Value
Event	pull_request
Repository	marcusrbrown/systematic
Run ID	25616312322
Cache	hit
Session	ses_1f08d7f50ffeXxQgdIl4z32bej

[marcusrbrown]

All 4 findings (1 from Code Scanning + 3 from Fro Bot) addressed in 7360359:

Code Scanning #41 — Potential file system race condition (tests/unit/agent-overlays.test.ts:861)

Fixed. The test's intent was "prove the file wasn't touched after a read-only operation," but the fs.readFileSync(authPath) after getAuthenticatedProviders(dir) was a redundant TOCTOU pattern. Replaced with mtime + size assertions only — a content-modifying write would change at least one. Removed the now-unused crypto import from this test.

Fro Bot NBC #1 — isSystemError type assertion

Fixed. Cast narrowed from Record<string, unknown> to { code: unknown }.

Fro Bot NBC #2 — Nested-form provider test

Fixed. The previous test demonstrated the algorithm inline but didn't exercise the function's slashIndex logic through the public API (because SOURCE_CATEGORY_MODEL_DEFAULTS has no nested-form entries). Replaced with a focused public-API test naming the contract: a provider/model string in authedProviders must NOT be treated as a provider id (otherwise substring contamination would cause false matches).

Fro Bot NBC #3 — XDG_DATA_HOME branch coverage

Fixed. Added 3 tests covering the resolution branches: absolute XDG_DATA_HOME is used directly; empty value falls back to os.homedir(); non-absolute value falls back to os.homedir(). Tests temporarily mock os.homedir and process.env.XDG_DATA_HOME and restore both in finally.

Verification post-fix: bun run typecheck clean, bun run lint clean (pre-existing warnings only), 562 unit tests pass (was 559, +3).

Plan units 1-4 are also now ticked as completed in docs/plans/2026-05-09-004-feat-auth-aware-source-model-resolution-plan.md and the plan status is flipped to completed.

[fro-bot]

Verdict: PASS

All prior review feedback has been addressed cleanly in 7360359.

Blocking issues

None

Non-blocking concerns

None. All three prior NBCs are resolved:

1. isSystemError type assertion — Cast narrowed from Record<string, unknown> to { code: unknown } (src/lib/agent-overlays.ts:737).
2. Nested-form provider test — Replaced inline logic demo with a focused public-API test proving that authedProviders entries are matched by prefix-before-slash only, preventing false matches from full provider/model strings.
3. XDG_DATA_HOME branch coverage — Added 3 tests covering absolute path usage, empty-string fallback, and non-absolute fallback.

Additionally, the Code Scanning TOCTOU finding in the file-mutation test was fixed by removing the post-call readFileSync and asserting on mtime + size only. The unused crypto import was also removed.

Missing tests

None

Risk assessment (LOW) + rationale

• Regression likelihood: Low. Purely additive; existing behavior preserved as array[0] fallback.
• Security exposure: Very low. Read-only Object.keys() access with no credential leakage.
• Blast radius: Confined to source model default selection for bundled agents.

Additional notes

• bun run typecheck clean.
• bun run build clean.
• bun run lint clean (pre-existing warnings only).
• 135 tests pass across affected files (62 unit agent-overlays + 73 config-handler/integration).
• Plan document units 1-4 ticked as completed, status flipped to completed.

---

Run Summary

Field	Value
Event	pull_request
Repository	marcusrbrown/systematic
Run ID	25616976756
Cache	hit
Session	ses_1f08d7f50ffeXxQgdIl4z32bej