# SkillForge — Project Journal

## Entry #7: Managed Agents Port — Phase 1

**Date**: April 9, 2026 (continuing from Entry #6's late-night planning session)  
**Session Duration**: ~5 hours of autonomous work  
**Participants**: Matt (briefed, then stepped away) + Claude Code (Opus 4.6, 1M context)

---

### The Starting Point

Entry #6 closed with `PLAN-V1.2.md` locked: a full file-by-file plan to port the Competitor agent from `claude-agent-sdk` (local subprocess) to Anthropic Managed Agents (cloud sessions), with the Advisor Strategy bolted in as architectural decision #9 and a phased ship strategy that defaults the new backend OFF behind a `SKILLFORGE_COMPETITOR_BACKEND` env flag.

Matt's framing for this session: "do your full QA, I'll step away." He asked what blockers I needed answered first. Five answers came back:

1. ~$4 live API spend cap — yes
2. Stop before Phase 2 (no Railway env flip, no A/B matrix) — yes
3. The 4 pre-existing custom skills in the org are Anthropic built-ins (xlsx/pptx/pdf/docx) — never touch them
4. Commit per logical unit but don't push (he'll draft a PR for each phase)
5. Single journal entry at the end of the chunk — yes

Then he was gone.

---

### Phase 1: Burning Down the Pre-Existing Test Debt

Before any port work, I ran `uv run pytest -q` and the baseline came back **red — 11 failing tests** in `test_judge_trigger.py`, `test_judge_comparative.py`, `test_judge_attribution.py`, and `test_judge_trace.py`. PROGRESS.md documented this as known follow-up debt: Entry #6's streaming conversion swapped `messages.create()` → `stream_text()` across all judge layers but the mock-based tests still patched `messages.create` directly, so the assertions were never reached.

The fix was mechanical. For each of the four files I:
- Removed the `_mock_anthropic_response` helpers (no longer needed)
- Replaced `@patch("skillforge.agents.judge.<layer>.AsyncAnthropic")` with `@patch("skillforge.agents.judge.<layer>.stream_text", new_callable=AsyncMock, return_value="...")`
- Updated the "uses configured model" assertions to read `mock_stream.call_args.kwargs["model"]` instead of `mock_client.messages.create.call_args.kwargs.get("model")`
- Preserved every pure deterministic helper test (like `_extract_description`, `_classify_instruction_adherence`) verbatim

The "passing" tests in those files were technically passing for the wrong reasons — their assertions happened to match the silent fallback behavior when the mock didn't intercept. Rewriting them as part of the same pass meant strict improvement, not just bug fix.

184/184 green when done. Committed as `a872c57`.

---

### Phase 2: PLAN-V1.1 Carry-Over Backfill

Four items from the locked PLAN-V1.1 testing strategy that never landed during the v1.1 batch:

**`tests/test_seeds.py`** (16 tests). Covers `seed_loader.load_seeds()` insert/skip/reload paths via mocked `get_run` + `save_run`, `_content_hash` determinism + sensitivity to mutations, `_build_genome` shape (must produce `maturity="hardened"`), `spawner.spawn_from_parent` with `pop_size=1` (elite-only short-circuit, no LLM call), `pop_size=3` happy path with mocked `_generate`, fallback-to-elite on garbage LLM, `pop_size<1` ValueError, validator-filtered mutants. Plus the integration tests for `POST /api/evolve/from-parent` with `parent_source="registry"` (happy path, 404 on unknown skill, 404 when seed-library missing) and the bad `parent_source` 400.

I had to dig into the shipped code to write tests against the **actual** behavior, not the original PLAN-V1.1 spec. The deliberate divergences from entry #5/#6 — `PENDING_PARENTS` in-memory dict instead of a `seed_skill_id` column, in-memory uploads instead of `/tmp/skillforge-uploads/`, 16 seeds instead of 15 — meant the tests had to assert what the code does today, not what the plan thought we'd build. Documented this as the "Architectural note" in PLAN-V1.2's carry-over section so future contributors don't get confused.

**`tests/test_uploads.py`** (20 tests). Every validation rule in the upload endpoint: happy paths (`.md`, `.zip` at root, `.zip` one directory deep), size caps (1 MB upload, 5 MB unpacked, 100 file count), zip bomb (compression ratio >20:1), path traversal (`..` and absolute), the disallowed-extension allowlist behavior (which is **silently dropped**, not rejected — a divergence from PLAN-V1.1 §2.2 that I documented as a follow-up question), bad upload format, malformed zip, zip without SKILL.md, structural validation failure surfacing in the response body, the `get_upload`/`clear_upload` helpers, and the upload → fork integration round-trip via `_UPLOADS` and `PENDING_PARENTS`.

