---
name: ironbee-run-scenario
description: >
  Run a saved IronBee verification scenario end-to-end by delegating to the ironbee-scenario custom
  agent (operation run). Use when the user types `$ironbee-run-scenario`. The sub-agent drives the
  pause → act → resume loop, realizes any `llm-action` steps with the platform tools, caches the
  realization, and reports the outcome. NOT a verification cycle — no verdict, no gate.
---

# IronBee — Run scenario

> **Delegate** — spawn the **`ironbee-scenario` custom agent** via `spawn_agent` with
> `agent_type="ironbee-scenario"` **and `fork_turns="none"`** (the default `fork_turns="all"` silently
> drops the agent_type → a generic toolless agent). The sub-agent owns the `ibdt_scenario-*` tools and the
> platform tools the run needs; you don't have them.

Run a saved verification **scenario**. This is NOT a verification cycle — no verdict, no gate.

## Resolve the arguments
Peel these off the front of the argument string, then the remainder is the scenario:
- **`step`** → step-by-step mode: pause after EVERY step, not just `llm-action` ones.
- **`refresh:<stepId>[,<stepId>…]`** (or **`refresh:all`**) → re-resolve those `llm-action` steps
  from scratch, ignoring their cached realizations. (`ironbee scenario status --verbose` lists the
  step names and which are stale.)
- The **remainder is the scenario reference** — an exact name OR a semantic description — up to an
  optional ` args:` boundary. A ` args:` token (a space, then `args:`) splits it: text BEFORE is the
  reference, text AFTER is a JSON object of **override arguments** for the scenario's `params`. With
  no ` args:` the whole remainder is the reference and the scenario runs with its captured defaults.


> **Step mode + delegation — set expectations.** The sub-agent prints a progress block after every
> pause, but a delegated sub-agent's turn-by-turn output does NOT stream into this conversation —
> you only get its report when it returns. So `step` here gives you a controlled, pause-per-step run
> and a full step-by-step account at the END, not a live blow-by-blow. Say that up front when the
> user asks for step mode, so they aren't waiting on output that won't arrive mid-run.
> (A project running `codex.verifier.mode: main-agent` drives the loop inline instead, where each
> block does appear as it happens.)

## Steps
1. **Resolve** the tokens above.
2. **Spawn** `spawn_agent` with `agent_type="ironbee-scenario"` and `fork_turns="none"`, passing in
   `message`:
   > Operation: run
   > Target: \<the name / description>
   > Args: \<the override JSON — OMIT when no ` args:` tail was given>
   > Mode: \<include `Mode: step` ONLY when the request began with a `step` token>
   > Refresh: \<`all`, or the comma-separated step names — OMIT when no `refresh:` token was given>
   The sub-agent resolves the reference, starts the run, and drives the **pause → act → resume**
   loop: on an `llm-action` pause it performs the intent with the platform tools, writes the
   deterministic replay back as that step's cache (stamped with the current commit + the paths it
   covers), and resumes. Cached steps replay without pausing.
   **Wait for the sub-agent in the same turn.** Block on it with `wait_agent` passing `timeout_ms: 600000` (install also sets that as the default wait). A wait that returns with no completed agent is NOT a failure — call `wait_agent` again; do not nudge a still-running agent with `send_message` and do not interrupt it. A run takes minutes.
3. **Relay** its report. If it hands back a ready-made progress / result block, print it **verbatim**.

## Reading the result
- Green **only when the verdict is `pass`**. A **`soft-fail`** (soft assertions failed while the run
  continued) is NOT green — say so plainly.
- On failure, name the failing step and its error, not just "it failed".
- A genuine app DEFECT is the headline — the scenario did its job. Never weaken a scenario to make a
  run pass.

(To verify your code changes use `$ironbee-verify`. To author/change a scenario use
`$ironbee-manage-scenario`, to find one `$ironbee-search-scenario`, to re-validate + repair stale
ones `$ironbee-sync-scenario`. To just *detect* staleness — including per cached step — run
`ironbee scenario status --verbose`.)