# NexStream Agent Routing Notes — 2026-05-20

## What happened

A long Claude Code run on NexStream successfully completed launch/playback/subtitle work, then stopped twice:

1. `API Error: Output blocked by content filtering policy` while working near debrid/addon/source areas.
2. `You've hit your session limit · resets 1am (America/Los_Angeles)` on a later safe-phase run.

The code changes left by Claude were still compile-safe; always verify with Gradle before assuming a stopped agent left broken code.

## Recommended routing for NexStream

Use a phase split rather than feeding the full 2-day master prompt to one agent:

### Claude Code: safe/product phases
- Launch/navigation blockers
- Player diagnostics overlay
- External subtitles and player controls
- TV UI polish
- Search/profile/settings UX
- Performance/compliance docs
- Final handoff docs

### Codex GPT-5.5 via Hermes/current model: risky/domain phases
- SourceRanker reliability/source health work
- Addon health/control safety
- Debrid provider abstraction
- Security/privacy audit around tokens/addons/diagnostics
- Any implementation likely to include sensitive debrid/addon/source terminology

Important: if the session model has been switched to OpenAI Codex/GPT-5.5 inside Hermes, do not install or invoke the Codex CLI just to use Codex. Work directly with Hermes tools under the current model.

### OpenCode GLM 5.1: remaining safe backlog or fallback
- After Codex quota/model time is exhausted, hand remaining safe work to `opencode run ... --model opencode-go/glm-5.1`.
- Prefer a concise handoff file under `/tmp/` listing completed work, constraints, remaining phases, and finish criteria.
- Use prompt-first then `-f file` ordering: `opencode run "execute handoff" --model opencode-go/glm-5.1 -f /tmp/handoff.md`.
- Watch delegated runs actively. If an `opencode run` repo-edit task has zero stdout and no source-file mtime changes for ~30 minutes, treat it as a stalled delegation: kill it, verify Gradle, and either relaunch with a much narrower chunk or do the small remaining work directly. The durable lesson is the watchdog pattern, not that GLM/OpenCode is broken.

## 2026-05-20 follow-up: split + direct completion pattern

After Claude stopped, the risky phases were completed directly under Hermes after the model was switched to GPT-5.5/Codex, without invoking the Codex CLI. The safe remainder was attempted through OpenCode GLM 5.1; large and then narrow repo-edit tasks produced no output and no file changes, so they were killed and verified clean.

Useful artifacts produced in the follow-up pass:
- `data/source/SourceRanker.kt`: reliability-first scoring, labels, rank breakdown, codec compatibility, low-quality-source penalties, and success/failure history.
- `test/.../SourceRankerTest.kt`: focused tests for cached/reliable ranking, low-quality penalties, history, and file-size preference.
- `data/addon/AddonHealthMonitor.kt`: rolling `successRate`, `timeoutCount`, `disabledBySystem`, and live health scores.
- `data/debrid/DebridProviderAdapter.kt`: provider-neutral scaffold for auth/refresh/availability/resolve operations.
- `docs/SECURITY_PRIVACY_AUDIT.md`, `docs/ANDROID_TV_COMPLIANCE.md`, `docs/CLAUDE_CODE_FINAL_HANDOFF.md`: final audit/compliance/handoff docs.
- `SettingsSubtitlesScreen.kt` + `PlayerViewModel.kt`: global default subtitle sync offset wired into player subtitle delay fallback.

When taking over from stalled delegated agents, keep the direct pass narrow: pick one low-risk user-visible improvement plus missing docs, then run `compileDebugKotlin testDebugUnitTest assembleDebug` before reporting.

## Verification pattern after any external agent stops

Run:

```bash
cd ~/nexstream
./gradlew compileDebugKotlin
./gradlew testDebugUnitTest
./gradlew assembleDebug
```

Then inspect:

```bash
git status --short | grep -v '^ M .gradle/' | grep -v '^ M app/build/'
```

Treat generated Gradle/build/KSP changes as noise unless source/schema files changed.

## Do not preserve as permanent claims

Do not write a permanent rule that Claude Code “cannot work on NexStream” or that Codex CLI is unavailable. The durable lesson is the routing and verification pattern, not a one-off environment/setup failure.