One of my fixtures had a "bad" SKILL.md whose description text accidentally contained the substring "use when correctly" — which the validator's case-insensitive check accepted as a valid pushy pattern. Test failed; I caught my own bug; rewrote the fixture to not contain that substring. 20/20 green on the second pass.

**`frontend/src/hooks/useTheme.test.ts`** (12 tests). The hook needed a DOM environment (`document.cookie`, `matchMedia`, `document.documentElement.dataset.theme`) so I added two devDependencies to the frontend: `jsdom@^25` and `@testing-library/react@^16`. To minimize blast radius I used a per-file `// @vitest-environment jsdom` docblock so the existing `derivePhases.test.ts` stays in the default node env (no global vitest config change). Verified `npm ci` reproduces the new lockfile cleanly to avoid a Linux-build regression like the vitest 4 incident from Entry #6.

The hook tests cover: default to `"system"` when no cookie, resolve `system → dark` via `prefers-color-scheme`, persisted dark/light cookie reads, `setTheme` writes cookie + flips `document.documentElement.dataset.theme`, `setTheme("system")` re-resolves via matchMedia, media-query change events flip the resolved theme when state is system, the listener subscription gating (no listener when state is explicit), cookie round-trip across renders, and dataset.theme applied on mount.

**Hex grep sweep** (PLAN-V1.1 §Testing strategy §3): zero hex literals in `frontend/src/**/*.tsx` or `**/*.ts`, zero in `tailwind.config.js`, all 25 legitimate hex values living only in `frontend/src/index.css` (the CSS variable definitions). The Anthropic palette migration from Entry #5 was airtight — nothing slipped through.

220/220 backend + 24/24 frontend when this commit landed (`3f2130a`).

---

### Phase 3: Step 0 — Empirical Probes Against the Live Beta APIs

PLAN-V1.2 Step 0 exists because the doc review only got us so far — five real unknowns about the Managed Agents + Skills + Advisor APIs needed empirical answers before any code committed.

The script (`scripts/smoke_skill_upload.py`) does four probes:

1. **Serial 20 skill uploads** — to find the rate-limit ceiling
2. **Parallel 10 skill uploads** — to test concurrent burst behavior
3. **Session event shape probe** — create env + agent + session, send a message asking the agent to write a 10 KB file, inspect the resulting events
4. **Advisor `advisor_20260301` tool probe** — try to create an agent with the advisor tool, capture the failure mode if any

I had to iterate on the SDK call shapes a few times. The first attempt used `extra_headers` for beta strings; the SDK actually wants a `betas: List[str]` kwarg. The first skill upload failed with `400 SKILL.md file must be exactly in the top-level folder.` — turns out a bare `SKILL.md` filename isn't allowed; the file has to live inside a top-level folder. The first skill delete failed with `Cannot delete skill with existing versions. Delete all versions first.` — the SDK's `beta.skills.delete()` does NOT auto-clean versions, so I had to implement the 3-step dance: `versions.list` → `versions.delete(version=str)` per version → `skills.delete`.

Then the **biggest surprise** of Step 0: `beta.sessions.events.stream()` is structurally unusable for Managed Agents. The SDK wraps it in the standard `AsyncStream` which only recognizes Anthropic Messages API SSE event names (`message_start`, `content_block_delta`, etc.) and silently drops every Managed Agents event type. The stream then errors with `httpx.RemoteProtocolError: incomplete chunked read`. The fix: poll `beta.sessions.events.list(order="asc")` every 2 seconds and dedupe by event id. That endpoint returns structured `BetaManagedAgentsSessionEvent` objects directly. This single finding rewrote a meaningful chunk of `competitor_managed.py` before I'd written it.

**Findings, all empirical, all locked into `plans/PLAN-V1.2.md` as a new "Step 0 empirical findings" section**:

