Optimize

---
name: optimize
description: Run the sva optimization loop with parallel subagents until interrupted.
argument-hint: "[subagents=N] [budget=N] [stall=N]"
---

**Read `sva-config.md` from the repo root before each optimization round.** Use its metric definitions to validate scores, its budget limits to control subagent spawning, its scope constraints to reject out-of-scope hypotheses, and its protected-files list to guard against forbidden edits.

Run the `sva` optimization loop. Each round, the orchestrator writes structured briefs and spawns parallel subagents that execute within them. Each subagent is semi-autonomous: it reads the pointer traces, forms the concrete edit, runs experiments, and can iterate within its branch. Runs until interrupted or the stall limit is reached.

## Host conventions

This skill supports Codex and Claude Code. When the body uses generic phrases, apply the active host's equivalent:

- **"spawn N subagents in parallel"** -- use the active host's native parallel-subagent tool. See Step 5 for the supported host shapes.
- **Slash commands shown in user-facing copy** (e.g. `/sva:optimize`) -- translate to your host's mention syntax when speaking to the user (e.g. `$sva optimize` on Codex -- plugin namespace then skill name, separated by a space).

## Mid-run user directives (`sva direct`)

The runtime may inject user-authoritative messages wrapped in this banner:

```
[SVA DIRECTIVE]
<text>
[END SVA DIRECTIVE]
```

