@@ -160,12 +160,13 @@ step's think time, and the next step's first request **wakes it through the
 atenet router** (request parking). Mostly-idle sessions plus fast wake is
 exactly the oversubscription story this measures.
 
-The entire workload is the declarative script in
-[`internal/benchmarking/boomer/agentsession/script.go`](../internal/benchmarking/boomer/agentsession/script.go)
-— one table entry per step, naming what the agent is doing and the resource
-ops that act it out. To change the workload, edit the table. Each session is
-an actor from the stock `glutton` template; steps are sequences of glutton
-RPCs:
+The entire workload is a YAML script. The default,
+[`internal/benchmarking/boomer/agentsession/scripts/coding-session.yaml`](../internal/benchmarking/boomer/agentsession/scripts/coding-session.yaml),
+has one entry per step naming what the agent is doing and the resource ops
+that act it out. To change the workload, edit it or add a sibling file and
+select it with `--agentsession-script` (see [Writing a
+script](#writing-an-agent-session-script)). Each session is an actor from
+the stock `glutton` template; steps are sequences of glutton RPCs:
 
 | Step | The agent is… | Sandbox effect |
 |---|---|---|
@@ -193,9 +194,10 @@ RPCs:
 The script needs bigger actors than the 256Mi default: it holds ~96Mi of
 RAM arrays + ~110Mi of tmpfs files, and the observed guest peak with
 allocator transients is ~320Mi (512Mi OOMs). Deploy the workloads with
-`--actor-memory 1Gi`. `TestSessionBudgets` bounds the script-declared bytes
-only, so script edits that grow the working set fail the test and force this
-guidance to be revisited.
+`--actor-memory 1Gi`. Every script declares that floor as
+`min_actor_memory`; the worker reads the `glutton` template's memory limit
+at start and refuses to run a script against a smaller actor, so a too-small
+deployment fails loudly instead of showing up as OOM-flaky steps.
 
 ```sh
 ./benchmarking/deploy_locust.sh --deploy --sandbox-class gvisor --actor-memory 1Gi
@@ -204,6 +206,10 @@ guidance to be revisited.
 
 #### Agent-Session Configuration Knobs
 
+* `--agentsession-script` — built-in script variant to run, by file name
+  under `internal/benchmarking/boomer/agentsession/scripts/` (default
+  `coding-session`). Read once, on the worker's first iteration after the
+  swarm starts, then fixed for the worker's lifetime.
 * `--agentsession-think-scale` — multiplier on every think gap; 0.5 makes the
   fleet twice as chatty, 4.0 models slow reasoning models (default 1.0). Each
   gap gets ±20% jitter so sessions don't move in lockstep.
@@ -212,6 +218,50 @@ guidance to be revisited.
 * `--lifecycle-mode suspend|pause` — durable suspend (default) or node-local
   pause between steps.
 
+#### Writing an agent-session script
+
+A script is a named step list with a memory floor:
+
+```yaml
+name: coding-session
+min_actor_memory: 1Gi
+steps:
+  - name: 01_read_task
+    agent: Boots, reads the task prompt, loads its context window
+    think: 2s
+    ops:
+      - fill_ram: {key: agent_context, size: 32Mi}
+      - ping: {}
+  - name: 02_clone_repo
+    agent: git clone of the target repository
+    think: 3s
+    ops:
+      - ingest: {key: repo_tarball, size: 16Mi}
+      - burn_cpu: {millis: 500, parallel: 1}
+```
+
+`think` is the suspended gap before the step (a Go duration, scaled by
+`--agentsession-think-scale`); `name` keys the `Step_<name>` stats row.
+Sizes are Kubernetes quantities. Each op is one glutton RPC:
+
+| Op | Arguments | Sandbox effect |
+|---|---|---|
+| `ingest` | `key`, `size` | bytes cross the network from the driver and land in a file: a download |
+| `burn_cpu` | `millis`, `parallel` (default 1) | spins `parallel` goroutines for `millis` of wall clock |
+| `write_disk` | `key`, `size` | writes locally generated bytes to a file |
+| `read_disk_digest` | `key` | reads and hashes a file; nothing ships back |
+| `read_disk_data` | `key` | reads a file and returns its bytes: disk read plus egress |
+| `fill_ram` | `key`, `size` | allocates a resident RAM array |
+| `churn_ram` | `key`, `size` | re-randomizes part of an array in place, dirtying pages |
+| `walk_ram` | `key` | touches one byte per page: demand-paging cost after a resume |
+| `ping` | none | a minimal round trip through the router |
+
+Loading is strict: unknown op kinds or fields, an argument a kind does not
+take, a read of a file nothing wrote, a walk of an array nothing filled, a
+duplicate step name, or a `min_actor_memory` below the declared RAM plus
+disk all fail before any actor is created. Built-in variants are checked by
+`TestEmbeddedScriptsAreValid`, so a broken file cannot merge.
+
 #### Agent-Session Reported Metrics
 
 * `WakeFirstTouch`: latency of a dedicated ping sent before each step's ops —
 
@@ -20,6 +20,18 @@
 
 @events.init_command_line_parser.add_listener
 def add_agentsession_arguments(parser: LocustArgumentParser) -> None:
+    parser.add_argument(
+        "--agentsession-script",
+        type=str,
+        default="coding-session",
+        env_var="LOCUST_AGENTSESSION_SCRIPT",
+        help=(
+            "Built-in agent-session script variant to run; one of the YAML "
+            "files under internal/benchmarking/boomer/agentsession/scripts/ "
+            "(default: coding-session)"
+        ),
+        include_in_web_ui=True,
+    )
     parser.add_argument(
         "--agentsession-think-scale",
         type=float,
 
@@ -67,6 +67,7 @@
     "--sweperf-total-steps": int,
     "--sweperf-num-cycles": int,
     "--sweperf-poll-interval-ms": int,
+    "--agentsession-script": str,
     "--agentsession-think-scale": float,
 }
 
 
@@ -13,8 +13,9 @@
 // limitations under the License.
 
 // Package agentsession implements the AgentSessionUser locust test: each VU
-// is one coding-agent session replaying the scripted steps in script.go
-// against a glutton actor. After every step the actor is suspended for the
+// is one coding-agent session replaying a scripted step sequence (a YAML
+// file under scripts/, selected by --agentsession-script) against a glutton
+// actor. After every step the actor is suspended for the
 // step's "LLM thinking" gap; by default the next step's first request wakes
 // it through the atenet router (request parking), so the benchmark measures
 // the user-visible wake latency Substrate's oversubscription story rests on.
@@ -55,6 +56,7 @@ import (
 	"google.golang.org/grpc/metadata"
 	"google.golang.org/grpc/status"
 	"google.golang.org/protobuf/proto"
+	"k8s.io/apimachinery/pkg/api/resource"
 )
 
 const (
@@ -100,8 +102,7 @@ func initAgentSession(cfg *userclass.Config) (taskFn func(), shutdown func(conte
 	if cfg.Tracer == nil {
 		cfg.Tracer = otel.Tracer("substrate-boomer/agentsession")
 	}
-	rt := &runtime{cfg: cfg, steps: Session()}
-	rt.ingestBuf = makeIngestBuf(rt.steps)
+	rt := &runtime{cfg: cfg}
 	return rt.iterate, rt.shutdown
 }
 
@@ -132,10 +133,101 @@ func makeIngestBuf(steps []Step) []byte {
 // goroutine keeps its own session in users, keyed by goroutine ID, because
 // boomer offers no per-VU context.
 type runtime struct {
-	cfg       *userclass.Config
-	steps     []Step
-	ingestBuf []byte   // shared read-only ingest payload, sized to the largest ingest op
-	users     sync.Map // goroutineID -> *sessionUser
+	cfg   *userclass.Config
+	users sync.Map // goroutineID -> *sessionUser
+
+	// script is resolved by loadScript on the first iteration and fixed for
+	// the worker's lifetime; ingestBuf is sized to it.
+	scriptMu  sync.Mutex
+	script    *Script
+	ingestBuf []byte // shared read-only ingest payload, sized to the largest ingest op
+
+	// The template memory check runs once per worker. A fetch failure
+	// leaves it unanswered so the next startUser retries; a verdict is
+	// final until the workloads are redeployed.
+	templateMu  sync.Mutex
+	templateOK  bool
+	templateErr error
+}
+
+// loadScript resolves the run's script on first use. It cannot happen at
+// Init: the operator's knob values arrive with the first spawn message,
+// after Init, so a load there would only ever see --config-json. A failed
+// load is retried on the next iteration, so correcting the knob in the web
+// UI and starting a new swarm recovers without a pod restart.
+func (r *runtime) loadScript() (*Script, error) {
+	r.scriptMu.Lock()
+	defer r.scriptMu.Unlock()
+	if r.script != nil {
+		return r.script, nil
+	}
+	name := r.cfg.Dyn.Load().AgentSessionScript
+	if name == "" {
+		name = DefaultScript
+	}
+	s, err := Load(name)
+	if err != nil {
+		return nil, err
+	}
+	b := Budgets(s.Steps)
+	slog.Info("agentsession: loaded script",
+		slog.String("script", s.Name),
+		slog.Int("steps", len(s.Steps)),
+		slog.String("declared_ram", formatSize(b.RAM)),
+		slog.String("declared_disk", formatSize(b.Disk)),
+		slog.String("min_actor_memory", formatSize(s.MinActorMemory)))
+	r.script = s
+	r.ingestBuf = makeIngestBuf(s.Steps)
+	return s, nil
+}
+
+// checkTemplateMemory refuses to start sessions against a template whose
+// memory limit is below the script's min_actor_memory. A too-small actor
+// OOMs partway through the script and shows up as flaky steps, which is far
+// harder to read than a refusal at start. A template with no memory limit
+// is allowed through with a warning.
+func (r *runtime) checkTemplateMemory(ctx context.Context) error {
+	r.templateMu.Lock()
+	defer r.templateMu.Unlock()
+	if r.templateOK {
+		return nil
+	}
+	if r.templateErr != nil {
+		return r.templateErr
+	}
+	ref := &ateapipb.ObjectRef{Atespace: templateNS, Name: templateName}
+	tmpl, err := r.cfg.APIStub.GetActorTemplate(ctx, &ateapipb.GetActorTemplateRequest{ActorTemplate: ref})
+	if err != nil {
+		return fmt.Errorf("GetActorTemplate %s/%s: %w", templateNS, templateName, err)
+	}
+	limit, ok := memoryLimit(tmpl)
+	switch {
+	case !ok:
+		slog.Warn("agentsession: template sets no memory limit; cannot check it against the script",
+			slog.String("template", templateName),
+			slog.String("min_actor_memory", formatSize(r.script.MinActorMemory)))
+	case limit < r.script.MinActorMemory:
+		r.templateErr = fmt.Errorf("template %s/%s memory limit %s is below script %q min_actor_memory %s; redeploy the workloads with --actor-memory %s",
+			templateNS, templateName, formatSize(limit), r.script.Name, formatSize(r.script.MinActorMemory), formatSize(r.script.MinActorMemory))
+		return r.templateErr
+	}
+	r.templateOK = true
+	return nil
+}
+
+// memoryLimit reads the template's memory limit in bytes, if it has one.
+func memoryLimit(tmpl *ateapipb.ActorTemplate) (int64, bool) {
+	for _, l := range tmpl.GetResources().GetLimits() {
+		if l.GetName() != "memory" {
+			continue
+		}
+		q, err := resource.ParseQuantity(l.GetQuantity())
+		if err != nil {
+			return 0, false
+		}
+		return q.AsInt64()
+	}
+	return 0, false
 }
 
 // think returns the suspended "LLM thinking" gap before step s, which is the
@@ -155,6 +247,15 @@ func (r *runtime) think(s Step) time.Duration {
 // script completes, so one actor keeps producing suspend/resume cycles for
 // the whole run.
 func (r *runtime) iterate() {
+	script, err := r.loadScript()
+	if err != nil {
+		slog.Error("agentsession: cannot load script; goroutine will retry next iter",
+			slog.String("err", err.Error()))
+		time.Sleep(2 * time.Second)
+		return
+	}
+	steps := script.Steps
+
 	gid := boomerutil.GoroutineID()
 	val, loaded := r.users.Load(gid)
 	if !loaded {
@@ -169,13 +270,13 @@ func (r *runtime) iterate() {
 	}
 	u := val.(*sessionUser)
 
-	step := r.steps[u.stepIndex]
+	step := steps[u.stepIndex]
 
 	// The LLM is "thinking": the actor stays suspended for the gap.
 	time.Sleep(r.think(step))
 
 	if u.runStep(context.Background(), step) {
-		u.stepIndex = (u.stepIndex + 1) % len(r.steps)
+		u.stepIndex = (u.stepIndex + 1) % len(steps)
 		if u.stepIndex == 0 {
 			slog.Info("agent session completed the full script; starting over",
 				slog.String("actor", u.actorName))
@@ -195,6 +296,9 @@ func (r *runtime) iterate() {
 // then suspends it so the first scripted step begins — like every later
 // step — with a wake from suspension.
 func (r *runtime) startUser(ctx context.Context) (*sessionUser, error) {
+	if err := r.checkTemplateMemory(ctx); err != nil {
+		return nil, err
+	}
 	u := &sessionUser{
 		cfg:       r.cfg,
 		actorName: "agent-" + uuid.NewString(),
Original file line number	Diff line number	Diff line change
`@@ -67,6 +67,7 @@`
`67`	`67`	`"--sweperf-total-steps": int,`
`68`	`68`	`"--sweperf-num-cycles": int,`
`69`	`69`	`"--sweperf-poll-interval-ms": int,`
	`70`	`+ "--agentsession-script": str,`
`70`	`71`	`"--agentsession-think-scale": float,`
`71`	`72`	`}`
`72`	`73`