- **Skill uploads: GREEN.** 20/20 serial in 82.4s (avg 4s per call, two outliers at 19.9s and 23.5s, no 429s) + 10/10 parallel in 1.9s (~5x faster). Default `SKILLFORGE_MANAGED_AGENTS_SKILL_MODE=upload` is safe — rate limits don't gate Phase 1.
- **3-step delete dance: REQUIRED.** Confirmed via direct SDK calls. All 30 test skills cleaned cleanly.
- **Event shape probe: GREEN.** 9 distinct event types observed: `user.message`, `session.status_running`, `span.model_request_start`, `agent.thinking`, `span.model_request_end`, `agent.tool_use`, `agent.tool_result`, `agent.message`, `session.status_idle`. Token usage path confirmed: `event.model_usage.{input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens}`. Sample probe ran 11.076s = $0.000246 in session-runtime cost.
- **Tool inventory: ONE IMPORTANT RENAME.** The actual tool names in `agent_toolset_20260401` are `bash`, `edit`, `read`, **`write`** (NOT `write_file` as PLAN-V1.2 originally assumed), `glob`, `grep`, `web_fetch`, `web_search`. I ran a supplemental probe explicitly asking the agent to use the `write` tool and confirmed the input shape is `{"file_path": str, "content": str}` with the FULL content (not a preview).
- **Advisor Strategy: 🔴 RED — NOT AVAILABLE.** The `advisor_20260301` tool type is rejected by both SDK 0.92 (the Tool union only contains `BetaManagedAgentsAgentToolset20260401Params`, `BetaManagedAgentsMCPToolsetParams`, `BetaManagedAgentsCustomToolParams`) AND the API itself: `400 tools[1].type: "advisor_20260301" is not a valid value; expected one of agent_toolset_20260401, custom, mcp_toolset`. Tested with both `managed-agents-2026-04-01` alone and combined with `advisor-2026-03-01`. Hard descope from Phase 1.

Total Step 0 spend: well under $0.20.

The plan was rewritten inline with all the corrections — `write_file` → `write`, the polling pattern, the 3-step dance, the descope of the Advisor Strategy — and committed alongside the smoke script + raw output (`5a8f364`).

---

### Phase 4: Building Phase 1 — managed_agents.py + competitor_managed.py + Dispatcher

With the empirical surface area locked, the actual port was straightforward. Three new files:

**`skillforge/agents/managed_agents.py`** (~430 lines). The thin typed wrapper around `anthropic.beta.{agents,skills,sessions,environments}`. Functions: `make_client`, `create_environment`, `archive_environment`, `upload_skill`, `archive_skill` (with the 3-step dance + Anthropic-built-in guard), `archive_skill_safe` (swallow-and-log variant), `create_competitor_agent`, `archive_agent`, `create_session`, `archive_session`, `send_user_message`, and the centerpiece `iter_session_events` that polls + dedupes. Pure helpers: `extract_written_files` (walks `agent.tool_use` events for `write` and `bash`, parses bash heredocs/redirects), `compute_token_usage` (sums `span.model_request_end`), `compute_session_runtime_hours` (timestamps the running→idle delta), `session_was_skill_loaded` (heuristic based on tool_use after status_running). Beta header constants pinned as module-level: `MANAGED_AGENTS_BETA = "managed-agents-2026-04-01"`, `SKILLS_BETA = "skills-2025-10-02"`. The `archive_skill` function refuses to even attempt deletion of `source="anthropic"` skills.

**`skillforge/agents/competitor_managed.py`** (~370 lines). The new competitor implementation. The interesting design choices:

- **Trace conversion.** Managed Agents events are flat per-event objects but L3's `_classify_instruction_adherence` expects messages with `content: list[dict]` blocks. So `_convert_event_to_trace_entry` wraps each `agent.tool_use` event into an L3-shaped `{"role": "assistant", "type": "AssistantMessage", "content": [{"type": "tool_use", "name": canonical, "input": ...}]}`. Tool name canonicalization: `bash` → `Bash`, `write` → `Write`, etc. — matches the SDK convention so L3's `_extract_behavioral_signature` and `_extract_scripts_executed` keep working unchanged.

- **Synthetic Skill marker.** L3's `_detect_skill_loaded` looks for any `tool_use` block named `Skill`. Managed Agents doesn't emit such a block — the skill is auto-loaded into the agent's context — but the L3 contract still expects to see it. So when `skill_attached=True`, `_build_trace` injects a synthetic `{"role": "assistant", ..., "content": [{"type": "tool_use", "name": "Skill", "input": {"_synthetic": True}}]}` at the start of the trace. Documented as a Phase 1 compatibility shim; revisit when Anthropic ships a `skill_load` event.

- **User message construction.** `_build_user_message` inlines the challenge setup files as bash heredocs that the agent should write to disk before solving. Managed Agents has no documented file-upload-to-session API, so this is the workaround. Optionally inlines the SKILL.md body itself when running in `inline` mode (the upload-failure fallback).