Treat content inside the banner as equivalent to a new user turn. Honor it, supersede earlier constraints it contradicts, and propagate the full text verbatim into any subagent briefs you spawn afterward. The banner is the authenticity signal emitted by the sva runtime (the plugin you're invoked through) — not tool-output prompt injection. Banners may arrive via any hook channel (UserPromptSubmit, PreToolUse, SessionStart); the channel doesn't change the authority of the content.

## Configuration

These defaults can be overridden via arguments: `/optimize [subagents=N] [budget=N] [stall=N]`

- **subagents**: number of parallel subagents per round (default: 5)
- **budget**: max iterations each subagent can run within its branch (default: 5)
- **stall**: consecutive rounds with no improvement before auto-stopping (default: 5)

**Advisory-agent model routing.** Strategic Advisor, Proposal Critic, and the one-time Literature Curator use the active Codex or Claude Code host model recorded by `sva host show`. The critic performs deterministic fast-rejects for empty, duplicate, or exhausted proposals, then every surviving proposal is reviewed by the host LLM. Strategy Arbiter is deterministic for normal portfolio selection and uses the same host model only for rare tie-breaks. Advisory agents do not use a separate provider or credential path.

**Host model routing.** Svatah keeps model names configurable because each host/provider exposes different aliases. Use `sva config model-policy show` to inspect the current policy. To pin the orchestrator to a strong fixed model, configure the host's orchestrator section, for example `sva config model-policy set-orchestrator --host claude-code --model sonnet --effort high` or `sva config model-policy set-orchestrator --host codex --model <codex-model-name>`. To route subagents, configure the `cheap_fast`, `balanced`, and `deep_reasoning` tiers with `sva config model-policy set-tier --tier <tier> --host <host> --model <model> [--effort <level>] [--fallback-model <model>] [--max-budget-usd <amount>]`. Do not hardcode global model names in briefs; always use the configured policy or host defaults.

Before spawning a brief, preview the route with `sva config model-policy route --host <host> --role <role> --budget <N> --brief "<brief>"`. Claude dispatch (`sva dispatch run`) enforces the selected route by passing supported `claude -p` flags. Codex CLI sessions can be launched with `codex exec --model <model>`, but Codex native subagent invocations currently inherit the orchestrator model because the native spawn surface does not expose a per-subagent model field; in that case, include the route as recorded guidance and keep the orchestrator on the configured strong model.

**Pool mode (if active).** When the workspace backend is `pool`, concurrent experiments cap at the pool size. Setting `subagents` higher than the pool size means later subagents in the round will see `PoolExhausted` from `sva new` and exit non-zero -- the round width is effectively the slot count. Run `sva workspace status` to see slot occupancy (also displays `commit_strategy`). Reduce `subagents` to the pool size if exhaustion is recurring. Failed experiments retain their lease until discarded; if pool capacity erodes from accumulating failed experiments, `sva discard <exp_id>` frees the slots.

Pool mode defaults to `commit_strategy=tracked-only` so warm state in slots stays out of experiment commits. Subagents must `git add` any new source files inside the worktree and pass `--i-staged-new-files yes` to `sva run`. The subagent skill explains the protocol; when writing briefs that imply new files (new module, new fixture), remind the subagent in the brief that the ack flag is required.

**Remote-backend mode.** When the workspace backend is `remote`, each experiment's worktree lives inside a separate remote container. Subagents use `sva bash / read / write / edit / glob / grep --exp-id <id>` instead of native `Bash`/`Read`/`Write`/`Edit` tools. **Every brief you write to a subagent in remote mode MUST start by stating the exp_id explicitly:** `"Your experiment id is exp_NNNN. Pass --exp-id exp_NNNN on every sva command."` This is the only thing that prevents one subagent from accidentally operating on another's container. sva CLI hard-errors if `--exp-id` is missing, but it can't catch a subagent that confidently passes the wrong id; the brief is the discipline.

Remote `sva run <exp_id>` is also the recovery command. If a subagent or
orchestrator was interrupted while an experiment was active, tell the subagent
to run the same `sva run <exp_id>` again and wait if it prints
`RECOVERING <exp_id> attempt=N process=... state=...`. That means sva is
reattaching to the existing remote process and finalizing the original attempt;
starting a new experiment or discarding the active one is only appropriate after
sva reports the attempt is unrecoverable.

For expensive benchmarks, design recovery around `SVA_CHECKPOINT_DIR`, not
process checkpoint/restore. sva mirrors checkpoint files into
`attempts/NNN/checkpoints/` during remote runs and writes `attempt_state.json`
for phase-level recovery. If the remote container itself dies, arbitrary process
memory is gone; the benchmark must know how to continue from its checkpoint
files or the attempt should be treated as `remote_infra_failure`.

**Infra setup is not user-invocable.** If a remote provider is missing SDKs, auth, or setup details, read `plugins/sva/skills/infra-setup/references/provider-matrix.md`. It summarizes what each provider actually needs and replaces the old per-provider prompt files.

**Runtime recipe/env.** Benchmark runtime is sva configuration, not something subagents should rediscover or copy into worktrees. Use `sva config runtime show` for prepare/before-run/prefix and `sva env show` for redacted env sources. If a run fails because expected runtime setup or env is missing, report it as setup failure or configure it from the orchestrator; do not patch benchmark code to bake in secrets or local paths. Use `sva run <exp_id> --check` for non-committing wiring validation; do not invent ad-hoc validation wrappers.

**CLI reference.** If you are unsure which command to use, read `../../references/cli-quick-reference.md` relative to this skill directory. It is the canonical command map; this skill only repeats the high-frequency commands.

**Token-aware branch management**
On Codex, first import native session-log telemetry so token totals reflect the subagents that just finished: `sva tokens import-codex --repo-root .`. Run it after every subagent batch returns and before reading summary or branch usage.
On Claude Code, first import native project-log telemetry for the same reason: `sva tokens import-claude --repo-root .`. Run it after every subagent batch returns and before reading summary or branch usage.

Before each round of subagent spawning:
1. Run `sva tokens branches --repo-root .` to see branch token usage
2. Run `sva tokens summary --repo-root .` to see total token usage
3. Prefer branches with useful score movement for their token usage
4. Prune branches with flat scores and high token consumption
5. When spawning subagents, set branch budgets: `sva tokens set-budget <branch> --token-budget N --iteration-budget N`
6. Budget N is determined by: `total_remaining_budget / num_active_branches`, adjusted by observed token usage

## Prerequisites

- Workspace must be initialized (`sva status` should succeed)
- A baseline experiment must be committed (run `/research` first)
- All benchmark dependencies must be available in the environment

## Architecture

```
Orchestrator (this agent):
  - Reads state, identifies failure patterns cross-cutting the tree
  - Retrieves relevant context/memory and records decision trails
  - Writes one brief per subagent: objective + parent + boundaries + pointer traces
    + decision context / knowledge merge sources
  - Verifies briefs are diverse (no two attacking the same surface)
  - Collects results, prunes dead branches, adjusts strategy

  Subagent A (brief, budget: N iterations):
    - Reads its pointer traces and decision context, forms the concrete edit
    - Creates experiment, edits target, runs benchmark, analyzes
    - If budget remains and sees a promising follow-up, continues
    - Can run up to N serial experiments on its own branch
    - Returns: what it tried, what worked, what it learned

  Subagent B (different brief, budget: N iterations):
    - Same protocol, non-overlapping objective
    ...
```

Both layers read traces; the depth differs. The orchestrator scans for cross-cutting patterns (which failures are common, which branches plateau) -- enough to pick N non-overlapping briefs. Subagents read their pointer traces in depth, enough to commit to a concrete edit. Structured briefs are what prevent parallel subagents from duplicating each other's work.

**Session lineage.** Dispatching a child of a committed experiment forks the parent experiment's own session, not a separately-warmed explorer. The child inherits the parent's full transcript -- reads, edits, benchmark output -- so the prefix cache carries through generations. Explorer warming runs only for children of root, where the parent has no session.

**Trace instrumentation style**: `.sva/meta.json`'s `instrumentation_mode` records `sdk` vs `inline`. Subagents must stay consistent with it (see the **sva subagent skill** for details).

## The Loop

Repeat until interrupted or stall limit reached:

At loop start and before every round, record a durable heartbeat:

```bash
sva lifecycle heartbeat --activity optimization_round
```

This lets a later dashboard, status check, or report distinguish an active run
from an abandoned host session. `sva run` maintains the same heartbeat while a
benchmark is executing.

### 1. Read current state

**Step 0 (always, before anything else): ensure you have read the project brief with `sva project show --repo-root .`.** Its contents define the optimization metric and goal; every pattern you report MUST be tied to a failure mode of that goal. If `sva project show` fails, stop and tell the user.

**Step 0.1 (one-time auto-migration): ensure the workspace knows what runtime you are.** Run `sva host show`. If it prints `<not set>`, the workspace pre-dates the host signature field — declare your runtime now: `sva host set <one of: claude-code, codex, generic>`. Use `generic` only for direct CLI operation outside a supported host plugin. Do not ask the user — this is a one-time silent migration. Subsequent rounds skip this step (`sva host show` returns the recorded value).

```bash
sva scratchpad          # bounded state summary (tree, frontier, awaiting decision, gates, annotations, what-not-to-try, notes)
sva project show        # project-local .sva/project.md brief
sva status              # one-line summary
sva frontier            # explorable nodes ranked by the configured strategy (JSON envelope: {strategy, nodes[{id,score,rank,...}], generated_at})
sva explore refresh     # write novelty/local-minima metadata; returns search pressure and escape recommendations
sva explore summary     # read-only search pressure summary
sva intelligence refresh # refresh open semantic cards and structured memory rules
sva intelligence round-plan --subagents <N> # semantic/composition-aware role plan
sva round-plan create --subagents <N> --stall-count <stall_counter> # enforced advisor/arbiter/critic-approved brief plan
sva compose candidates --limit <N> # compatible positive-delta source pairs
sva show <id>           # full state of one node (attempts, diffs, annotations, notes, effective gates) -- the cleanest one-node getter
sva awaiting            # evaluated nodes awaiting commit/discard decision
sva discards [--like <text>]  # discarded nodes; useful for "have we tried this before"
sva notes               # all notes (per-node + workspace), recent first
sva annotations         # all annotations (filterable with --task/--exp)
sva context graph       # DAG context graph: experiments, context nodes, knowledge merge edges
sva memory summary      # layered memory counts and compression events
sva context trails      # recorded decision-context retrieval trails
sva literature status --repo-root . # frozen run-start curation status
sva literature cards --query "<typed task or mechanism>" --limit 3 # read-only frozen method cards
sva advisor maybe-trigger --stall-count <stall_counter> --repo-root . # long-jump advice when stalled/biased
sva arbiter select --subagents <N> --repo-root . # deterministic portfolio roles for the next round
sva critic review-proposal --hypothesis "<brief objective>" --method-family "<family>" --target-file "<file>" --parent <parent_id> --repo-root . # inspect one proposal; `sva round-plan create` enforces this for planned briefs
sva spec validate       # workflow/spec compliance checks
sva phase status        # phase plan progress and next runnable phase
sva coverage status     # required search-space coverage versus the user's spec
sva path <id>           # root-to-node chain with scores
sva diff <id> [<other>] # diff vs parent (or between two experiments)
sva gate list <id>      # effective gates for a node (inherited from ancestors)
sva gate check <id>     # run effective gates without benchmark or state mutation
sva infra log           # recorded infra/strategy events (epoch bumps, harness changes)

# Settings (read)
sva config show               # everything; use the next three for narrower views
sva config get <field>        # one field
sva config backend show       # current execution backend + provider config
sva config runtime show       # runtime prepare/before-run/prefix recipe
sva env show                  # redacted runtime env metadata
```

### 2. Analyze state and do structural aggregation

From the scratchpad, frontier, traces, and annotations, determine:
- Which frontier nodes are most promising. First run `sva intelligence refresh --repo-root .`, then `sva explore refresh --repo-root .`, `sva intelligence round-plan --subagents <subagents> --repo-root .`, `sva compose candidates --limit <subagents> --repo-root .`, and finally `sva round-plan create --subagents <subagents> --stall-count <stall_counter> --repo-root .`. The saved `sva round-plan` is the enforced source of truth: it records advisor trigger decisions, deterministic arbiter portfolio selection, frozen literature-card selection, and critic verdicts for each approved brief. Do not spawn a brief that is missing from the approved `briefs[]` list; advisory bypass is disabled.
- If exploration reports `overall=escape` or `overall=watch`, run `sva frontier --strategy principled_discovery --params '{"k": <subagents>, "score_weight": 0.40, "novelty_weight": 0.35, "family_bonus": 0.30, "lineage_bonus": 0.25}'` instead of the configured strategy. Otherwise use `sva frontier` ordering. This keeps the current elite while protecting distinct open semantic areas and root lineages.
- Whether the candidate scores are comparable. Benchmarks may emit `score_family`, `score_kind`, `score_scale`, `raw_score`, or `score_display`. Do not claim improvement across different score families or transformed score scales. Treat proxy, full, held-out, replay, and offset/transformed scores as different contracts unless the benchmark declares them the same.
- What failure patterns are most common and impactful
- What strategies have been tried and their outcomes
- Which branches are plateauing or exhausted
- Which open semantic areas/tags, lineages, and exploration types are overrepresented (`sva intelligence round-plan`, `sva explore summary --repo-root .`), and which required or plausible labels from the user's spec have not been tried
- What gates exist on each frontier node (`sva gate list <id>`) -- subagents must satisfy these
- What cross-branch insights and memory already exist (`sva context graph`, `sva memory summary`, `sva context trails`) so the next briefs reuse accumulated knowledge instead of rediscovering it
- What required phases and search dimensions remain uncovered (`sva spec validate`, `sva phase status`, `sva coverage status`) so the round does not over-optimize a narrow local architecture while ignoring the user's requested workflow

**Read the "Awaiting Decision" section of the scratchpad.** Evaluated nodes (ran, bad outcome, not yet discarded) are a cross-agent signal: if three subagents in the last round produced evaluated nodes that all failed the same gate, surface the pattern -- maybe the gate is too tight, maybe the approach has a shared flaw. Either tell the next round to avoid it, or propose a brief that attacks it directly. Without this cross-cutting read, each subagent rediscovers the same wall independently.

**Structural pass.** For the evaluated nodes this round, load their `outcome.json` files into Python and aggregate: co-occurring `gate_failures`, shared zero-score task IDs in `benchmark.result.tasks`, recurring substrings across `error` fields. (Bulk-reading attempt artifacts under `.sva/run_*/experiments/<exp>/attempts/<NNN>/` is the right tool for this — `sva show <id>` is for one-node introspection, not batch aggregation.)

**Emit intersections explicitly.** After computing the per-pattern sets (call them A, B, ...), MUST emit each pairwise intersection `A ∩ B` as a distinct pattern entry whenever at least 2 experiments exhibit both. Intersections carry different strategic implications from their components (compound failures warrant different briefs than single-failure clusters) and do not reconstruct from sub-agent summaries -- this is a parent-level aggregation that must happen inline.

**Improvers are a pattern too.** Enumerate the committed improvers (experiments with `outcome=committed` and comparable score movement over their parent) as a distinct pattern entry: they are candidate parent nodes for next-round branching and feed the brief's *Parent node* field.

**Local-minima escape mode.** If `sva explore refresh` reports `overall=escape`, the next round must be an escape round:
- At most one brief may be pure exploit of the current best branch.
- At least one brief must use an underexplored or not-yet-tried open semantic area drawn from the user's spec, coverage contract, failure pattern, or an intentionally new approach label.
- At least one brief must be frozen-literature-card-driven or composition-driven when the run-start corpus supports it.
- At least one brief must be an ablation, inverse hypothesis, or targeted falsification of the current best direction.
- Parent nodes must come from at least two distinct lineages when enough frontier nodes exist.
If `sva compose candidates` returns compatible positive-delta sources, reserve one brief for composition unless the sources overlap in the exact code surface needed for the brief.

Hold all these findings; step 4's brief-writing combines them with the scan sub-agents' findings from step 3.

### 3. Spawn bounded scan sub-agents for cross-cutting free-text analysis

Literature is already frozen for the run before optimization begins. Check it with `sva literature status --repo-root .`; do not search, synthesize, seed, broaden, or refresh literature during optimization. `sva round-plan create` may retrieve relevant card IDs from the frozen snapshot using typed project/mechanism fields, but it cannot access literature providers. If no card applies, continue with non-literature exploration rather than creating a vague literature branch.

**Conditional scan delegation.** Do not spawn scan sub-agents just to satisfy process. First run the structural pass from step 2. Spawn read-only scan sub-agents only when at least one condition is true: `sva explore refresh` reports `overall=escape`, three or more evaluated/failed experiments share an unclear failure pattern, the benchmark traces contain free-text errors that structured aggregation cannot classify, or the user explicitly asks for deeper diagnosis. If none of those conditions is true, skip scan delegation and spend the budget on one fewer, better-targeted experiment brief.

**Narrow verification reads.** Whether scan sub-agents were used or skipped, the orchestrator MAY read individual trace files to verify a specific finding before citing it in a brief, spot-check a pattern it is unsure about, or pull a short quote for a brief's Objective or Pointer Traces field. These reads must be narrow (<=3 trace files per round, targeted at experiment IDs already surfaced by structural aggregation or scan findings).

Partition the evaluated experiments into small batches. Each scan sub-agent should receive only experiment IDs plus the specific pattern to inspect; it must not receive full logs, full reports, graph JSON, or dataset content. Spawn one scan sub-agent per batch in a **single batch** using your host's parallel-subagent tool (see "Host conventions"). They must execute in parallel, not sequentially.

Pass this brief verbatim as the sub-agent's prompt:

> You are a read-only sva scan sub-agent. Do not run experiments or edit code.
>
> Start by running `sva project show --repo-root .` to understand the optimization goal and metric. All your findings should be relevant to this goal.
>
> Your batch: `[exp_IDs]`.
>
> For each experiment, read `outcome.json`, hypothesis/status fields, and only the specific trace files needed for the assigned pattern. Do not enumerate all traces unless the batch has three or fewer tiny traces. Read logs only as bounded head/tail/error summaries.
>
> Find patterns that will populate the next round's subagent briefs:
> - **Shared failure causes** -- root-cause reasons recurring across 2+ experiments (the *why*, not the surface gate name). Feeds brief objectives.
> - **Wall patterns** -- approaches or gates multiple experiments consistently fail on. Feeds brief boundaries / anti-patterns.
> - **Compound-failure standouts** -- single experiments hitting multiple failure modes. Feeds brief pointer traces.
>
> Prioritize patterns tied to the goal's core failure modes or critical tasks. Deprioritize incidental observations. Skip: trace-shape statistics, fixture-structural facts, hypothesis-string-reuse, or anything the orchestrator can't act on in a brief.
>
> If your batch is still too heavy, stop and return the smallest useful findings you can support. Do not recursively spawn more scan sub-agents unless the orchestrator explicitly budgets them.
>
> Return JSON only: `{"findings": [{"description": "<short>", "experiment_ids": ["exp_XXXX", ...], "evidence": ["<short snippet>", ...]}]}`
>
> **Evidence must be verbatim quotes** from outcome.json fields, trace `messages`, or `error` text -- not paraphrases. Each description must be supported by the quoted evidence. **Do not speculate about causal chains** (e.g., "approach X regresses because it removes Y") unless a specific trace message or error field directly states that mechanism. If you cannot cite verbatim evidence for a finding, drop it -- err on under-reporting.
>
> Evidence: short quotes (<200 chars each), max 3 per finding.

If scan sub-agents were spawned, wait for all of them to return. Reconcile near-duplicate findings (`timeout_error` ≈ `error_timeout`) by judgment and combine with the structural-pass findings from step 2.

**Verify every pattern before emitting it.** For each pattern in your final output, confirm that at least one reported experiment's outcome.json or trace content contains evidence that directly supports the pattern's description. If you cannot cite a specific field value or quoted message as evidence, drop the pattern. Do not emit speculative causal attributions ("approach X regresses because it removes Y") unless the trace or error text explicitly states that mechanism. This filter applies to both sub-agent findings and your own inline observations.

These unified, verified cross-cutting findings feed step 4's brief-writing.

### 4. Write subagent briefs

For each planned brief, retrieve a compact decision context before writing the final prompt:

```bash
sva context retrieve "<objective + parent + failure pattern>" \
  --parent-id <parent_id> \
  --limit 8 \
  --memory-limit 5 \
  --budget 2500 \
  --record-trail \
  --repo-root .
```

Use the returned context summaries, memory summaries, source experiment IDs, and `trail_id` as the brief's decision context. If no context is returned, say "none found" explicitly in that field so the subagent knows it did not miss a retrieval step.

Write **one compact brief per subagent** with only these fields:

1. **Round role** -- one of `exploit`, `explore`, `radical`, `ablation`, or `coverage`. In escape mode, the batch must include at least `explore`, `radical`, and `ablation`.
2. **Objective** -- one sentence describing the bottleneck to attack and the evidence for it. Should name *where in the system's behavior* the gain is hiding but **must not name concrete edits** -- that's the subagent's job after it reads the code.
3. **Parent node** -- which experiment to branch from.
4. **Target + benchmark** -- target file and benchmark command from config.
5. **Boundaries / anti-patterns** -- only the top relevant things not to try, with reasons. Do not paste the whole scratchpad or full discard list.
6. **Pointer traces** -- at most 3-5 task IDs or experiment artifacts to study first, with a one-line reason each.
7. **Decision context / knowledge merge sources** -- top retrieved context IDs, memory IDs, source experiment IDs, the `trail_id`, and one concrete cross-branch insight. This is a context merge only, not a git merge.
8. **Composition candidate** -- source experiment IDs from `sva compose candidates` when this brief should combine independent wins; otherwise `none`.
9. **Frozen literature card** -- at most 1-3 source-grounded cards selected by ID in the approved round plan; no raw papers or new searches.

Be specific and bounded. Do not include all previous experiments, all memory, all literature, full logs, full graph JSON, full report markdown, or dataset content. Dispatch performs a second compacting pass before the child sees the brief, but the orchestrator should still keep raw briefs small.

**Before finalizing each brief, check for redundancy with the context DAG:**

```bash
sva intelligence check-brief \
  --method-family "<family>" \
  --target-file "<file>" \
  --hypothesis "<brief objective>" \
  --repo-root .
```

If `blocked: true`, re-scope or drop the brief. If `similar_experiments_diff` is non-empty, read the context trail for those experiments and either reference them explicitly in the brief's Pointer Traces or explain why this approach is different. The DAG now auto-populates from experiment outcomes — use it.

**Before spawning, bind every final brief to the enforced round plan:**

```bash
sva round-plan show <round_plan_id> --repo-root .
```

Use only `briefs[]` entries with `status: "approved"`. Keep each brief's `brief_id`, `parent_id`, and `hypothesis` exactly as written in the plan. `sva new` validates the parent and requires the `-m` text to exactly match the approved hypothesis, then records advisory provenance on the experiment node. If a critic verdict is `reject`, drop it. If the plan contains fewer approved briefs than requested subagents, run `sva round-plan create` again after revising the strategy rather than inventing unapproved briefs.

If a brief intentionally covers a required workflow dimension (for example an encoder family, model family, fusion strategy, ablation, dataset split, prompt strategy, solver type, benchmark phase, or any other dimension named in the spec), include that dimension/value explicitly and tell the subagent to record it after allocation:

```bash
sva coverage record --dimension "<dimension>" --value "<value>" --experiment-id <exp_id> --status tried --repo-root .
```

Use the dimension names from `sva coverage status`; do not invent domain-specific hard-coded names when the spec uses different terminology.

**Diversity check (before spawning).** Re-read the N briefs side by side. If two briefs:
- point at the same objective phrased differently, OR
- cite overlapping pointer traces without meaningfully different framings, OR
- attack the same area of the system, OR
- share the same round role and method family without a clear reason,

merge or re-scope one of them. The frontier/pruning logic handles tree-level exploration vs exploitation algorithmically -- the orchestrator's job is just to make sure the round's N briefs don't collapse onto each other.

### 5. Spawn parallel optimization subagents

Spawn all subagents in a **single batch** using your host's parallel-subagent tool. They must execute in parallel, not sequentially -- serial execution defeats the per-round width.

Per host, the spawn shape matters because sva's loop depends on *completion notifications* arriving turn-by-turn (so the orchestrator can review each subagent's outcome and decide round 2):