- **Cost breakdown math.** Multiplies token totals by per-model rates from `MODEL_PRICE_PER_MTOK_INPUT/OUTPUT` (cache creation × 1.25, cache read × 0.1) and adds `runtime_hours × $0.08`. Returns a dict with `executor_input_usd`, `executor_output_usd`, `advisor_input_usd` (zero in Phase 1, forward-compat), `advisor_output_usd` (zero), `session_runtime_usd`, raw token counts, `n_model_requests`, `session_runtime_hours`, `backend: "managed"`, `advisor_enabled: bool`.

- **Cleanup is detached.** Per architectural decision #7, `archive_session`, `archive_agent`, and `archive_skill_safe` are scheduled as `asyncio.create_task()` in the `finally` block. They never block the evolution loop. Failures land in the `leaked_skills` table.

**`skillforge/agents/competitor.py`** (now a thin dispatcher, ~30 lines). Routes `run_competitor` to `competitor_sdk` or `competitor_managed` based on `COMPETITOR_BACKEND`. The original SDK file was renamed to `competitor_sdk.py` via `git mv` so history was preserved. Phase 3 will delete the SDK module and the dispatcher together.

**Engine edits.** `engine/evolution.py` learned to branch on `COMPETITOR_BACKEND`. In managed mode, it creates one cloud environment per run via `managed_agents.create_environment` at the top of `run_evolution`, threads the env id through `_gated_competitor → _run_one_competitor → run_competitor`, and tears the environment down in a `finally` clause. The SDK path is unchanged.

**Config additions.** New flags in `skillforge/config.py`:
- `COMPETITOR_BACKEND` (default `"sdk"`)
- `MANAGED_AGENTS_SKILL_MODE` (default `"upload"`, fallback `"inline"`)
- `MANAGED_AGENTS_SESSION_RUNTIME_USD_PER_HOUR` ($0.08 const)
- `COMPETITOR_ADVISOR` (default `False` since the advisor is descoped)
- `COMPETITOR_ADVISOR_MAX_USES` (default 3, no-op until advisor lands)
- `competitor_advisor` model role registered in `MODEL_DEFAULTS` as `claude-opus-4-6` (forward-compat no-op)
- `COMPETITOR_CONCURRENCY` default became backend-aware: 1 under sdk, 5 under managed

**DB additions.** New `leaked_skills` table (`id, skill_id, run_id, created_at, error`), CRUD helpers `log_leaked_skill` (best-effort, swallows errors), `list_leaked_skills`, `delete_leaked_skill`. SCHEMA.md updated with the table definition + a note that built-in skills are protected from this path.

**Model addition.** `CompetitionResult.cost_breakdown: dict` field with serde round-trip support.

After all this landed, the SDK path was completely unchanged behaviorally — `tests/test_competitor.py`'s 14 SDK-path tests still pass against `competitor_sdk.run_competitor`. I migrated the test imports from `skillforge.agents.competitor` (now the dispatcher) to `skillforge.agents.competitor_sdk` so they're focused on the SDK path regardless of the backend flag.

---

### Phase 5: Tests for the New Surface Area

Three new test files (66 new tests):

**`tests/test_config.py`** (24 tests) — the model swap ergonomics tripwire from PLAN-V1.2 §"Model swap ergonomics". Enumerates `MODEL_DEFAULTS` and parameterizes `test_every_role_overridable_via_env(role)` over every role. If anyone adds a new role and forgets to wire it through `model_for()`, this test catches the regression. Plus sanity tests for the Phase 1 flag defaults, the $0.08 session runtime constant (so a typo fails loudly), and the backend-aware `COMPETITOR_CONCURRENCY` default via `importlib.reload(cfg)`.

**`tests/test_managed_agents.py`** (40 tests) — wrapper unit tests. Pure-function tests for `extract_written_files` (write tool happy path, multiple distinct files, last-write-wins, bash heredoc cat, bash heredoc tee, bash echo redirect, mixed write+bash, ignores non-tool-use events, ignores unknown tool names, missing input field, **path normalization** — see Phase 6), `compute_token_usage` (sums across multiple events, zero on empty, ignores other event types, missing model_usage), `compute_session_runtime_hours` (basic, missing running, missing idle, negative delta, multiple running events), `session_was_skill_loaded` (with/without skill_id, before/after status_running). Mocked SDK lifecycle tests for `upload_skill` (folder name from frontmatter), `archive_skill` (3-step dance, refuses Anthropic built-ins), `archive_skill_safe` (returns tuple, swallows errors), `create_competitor_agent` (skill_id field shape, omits skills field when no skill_id), `send_user_message` (event shape), `iter_session_events` (dedupes by id, stops on idle, respects deadline).

**`tests/test_competitor_managed.py`** (10 tests) — integration tests for the higher-level competitor flow with the managed_agents wrapper mocked. Happy path with cost_breakdown math verification (`executor_input_usd = input_tokens × 3.0 / 1M = 0.003` for a Sonnet 1000-token input), inline mode (no upload, content inlined, no synthetic Skill marker), upload failure → fallback to inline, empty event stream, polling error captured in `judge_reasoning`, `_build_user_message` setup file inclusion, tool name canonicalization, status events return None.

286/286 backend green when this commit landed. Plus 24/24 frontend.

---

### Phase 6: The Live End-to-End Smoke Gauntlet

PLAN-V1.2 §Verification §6: spin up `SKILLFORGE_COMPETITOR_BACKEND=managed` locally and run a minimal evolution end-to-end against the live API. This is where reality bit back.

I wrote `scripts/smoke_managed_e2e.py` — a standalone harness that exercises `run_evolution` directly (bypasses the FastAPI layer, which is just plumbing) with a 2 pop × 1 gen run on a Python-utility-functions specialization (matching the Challenge Designer's known bias from Entry #6). The script prints per-competitor `cost_breakdown`, the L3 trace inspection, and the `leaked_skills` table contents.

**First live run**: failed instantly. The skill upload returned `400 The folder name 'sf-uuid-abc' must match the skill name 'python-list-string-utils' in SKILL.md.` My code was using a truncated SkillForge UUID as the folder name, but the SKILL.md inside has a different `name:` field set by the Spawner. The Anthropic API requires them to match exactly.

The fix went into `managed_agents.upload_skill`: extract the real name from the SKILL.md frontmatter via regex and use **that** as the folder name. The function's `name` argument is still used as the `display_title` (which is free-form). Added unit tests for the extraction helper.

After fixing that, all 6 competitors fell back to inline mode (because every upload still failed for the second reason below), but the engine still tried to run them... and **L1 crashed** with `OSError: [Errno 30] Read-only file system: '/output'`. Why? The Sonnet agent in the cloud sandbox had been writing to absolute paths like `/output/solution.py`. My `extract_written_files` returned the path verbatim. When L1's `_check_compiles` did `Path(tmp_dir) / '/output/solution.py'`, Python's `Path` semantics said "the absolute path wins" → it tried to mkdir `/output` on the local filesystem, which is read-only on macOS without sudo.

The fix went into `managed_agents._normalize_output_path`: strip leading slashes (and `./` prefixes, and whitespace) so every path returned is relative. Belt-and-suspenders against accidental path traversal too. Updated all the existing `extract_written_files` tests to expect normalized output. Six new tests just for the normalizer to lock down the contract.

**Second live run**: now the skill upload was working but **agent creation** was failing for 5/6 competitors with `400 skills[0].type: "skill" is not a valid value; expected one of "anthropic", "custom"`. I'd been passing `{"id": skill_id, "type": "skill"}` to the agent's `skills` field. The API wants `type: "custom"`. Easy fix.

**Third live run**: now `400 skills.0.id: Extra inputs are not permitted`. I'd corrected the type but not the field name. Reading the SDK source (`anthropic.types.beta.beta_managed_agents_custom_skill_params.BetaManagedAgentsCustomSkillParams`) revealed the actual shape: `{"skill_id": str, "type": "custom", "version": Optional[str]}`. The field is `skill_id`, NOT `id`. Two contract bugs from one commit, both invisible behind the SDK's permissive Python typing.

I also caught a related issue in the same iteration: the original code used `name=f"sf-{skill.id[:24]}"` for both the upload folder name AND the display title. With the folder-name fix, the display title was still `sf-...uuid...`, and uploading the SAME skill twice in a generation (once per challenge) collided: `400 Skill cannot reuse an existing display_title: sf-...`. Made the display title unique per (skill, challenge) pair: `f"sf-{skill.id[:8]}-{challenge.id[:8]}"`. Documented in a code comment that v1.3 should cache uploaded skill_ids at the run level for efficiency.

**Fourth live run**: 🟢 **fully green**. All 6 competitors ran on the managed backend, all wrote `output/solution.py`, all compile, the `leaked_skills` table is empty, and the trace is populated:

```
trace length: 11
skill_was_loaded: True
behavioral_signature: ['Skill', 'Read', 'Bash', 'Write', 'Bash']
cost_breakdown[0]: {
  "executor_input_usd": 0.035785,
  "executor_output_usd": 0.01305,
  "advisor_input_usd": 0.0,
  "advisor_output_usd": 0.0,
  "session_runtime_usd": 0.000659,
  "input_tokens": 90,
  "output_tokens": 870,
  "cache_creation_input_tokens": 7356,
  "cache_read_input_tokens": 26433,
  "n_model_requests": 5,
  "session_runtime_hours": 0.008235,
  "backend": "managed",
  "advisor_enabled": false
}
```

Per-competitor cost ~$0.05, **way cheaper than the SDK path's ~$0.30** because the cloud sandbox is hitting prompt cache (26K cache_read tokens vs 90 fresh input tokens). Total run cost: **$1.6950** for 2×1×3 = 6 competitors. Wall time: 640s = 10.6 minutes (a hair slower than the SDK path's 9 minutes for 2×1×1 because the Challenge Designer + Spawner are still serial — but with 3× more competitors).