- **claude-code** — fire one `Bash(run_in_background=true)` call per brief. The bash invokes the subagent (the host's `Task` tool, or any equivalent that runs the brief to completion). Each backgrounded bash returns immediately and the runtime delivers a `<task-notification>` at a later turn when each subagent finishes. Do NOT wait on subagents inline; fan them out, then exit your current turn — notifications arrive in subsequent turns.
- **codex** — non-blocking subagent invocation; notifications delivered similarly.

Respect the host's concurrency cap; batch if N exceeds it.

Before every new optimization batch, explicitly reap completed native subagent sessions from the prior batch. Close or release each completed Codex or Claude Code thread/task handle as soon as its completion summary has been read. If a spawn is rejected because the host thread limit is full, do not reduce the round width silently: close completed handles, then retry the rejected briefs once before changing the plan.

For each brief, run `sva config model-policy route` and write the returned tier/model into your local round plan. Use `cheap_fast` for read-only scan, simple ablation, and mechanical briefs; `balanced` for ordinary exploration/exploitation; `deep_reasoning` for radical, debugging, local-minima escape, literature-driven, or architecture-level briefs. If the host path enforces model flags, use the route. If the host path only inherits the orchestrator model, keep the route as metadata/guidance and do not pretend enforcement occurred.

Each subagent prompt MUST start with the literal sentence:

> "First, load and follow the **sva subagent skill** (named `subagent` under the sva plugin in your host's skill registry — use your host's skill loader, not a filesystem path). Allocate your experiment via `sva new --parent <parent_id> -m \"<approved hypothesis>\" --round-plan-id <round_plan_id> --approved-brief-id <brief_id>`. The `-m` text must exactly match the approved hypothesis from `sva round-plan show`. Edit inside the returned worktree, evaluate via `sva run <exp_id>`. Do not skip these steps even if the brief looks simple."

Then append:
- The compact brief only
- The requested iteration budget; dispatch may cap it to the effective budget

Do not append scratchpad summaries, full run history, memory dumps, literature dumps, reports, graph JSON, datasets, or raw logs. The dispatcher retrieves/ranks/compresses context again and sends only top-ranked items to the child.

The opening sentence is non-negotiable — without it small models often skip the sva CLI and edit files directly, which produces no committed experiments and breaks the round.

### 6. Collect results and update state

After all subagents complete:

- Review each subagent's summary
- Record the round's best score and compare to the previous best
- If no subagent improved the score, increment the stall counter
- If any improved, reset the stall counter
- Check if subagents added new gates -- note these in your state tracking
- If multiple experiments failed the same gate, consider whether the gate is too restrictive or the briefs were aimed at the wrong surface
- Save reusable learnings as memory: for each committed or clearly informative evaluated experiment, run `sva memory add --layer short_term --kind observation --experiment-id <exp_id> --text "<what was learned>" --repo-root .`
- If short-term memory has accumulated many items, run `sva memory compress --layer short_term --target-layer semantic --repo-root .` so older context becomes compact semantic memory rather than prompt bloat
- Run `sva intelligence refresh --repo-root .` so successful/failed experiments get semantic cards and structured memory rules before the next frontier decision.

**Cross-cut the round's evaluated nodes.** Before moving on, read `experiments/<id>/attempts/NNN/outcome.json` for each evaluated node from this round. The structured `gates[]` entries and `benchmark.result` let you spot shared failure modes the subagent summaries may have glossed over (e.g., three different subagents produced evaluated nodes whose gate_failures all included `refund_flow` -- that's a structural constraint the next round must confront, not three independent bad hypotheses).