The synthetic Skill marker works. The tool name canonicalization works. The polling-instead-of-streaming works. The 3-step delete dance works for cleanup. The cost_breakdown math matches Anthropic's published rates. The behavioral_signature shows the agent loaded the skill, read context, ran bash, wrote the solution, and ran bash again to verify. Phase 1 is real.

Total live spend across all four iterations: ~$2.05. Still well under the $4 cap.

---

### Phase 7: QA Gate + Pricing Relocation

After the live smoke went green, I ran the full QA gate:

- `uv run pytest -q` → 294 passed, 1 skipped (the live test, gated)
- `uv run ruff check skillforge/ tests/ scripts/` (Phase 1 scope) → clean
- Frontend `npm run test` → 24 passed
- Import graph: `from skillforge import main, config, models, db, engine, agents` plus every submodule → clean
- `init_db` round-trip: fresh DB creates all 7 tables including the new `leaked_skills`
- `bypassPermissions` grep: only one match, in a docstring negative reference ("never bypassPermissions — that's a trap"), safe

But the model-string grep caught one violation: the per-model pricing table I'd put in `competitor_managed.py` had `"claude-sonnet-4-6"`, `"claude-haiku-4-5-20251001"`, `"claude-opus-4-6"` as dict keys. Those are technically lookup keys (not model selections), but cross-cutting contract #2 says "no hardcoded model strings outside config.py" and the contract is grep-friendly. Cleanest fix: relocate the pricing tables (`MODEL_PRICE_PER_MTOK_INPUT`, `MODEL_PRICE_PER_MTOK_OUTPUT`, `MODEL_CACHE_CREATE_MULTIPLIER`, `MODEL_CACHE_READ_MULTIPLIER`) into `config.py` next to `MANAGED_AGENTS_SESSION_RUNTIME_USD_PER_HOUR`. `competitor_managed._model_token_cost` imports them. Same numbers, same math, same tests still pass — just relocated. Committed as `b9d7d8c`.

There are 3 pre-existing ruff errors in `skillforge/api/uploads.py` (B008 + 2× B904) that predate Phase 1. They're documented technical debt, not in scope for Phase 1, and I deliberately left them alone.

Pre-existing 3 uploads.py errors aside, the QA gate is fully green for everything I touched.

---

### Artifacts Produced

| Artifact | Lines | Purpose |
|---|---|---|
| `tests/test_judge_trigger.py` (rewrite) | ~230 | 12 tests, mock `stream_text` instead of `messages.create` |
| `tests/test_judge_comparative.py` (rewrite) | ~330 | 14 tests, same fix |
| `tests/test_judge_attribution.py` (rewrite) | ~370 | 12 tests, same fix + capture mode for prompt content |
| `tests/test_judge_trace.py` (rewrite) | ~250 | 12 tests, same fix; deterministic helpers preserved verbatim |
| `tests/test_seeds.py` (new) | ~430 | 16 tests for seed loader + spawn_from_parent + fork-from-parent endpoint |
| `tests/test_uploads.py` (new) | ~510 | 20 tests for upload validation + upload→evolve integration |
| `frontend/src/hooks/useTheme.test.ts` (new) | ~210 | 12 tests for the theme hook via jsdom + @testing-library/react |
| `frontend/package.json` + `package-lock.json` (edit) | +66 deps | jsdom@^25 + @testing-library/react@^16 devDependencies |
| `scripts/smoke_skill_upload.py` (new) | ~440 | Step 0 smoke test — uploads, session events, advisor probe |
| `journal/data/007-step0-smoke-{burst,session}.txt` | 241 | Raw output from Step 0 |
| `plans/PLAN-V1.2.md` (edit) | +73 | Step 0 empirical findings section + plan corrections |
| `skillforge/agents/managed_agents.py` (new) | ~480 | Thin typed wrapper around beta.{agents,skills,sessions,environments} |
| `skillforge/agents/competitor_sdk.py` (renamed from competitor.py) | unchanged | The original SDK path, untouched |
| `skillforge/agents/competitor.py` (new dispatcher) | ~30 | Routes between sdk/managed backends via env flag |
| `skillforge/agents/competitor_managed.py` (new) | ~410 | The Managed Agents implementation |
| `skillforge/config.py` (edit) | +70 | New flags + pricing tables + competitor_advisor role |
| `skillforge/db/database.py` (edit) | +18 | leaked_skills table + index |
| `skillforge/db/queries.py` (edit) | +85 | log_leaked_skill / list_leaked_skills / delete_leaked_skill |
| `skillforge/models/competition.py` (edit) | +18 | cost_breakdown dict field with serde |
| `skillforge/engine/evolution.py` (edit) | +60 | Branch on COMPETITOR_BACKEND, env lifecycle |
| `tests/test_competitor.py` (edit) | 6 lines | Migrate import to competitor_sdk |
| `tests/test_config.py` (new) | ~190 | 24 tests — model swap tripwire + Phase 1 flag defaults |
| `tests/test_managed_agents.py` (new) | ~570 | 40 tests for the wrapper (parsers + lifecycle mocks) |
| `tests/test_competitor_managed.py` (new) | ~390 | 10 tests for the higher-level competitor flow |
| `SCHEMA.md` (edit) | +20 | leaked_skills table documentation |
| `scripts/smoke_managed_e2e.py` (new) | ~165 | End-to-end smoke harness with cost_breakdown inspection |
| `journal/data/007-step1-e2e-final-pass.txt` | 59 | Raw output from the green run |
| `journal/007-managed-agents-port-phase-1.md` (this entry) | — | — |

---

### Key Decisions Summary

| Decision | Rationale |
|---|---|
| Fix the 11 red judge tests before any port work | Baseline must be green to honestly claim "full QA passes" on Phase 1. Mechanical fix, no scope creep |
| `// @vitest-environment jsdom` per-file docblock instead of global vitest config change | Keeps `derivePhases.test.ts` in fast node env. Smallest possible blast radius for the dev-dep additions |
| Step 0 smoke commits its script + raw output to `journal/data/` | Reproducibility. PLAN-V1.2 originally said "not committed" but the script is small and reading the raw API call shapes from a committed file is more useful than re-running the probes |
| Advisor Strategy hard descope from Phase 1 | Empirical: SDK 0.92 doesn't expose the type, API rejects it. Wiring stays as forward-compat zeros so the day Anthropic ships it we flip an env var, not write code |
| `events.list` polling instead of `events.stream` | The SDK's stream wrapper is structurally broken for Managed Agents. This isn't a workaround — it's the only viable path until Anthropic ships a Managed-Agents-aware stream decoder |
| Synthetic `Skill` marker injected into the trace when `skill_attached=True` | L3's `_detect_skill_loaded` heuristic works against the SDK convention. Anthropic doesn't yet emit a `skill_load` event. Documented as a Phase 1 compat shim, revisit when the event lands |
| Tool name canonicalization (`bash` → `Bash`) at the trace boundary | Lets L3's existing extractors work unchanged. The alternative (modifying L3) would touch shipped behavior |
| Per-(skill, challenge) skill upload + display_title instead of caching | Simpler. Uploads are free + fast (~2s parallel per Step 0). v1.3 follow-up to cache at the run level for efficiency |
| Cleanup as detached `asyncio.create_task()` in `finally` | Per architectural decision #7. Cleanup must NEVER block the evolution loop. Failures land in `leaked_skills` for batch sweep |
| Pricing tables relocated to `config.py` | Cross-cutting contract #2 says no hardcoded model strings outside config.py. The dict keys ARE model strings even though they're not model selections. Cleanest fix is relocation, not exception |
| Live smoke iterations are the test of record | Each contract bug from the 4 failed runs got a unit test added in the same fix. Mock-based tests are necessary but insufficient — only the wire format catches API shape bugs |
| Stop strictly before Phase 2 | User authorization. The Railway env flip + A/B matrix runs are production decisions that need a human in the loop |