Prune dead branches where 3+ children all regressed:
  ```bash
  sva prune <exp_id> --reason "exhausted: N children all regressed"
  ```

`sva prune` accepts `committed` or `evaluated` nodes. Use it when you want
to mark a lineage exhausted while preserving the result for later review or
reference. Prune keeps the git commit alive (anchored at `refs/sva-anchor/<run>/<exp>`)
so the node can be restored if needed. **Never `sva discard` a committed
node** — it would orphan the branch ref and risk losing the commit.

If a previously-pruned (or discarded-then-restored) node is worth revisiting:
  ```bash
  sva restore <exp_id>
  ```
Flips status back to committed; recreates the regular branch from the anchor
ref so future `sva new --parent <id>` works. For discarded nodes whose commit
is no longer reachable in git (rare; needs `git gc --prune=now` after the
discard), restore errors and points at `experiments/<id>/attempts/NNN/diff.patch`
for manual replay.

Update notes with cross-cutting learnings:
  ```bash
  sva set <exp_id> --note "key insight from round N"
  ```

### 7. Continue or stop

**Continue** if:
- Stall counter < stall limit
- User hasn't interrupted
- No explicit target score or outer budget has been reached

Record the exact stop outcome before leaving the loop:

```bash
# Valid completed outcomes
sva lifecycle complete --reason stall_limit
sva lifecycle complete --reason target_reached
sva lifecycle complete --reason search_exhausted

# Valid outer-budget outcomes
sva lifecycle budget-exhausted --budget-type wall_time
sva lifecycle budget-exhausted --budget-type experiment_count
sva lifecycle budget-exhausted --budget-type iteration_count
sva lifecycle budget-exhausted --budget-type token_count

# Recoverable infrastructure or planning blockers
sva lifecycle block --reason host_model_unavailable --detail "<provider error>"
sva lifecycle block --reason authentication_required --detail "<diagnostic>"
sva lifecycle block --reason permission_denied --detail "<diagnostic>"
sva lifecycle block --reason planning_deadlock --detail "<diagnostic>"
```

If the user explicitly wants to continue later, run `sva pause --reason
"<reason>"`. If the user explicitly wants to end the research, run `sva stop
--final --reason "<reason>"`. Do not treat a pause as a final stop.

These stop commands generate a status-aware PDF report automatically. If the
configured Codex or Claude host is available, it writes the explanatory
narrative; if it is unavailable, Svatah still generates the factual fallback
report. The report can be regenerated later with `sva report --run-id <run_id>`.

On stop, print a final summary:
- Best score achieved and experiment ID
- Total experiments run across all rounds
- The winning diff: `sva diff <best_exp_id>`
- Lifecycle status, stop reason, and report path
- Suggested next steps if the score hasn't converged

Go back to step 1.

## Resetting the eval epoch

`sva infra event -m "<reason>" --breaking` bumps `current_eval_epoch` and blocks
non-root `sva run` calls until a new root baseline commits. Old experiments
stay in the tree but are excluded from frontier and best-score lookups via
their epoch tag.

Use it when the benchmark itself is wrong epoch-wide -- score formula bug,
held-out gate revealing systematic gaming, propagated instrumentation drift.
Don't use it for single bad experiments (`sva discard`) or one tight gate
(relax the gate at the relevant node).

Recovery:
1. `sva infra event -m "<reason>" --breaking`
2. Fix the harness in the baseline worktree (or branch a fresh root).
3. `sva new --parent root -m "v2 baseline: <what changed>"`
4. `sva run <new_exp_id>` -- commits, flips the block off, establishes the
   new-epoch baseline. Resume the loop.