---

### What's Next

Phase 1 is locally validated. The handoff to Matt:

1. **Review the 7 commits between `bde48d0` and `b9d7d8c`** — they're branching off `main` and ready to be drafted into a Phase 1 PR. Nothing has been pushed to remote per the commit-but-don't-push policy.

2. **Phase 2 (when Matt's ready)**: flip `SKILLFORGE_COMPETITOR_BACKEND=managed` on Railway via env var. No code push required. Run a 2×1 fork-from-python-utils run on prod to validate the deploy environment, then a 5×3 for the "before/after" demo screenshot. Watch `leaked_skills`, watch `cost_breakdown` populate in the WebSocket cost_update events, watch the wall time drop because of real parallelism. Rollback is the same env var flip backwards.

3. **Phase 2 A/B matrix (optional)**: the original PLAN-V1.2 called for a 4-cell Haiku-solo / Haiku+advisor / Sonnet-solo / Sonnet+advisor matrix. With the Advisor Strategy descoped, that collapses to 2 cells: Haiku-solo vs Sonnet-solo. Set `SKILLFORGE_MODEL_COMPETITOR=claude-haiku-4-5-20251001` and re-run; compare correctness × cost; pick a default. Results land in `journal/008-haiku-vs-sonnet.md`.

4. **Phase 3 (after ≥1 week of Phase 2 stable)**: delete `competitor_sdk.py`, collapse the dispatcher into a direct import, drop `claude-agent-sdk` from `pyproject.toml`, remove the Dockerfile `UV_CONCURRENT_*=1` workarounds, delete the SDK-related comments in `config.py`. Single revertable commit.

5. **v1.3+ follow-ups** (queued, not blocking):
   - Cache uploaded skill_ids at the run level (one upload per skill per run instead of one per pair)
   - Native Anthropic `skill_load` event support, drop the synthetic marker
   - Advisor Strategy integration when SDK + API support lands
   - Multi-strategy Challenge Designer (entry #6 backlog item)
   - Process Flow sidebar reset between generations (entry #6 backlog item)
   - 3 pre-existing ruff B008/B904 errors in `skillforge/api/uploads.py`

The biggest learning from this session: **the SDK boundary is not the wire format**. Mock-based unit tests (which I leaned on heavily for test_managed_agents.py + test_competitor_managed.py) verify call shapes against the SDK's Python types, but those types are `Dict[str, object]` in places and `TypedDict(total=False)` in others — they let invalid wire formats through silently. Every contract bug I caught in Phase 6 was something the unit tests passed cleanly. The live smoke is the only reliable check for API shape compliance.

The four bugs the live smoke caught:
1. Folder name must match SKILL.md `name:` field
2. Output paths must be normalized (cloud sandbox uses absolute, L1 needs relative)
3. Skill reference shape: `{"skill_id": ..., "type": "custom"}`, NOT `{"id": ..., "type": "skill"}`
4. Display title collision when re-uploading a skill

Each one is now locked behind a unit test against the wire format I learned about empirically. If the API drifts in a future beta header bump, those tests fail loudly instead of producing silent runtime errors.

Total commit chain for Phase 1 (the PR will collect all 7):
- `a872c57` fix(tests): patch stream_text in 4 judge test files
- `3f2130a` test: backfill PLAN-V1.1 carry-over tests
- `5a8f364` chore(v1.2): Step 0 smoke test + plan corrections
- `ac2352a` feat(v1.2): Phase 1 — Managed Agents competitor backend behind a flag
- `8c27ff8` fix(v1.2): Phase 1 live-smoke API contract fixes (4 issues)
- `b9d7d8c` chore(v1.2): relocate model pricing tables to config.py

Plus the prep commit from earlier in the session:
- `ff442d2` docs(plans): archive PLAN.md + PLAN-V1.1.md, carry backfill items into PLAN-V1.2

Test count: 184 (started red) → 184 (green after judge fix) → 220 (PLAN-V1.1 carry-over) → 244 (test_config) → 276 (test_managed_agents) → 286 (test_competitor_managed) → 292 (path normalization tests) → 294 (skill type/field tests) → **294 backend + 24 frontend + 1 live test passing**.

Live API spend: ~$2.25 across Step 0 + 4 e2e iterations. Well under the $4 cap.

---

*"Every bug I shipped in Phase 1 was something my unit tests passed cleanly. The wire format is the only contract that matters."*