@adcp/sdk 6.5.0 → 6.7.0

package/dist/lib/testing/storyboard/runner.js

@@ -17,6 +17,7 @@ exports.listStrictOnlyFailures = listStrictOnlyFailures;
 exports.summarizeStrictValidation = summarizeStrictValidation;
 exports.runStoryboardStep = runStoryboardStep;
 exports.applyBrandInvariant = applyBrandInvariant;
+exports.applyDisableSandboxHint = applyDisableSandboxHint;
 exports.applyIdempotencyInvariant = applyIdempotencyInvariant;
 exports.getFirstStepPreview = getFirstStepPreview;
 const client_1 = require("../client");
@@ -28,6 +29,9 @@ const rejection_hints_1 = require("./rejection-hints");
 const shape_drift_hints_1 = require("./shape-drift-hints");
 const strict_validation_hints_1 = require("./strict-validation-hints");
 const validations_1 = require("./validations");
+const path_1 = require("./path");
+const redact_secrets_1 = require("../../utils/redact-secrets");
+const test_controller_1 = require("../test-controller");
 const request_builder_1 = require("./request-builder");
 const client_2 = require("../client");
 const idempotency_1 = require("../../utils/idempotency");
@@ -39,6 +43,7 @@ const probe_dispatch_1 = require("./request-signing/probe-dispatch");
 const webhook_receiver_1 = require("./webhook-receiver");
 const webhook_assertions_1 = require("./webhook-assertions");
 const seeding_1 = require("./seeding");
+const agent_routing_1 = require("./agent-routing");
 const types_1 = require("./types");
 const assertions_1 = require("./assertions");
 // ────────────────────────────────────────────────────────────
@@ -52,6 +57,7 @@ const SKIP_DETAILS = {
     missing_test_controller: 'Skipped: deterministic_testing phase requires comply_test_controller, which the agent did not advertise.',
     unsatisfied_contract: 'Skipped: test-kit contract is out of scope for this grading run.',
     peer_branch_taken: 'Skipped: a peer branch in the same any_of branch set already contributed the aggregation flag.',
+    peer_substituted: 'Skipped: a same-phase peer step established equivalent state via `provides_state_for`.',
 };
 const CONTROLLER_SEEDING_FAILED_DETAIL = 'Skipped: pre-flight comply_test_controller seeding failed; the agent was not populated with the storyboard fixtures the remaining phases depend on.';
 const OAUTH_NOT_ADVERTISED_DETAIL = 'Skipped: agent does not advertise OAuth — /.well-known/oauth-protected-resource returned 404 (RFC 9728 §3). API-key path must carry auth_mechanism_verified for this storyboard to pass.';
@@ -230,6 +236,170 @@ function applyBranchSetGrading(phases, phaseResults, branchSetByPhaseId, contrib
     }
     return { skippedDelta };
 }
+// ────────────────────────────────────────────────────────────
+// task_completion. context_outputs path resolution
+// ────────────────────────────────────────────────────────────
+/** Marker prefix on `context_outputs.path` that opts a capture into the
+ *  poll-tasks-get-for-the-completion-artifact resolution flow. The remainder
+ *  of the path is resolved against the artifact's `data`, not the immediate
+ *  submitted envelope. */
+const TASK_COMPLETION_PATH_PREFIX = 'task_completion.';
+/** Hard cap on how long the runner blocks one step waiting for a task to
+ *  reach terminal state. Long enough to cover most HITL approval flows that
+ *  are expected to complete inline; short enough that a stuck task surfaces
+ *  the failure on the step that authored the dependency rather than the
+ *  storyboard wall-clock budget. Override with `STORYBOARD_TASK_POLL_TIMEOUT_MS`. */
+const TASK_COMPLETION_DEFAULT_TIMEOUT_MS = 30_000;
+/** Per-poll cadence inside `pollTaskCompletion`. Scaled tight enough that
+ *  short HITL flows complete in a couple of polls; the bound is still the
+ *  outer timeout race. Override with `STORYBOARD_TASK_POLL_INTERVAL_MS`. */
+const TASK_COMPLETION_DEFAULT_POLL_INTERVAL_MS = 1_500;
+/** Defensive task_id pattern. AdCP doesn't constrain `task_id` shape on the
+ *  wire, but unbounded strings are an SSRF / log-injection lever — we cap
+ *  the length and reject control characters before the value reaches the
+ *  SDK's tasks/get JSON-RPC param. */
+const TASK_ID_MAX_LEN = 256;
+// eslint-disable-next-line no-control-regex -- intentional: reject control chars in task_id
+const TASK_ID_CONTROL_CHAR_RE = /[\x00-\x1F\x7F]/;
+/** Non-terminal task statuses that carry a `task_id` and warrant polling
+ *  the artifact for `task_completion.<inner>` captures. Per the AdCP
+ *  `tasks-get-response.json` enum, all three are explicitly non-terminal:
+ *  `submitted` (HITL or async-signed-IO), `working` ("expect completion
+ *  within 120 seconds"), and `input-required` (waiting on the buyer to
+ *  supply additional info — relevant when the storyboard test harness
+ *  satisfies the input requirement). The 30s default poll timeout still
+ *  bounds the worst case for storyboards that test these arms directly. */
+const POLL_ELIGIBLE_STATUSES = new Set(['submitted', 'working', 'input-required']);
+function isPollEligibleEnvelope(data) {
+    if (data == null || typeof data !== 'object')
+        return false;
+    const obj = data;
+    return (typeof obj.status === 'string' &&
+        POLL_ELIGIBLE_STATUSES.has(obj.status) &&
+        typeof obj.task_id === 'string' &&
+        obj.task_id.length > 0);
+}
+function isValidTaskId(taskId) {
+    if (taskId.length === 0 || taskId.length > TASK_ID_MAX_LEN)
+        return false;
+    if (TASK_ID_CONTROL_CHAR_RE.test(taskId))
+        return false;
+    return true;
+}
+function remapTaskCompletionOutputs(outputs) {
+    return outputs.map(o => {
+        if (typeof o.path === 'string' && o.path.startsWith(TASK_COMPLETION_PATH_PREFIX)) {
+            return { ...o, path: o.path.slice(TASK_COMPLETION_PATH_PREFIX.length) };
+        }
+        return o;
+    });
+}
+async function resolveTaskCompletionOutputs(taskResult, outputs, client, webhookReceiver) {
+    const hasTaskCompletionPath = outputs.some(o => typeof o.path === 'string' && o.path.startsWith(TASK_COMPLETION_PATH_PREFIX));
+    if (!hasTaskCompletionPath)
+        return { attempted: false };
+    if (!taskResult || !isPollEligibleEnvelope(taskResult.data))
+        return { attempted: false };
+    const taskId = taskResult.data.task_id;
+    if (!isValidTaskId(taskId))
+        return { attempted: false };
+    const timeoutMs = readEnvIntOrDefault(process.env['STORYBOARD_TASK_POLL_TIMEOUT_MS'], TASK_COMPLETION_DEFAULT_TIMEOUT_MS);
+    const pollIntervalMs = readEnvIntOrDefault(process.env['STORYBOARD_TASK_POLL_INTERVAL_MS'], TASK_COMPLETION_DEFAULT_POLL_INTERVAL_MS);
+    // The SDK's `pollTaskCompletion` lives on the executor — accessed via the
+    // SingleAgentClient instance the storyboard runner created in
+    // `getOrCreateClient`. The runner historically uses `client: any` for
+    // dynamic dispatch (see task-map.ts:80) so this cast doesn't widen
+    // existing surface.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- dynamic SDK access
+    const dynamicClient = client;
+    const executor = dynamicClient?.executor;
+    const agent = dynamicClient?.agent;
+    const canPoll = !!(executor?.pollTaskCompletion && agent);
+    const canWebhook = !!webhookReceiver;
+    if (!canPoll && !canWebhook)
+        return { attempted: false };
+    const racers = [];
+    // Poll path. Note: when the outer race resolves first, the SDK's
+    // `pollTaskCompletion` keeps polling internally until it observes a
+    // terminal state. The runner's outer timeout is enough to bound the
+    // *step* duration; the inner loop continuation is a known limitation
+    // pending an AbortSignal addition to the SDK.
+    if (canPoll) {
+        racers.push(executor.pollTaskCompletion(agent, taskId, pollIntervalMs).then((result) => ({
+            kind: 'poll',
+            result,
+        })));
+    }
+    // Webhook path. Per `tasks-get-response.json`, sellers MAY use webhook-
+    // only HITL completion (no polling). When a `--webhook-receiver` is
+    // active, race the receiver's `wait` (filtered by `task_id`) against
+    // the poll. The webhook payload's `result` field is the artifact's
+    // `data` (per the framework's task webhook payload shape, mirroring
+    // the HITL completion shape from `from-platform.ts`).
+    //
+    // Note: `webhook.wait` keeps an internal `setTimeout(timeout_ms)` that
+    // we can't cancel from here. When the poll wins or the outer timeout
+    // fires first, that internal timer continues until `timeout_ms`
+    // elapses. Acceptable because the receiver is process-scoped (closed
+    // on storyboard exit) and runner-owned receivers aren't injected.
+    if (webhookReceiver) {
+        racers.push(webhookReceiver
+            .wait({ body: { task_id: taskId } }, timeoutMs)
+            .then((result) => ({ kind: 'webhook', result })));
+    }
+    let timer;
+    const timeoutRacer = new Promise(resolve => {
+        timer = setTimeout(() => resolve({ kind: 'timeout' }), timeoutMs);
+        // Don't keep the event loop alive on this handle — the runner's
+        // wall-clock budget is already enforced by the storyboard runner
+        // shell, and a hung task shouldn't delay process exit by `timeoutMs`.
+        timer.unref?.();
+    });
+    racers.push(timeoutRacer);
+    try {
+        const winner = await Promise.race(racers);
+        if (winner.kind === 'timeout') {
+            return { attempted: true, timedOut: true, pollTimeoutMs: timeoutMs };
+        }
+        if (winner.kind === 'poll') {
+            const polled = winner.result;
+            if (polled.success === false)
+                return { attempted: true, taskFailed: true };
+            return { attempted: true, data: polled.data };
+        }
+        // Webhook win.
+        const waitResult = winner.result;
+        if (waitResult.timed_out) {
+            return { attempted: true, timedOut: true, pollTimeoutMs: timeoutMs };
+        }
+        const webhookBody = waitResult.webhook.body;
+        // Fail-closed on the success path: require `status === 'completed'`.
+        // The framework's `buildTaskWebhookPayload` always emits `status`, so a
+        // missing or non-completed value means either a malformed webhook or a
+        // genuine terminal-failed/canceled/rejected outcome — both should
+        // attribute to `capture_task_failed`, not silently fall through to a
+        // capture against an undefined `result`.
+        if (webhookBody?.status === 'completed') {
+            return { attempted: true, data: webhookBody.result };
+        }
+        return { attempted: true, taskFailed: true };
+    }
+    catch {
+        return { attempted: true, taskFailed: true };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function readEnvIntOrDefault(value, fallback) {
+    if (!value)
+        return fallback;
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return fallback;
+    return parsed;
+}
 function extractionFromTaskResult(taskResult) {
     if (!taskResult)
         return { path: 'none' };
@@ -242,16 +412,8 @@ function extractionFromTaskResult(taskResult) {
         return { path: 'error' };
     return taskResult.data !== undefined && taskResult.data !== null ? { path: 'structured_content' } : { path: 'none' };
 }
-/**
- * Keys whose values must never appear verbatim in a compliance report.
- * Matching is case-insensitive and structural: any property whose final
- * path segment matches is replaced with `'[redacted]'` before the payload
- * is persisted on a step result. The contract spec calls for exactly this:
- * "Secrets SHOULD be redacted with the literal string '[redacted]'".
- */
-const SECRET_KEY_PATTERN = /^(authorization|credentials?|token|api[_-]?key|password|secret|client[_-]secret|refresh[_-]token|access[_-]token|bearer|session[_-]token|session[_-]id|offering[_-]token|cookie|set[_-]cookie)$/i;
 function __redactSecretsForTest(value) {
-    return redactSecrets(value);
+    return (0, redact_secrets_1.redactSecrets)(value);
 }
 function __filterResponseHeadersForTest(headers) {
     return filterResponseHeaders(headers);
@@ -259,23 +421,6 @@ function __filterResponseHeadersForTest(headers) {
 function __defaultAuthHeadersForRawProbeForTest(options) {
     return defaultAuthHeadersForRawProbe(options);
 }
-function redactSecrets(value, depth = 0) {
-    if (depth > 32)
-        return value; // cheap cycle guard
-    if (Array.isArray(value))
-        return value.map(v => redactSecrets(v, depth + 1));
-    if (value && typeof value === 'object') {
-        const out = {};
-        for (const [k, v] of Object.entries(value)) {
-            out[k] =
-                SECRET_KEY_PATTERN.test(k) && (typeof v === 'string' || typeof v === 'number')
-                    ? '[redacted]'
-                    : redactSecrets(v, depth + 1);
-        }
-        return out;
-    }
-    return value;
-}
 /**
  * Response headers to echo on a RunnerResponseRecord. Everything else is
  * dropped — agents can (and do) include `set-cookie`, echoed `authorization`,
@@ -326,8 +471,15 @@ async function runStoryboard(agentUrlOrUrls, storyboard, options = {}) {
     // fired, and the runtime's grading depends on the invariants holding.
     // `validateStoryboardShape` is idempotent so the double-pass is safe.
     (0, loader_1.validateStoryboardShape)(storyboard);
+    // Per-specialism routing (#1066). Mutually exclusive with replica-array
+    // dispatch and `_client`. Validate the shape of `options.agents` here so
+    // misconfigured callers fail fast with a clear error rather than getting
+    // silently routed to the first URL or a stale single-agent client.
+    if (options.agents !== undefined) {
+        validateAgentsMap(agentUrlOrUrls, storyboard, options);
+    }
     const agentUrls = Array.isArray(agentUrlOrUrls) ? agentUrlOrUrls : [agentUrlOrUrls];
-    if (agentUrls.length === 0) {
+    if (!options.agents && agentUrls.length === 0) {
         throw new Error('runStoryboard: at least one agent URL required');
     }
     const isMultiInstance = agentUrls.length > 1;
@@ -350,8 +502,94 @@ async function runStoryboard(agentUrlOrUrls, storyboard, options = {}) {
         }
         return runMultiPass(agentUrls, storyboard, options);
     }
+    if (options.agents) {
+        // Project the agents map's URLs into the legacy `agentUrls` array so
+        // downstream signatures (per-step `agent_url:` records, etc.) keep
+        // working unchanged. The routing dispatcher inside
+        // `executeStoryboardPass` reads `options.agents` directly for the
+        // actual per-tool routing.
+        const projected = Object.values(options.agents).map(e => e.url);
+        return executeStoryboardPass(projected, storyboard, options, 0);
+    }
     return executeStoryboardPass(agentUrls, storyboard, options, 0);
 }
+/**
+ * Validate the shape and consistency of `StoryboardRunOptions.agents` (#1066).
+ *
+ * Catches the failure modes that would otherwise surface as confusing
+ * runtime errors deep inside discovery or dispatch:
+ *
+ *   - empty map
+ *   - `default_agent` referencing an unknown key
+ *   - `step.agent` referencing an unknown key
+ *   - co-existence with `multi_instance_strategy` (replicas, different concept)
+ *   - co-existence with `_client` (single client cannot serve multiple agents)
+ *   - first positional arg passed alongside the map (ambiguous routing intent)
+ */
+function validateAgentsMap(agentUrlOrUrls, storyboard, options) {
+    const agents = options.agents;
+    const keys = Object.keys(agents);
+    if (keys.length === 0) {
+        throw new Error('runStoryboard: `agents` is set but contains no entries. ' + 'Either remove the key or supply at least one agent.');
+    }
+    for (const key of keys) {
+        const entry = agents[key];
+        if (!entry || typeof entry.url !== 'string' || entry.url === '') {
+            throw new Error(`runStoryboard: agents['${key}'] missing a non-empty \`url\`. ` + 'Each entry must declare its endpoint URL.');
+        }
+    }
+    if (options.default_agent !== undefined && !(options.default_agent in agents)) {
+        throw new Error(`runStoryboard: \`default_agent\` "${options.default_agent}" is not a key in \`agents\`. ` +
+            `Available keys: ${keys.join(', ')}.`);
+    }
+    // Per-step `agent:` overrides must reference an agent that's actually in
+    // the map. Walk the storyboard once at entry so authoring errors surface
+    // before the first network call.
+    for (const phase of storyboard.phases ?? []) {
+        for (const step of phase.steps ?? []) {
+            if (step.agent !== undefined && !(step.agent in agents)) {
+                throw new Error(`runStoryboard: step "${step.id}" declares \`agent: "${step.agent}"\` but ` +
+                    `that key is not in the agents map. Available keys: ${keys.join(', ')}.`);
+            }
+        }
+    }
+    if (options.multi_instance_strategy !== undefined) {
+        throw new Error('runStoryboard: `agents` (per-specialism routing) is incompatible with ' +
+            '`multi_instance_strategy` (replica round-robin). They are different concepts — ' +
+            'replicas test horizontal scaling of one agent, the agents map routes per tool ' +
+            'across different agents. Use one or the other.');
+    }
+    if (options._client) {
+        throw new Error('runStoryboard: `agents` is incompatible with `_client` override. ' +
+            'A single client cannot serve multiple agents; per-agent clients are ' +
+            'constructed from the map.');
+    }
+    // Controller seeding (`prerequisites.controller_seeding: true`) currently
+    // dispatches against the FIRST per-agent client only, which works for
+    // single-tenant runs but is the wrong shape under routed mode: a
+    // cross-specialism storyboard's `fixtures:` block typically declares
+    // seeds owned by different tenants (e.g., `seed_product` for sales,
+    // `seed_signal_provider` for signals). Per-tenant seed dispatch is a
+    // larger change tracked separately. Until that lands, fail-fast and
+    // tell the operator to seed each tenant out-of-band and pass
+    // `skip_controller_seeding: true`.
+    if (storyboard.prerequisites?.controller_seeding === true && options.skip_controller_seeding !== true) {
+        throw new Error('runStoryboard: `agents` + `prerequisites.controller_seeding: true` is not yet supported. ' +
+            'Controller seeding currently targets a single tenant; cross-tenant seed routing is a ' +
+            'follow-up. Pre-seed each tenant out-of-band and pass `skip_controller_seeding: true` to ' +
+            'opt out of the runner-side seeding loop.');
+    }
+    // First positional arg must be empty when `agents` is set. Allowing a
+    // non-empty value is ambiguous: is the map authoritative, or is the
+    // positional arg a hidden default? Reject and require the caller to
+    // express intent through `agents` + `default_agent`.
+    const firstArgEmpty = agentUrlOrUrls === '' || (Array.isArray(agentUrlOrUrls) && agentUrlOrUrls.length === 0);
+    if (!firstArgEmpty) {
+        throw new Error('runStoryboard: pass `""` (or `[]`) as the first argument when using ' +
+            '`options.agents`. The agents map is authoritative for routing; mixing ' +
+            'a positional URL with the map is ambiguous.');
+    }
+}
 /**
  * Build a minimal StoryboardResult for a storyboard skipped by a
  * `requires_capability` predicate. The single synthetic step carries
@@ -529,40 +767,87 @@ function buildRequiredToolsMissingResult(agentUrls, storyboard, detail) {
 async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOffset, preSeeded) {
     const start = Date.now();
     const isMultiInstance = agentUrls.length > 1;
-    // Build one client per URL. In single-URL mode `_client` (from comply()) is
-    // honored so the shared MCP transport is reused across storyboards.
-    const clients = agentUrls.map(url => (0, client_1.getOrCreateClient)(url, options));
-    // Discover agent profile against the first instance; all instances are
-    // expected to run the same code behind a shared state store, so one probe
-    // is sufficient. For multi-instance runs, skipping N-1 redundant
-    // get_agent_info calls also keeps CI output clean.
+    const useRouting = options.agents !== undefined;
+    // Per-specialism routing builds its own clients + per-agent discovery; the
+    // legacy single/multi-instance path discovers against the first replica.
+    let clients;
+    let routingContext;
     let profile;
-    if (!options._client) {
-        const discovered = await (0, client_1.getOrDiscoverProfile)(clients[0], options);
-        // Discovery failure must surface as a HARD STORYBOARD FAILURE, not a
-        // silent empty `agentTools: []` that lets every step skip with
-        // `missing_tool`. The latter mode produces "X/X clean" summaries with
-        // 100% skipped — invisible CI failure when transport setup is broken
-        // (auth misconfig, MCP transport-fallback bugs, network policy, etc.).
-        // See: https://github.com/adcontextprotocol/adcp-client/issues/...
-        if (discovered.step.passed === false) {
+    if (useRouting) {
+        try {
+            routingContext = await (0, agent_routing_1.buildRoutingContext)(storyboard, options);
+        }
+        catch (err) {
+            const detail = err?.message ?? String(err);
+            const failedStep = {
+                step: err instanceof agent_routing_1.DiscoveryFailure
+                    ? `Discover agent capabilities (${err.agentKey})`
+                    : 'Build agent routing index',
+                passed: false,
+                duration_ms: 0,
+                error: detail,
+            };
             if (!options._client)
                 await (0, protocols_1.closeConnections)(options.protocol);
-            return buildDiscoveryFailedResult(agentUrls, storyboard, discovered.step);
+            return buildDiscoveryFailedResult(agentUrls, storyboard, failedStep);
         }
-        profile = discovered.profile;
-        // Populate agentTools and _profile from discovered profile if not already set.
-        // _profile is threaded into executeStep so capability-based skip gates
-        // (e.g. account-mode branching) can read raw_capabilities at step time.
-        if (!options.agentTools && profile?.tools) {
-            options = { ...options, agentTools: profile.tools, _profile: profile };
+        clients = [...routingContext.clients.values()];
+        // Pick the first agent's profile as the "primary" for downstream code
+        // that reads single-profile fields (library_version on per-step result
+        // records, raw_capabilities for `requires_capability`). Per-step
+        // accuracy across N agents is a follow-up; today's storyboards that
+        // use `requires_capability` are single-tenant authored.
+        profile = [...routingContext.profiles.values()][0];
+        // For `required_tools` gating, union every agent's advertised tools so
+        // a storyboard that needs ≥1 of [sync_governance, activate_signal]
+        // passes the gate when any tenant in the map serves either one.
+        const unionedTools = new Set();
+        for (const p of routingContext.profiles.values()) {
+            for (const t of p.tools ?? [])
+                unionedTools.add(t);
+        }
+        if (!options.agentTools) {
+            options = { ...options, agentTools: [...unionedTools], _profile: profile };
         }
         else if (profile && !options._profile) {
             options = { ...options, _profile: profile };
         }
     }
     else {
-        profile = options._profile;
+        // Build one client per URL. In single-URL mode `_client` (from comply()) is
+        // honored so the shared MCP transport is reused across storyboards.
+        clients = agentUrls.map(url => (0, client_1.getOrCreateClient)(url, options));
+        // Discover agent profile against the first instance; all instances are
+        // expected to run the same code behind a shared state store, so one probe
+        // is sufficient. For multi-instance runs, skipping N-1 redundant
+        // get_agent_info calls also keeps CI output clean.
+        if (!options._client) {
+            const discovered = await (0, client_1.getOrDiscoverProfile)(clients[0], options);
+            // Discovery failure must surface as a HARD STORYBOARD FAILURE, not a
+            // silent empty `agentTools: []` that lets every step skip with
+            // `missing_tool`. The latter mode produces "X/X clean" summaries with
+            // 100% skipped — invisible CI failure when transport setup is broken
+            // (auth misconfig, MCP transport-fallback bugs, network policy, etc.).
+            // See: https://github.com/adcontextprotocol/adcp-client/issues/...
+            if (discovered.step.passed === false) {
+                if (!options._client)
+                    await (0, protocols_1.closeConnections)(options.protocol);
+                return buildDiscoveryFailedResult(agentUrls, storyboard, discovered.step);
+            }
+            profile = discovered.profile;
+            // Populate agentTools and _profile from discovered profile if not already set.
+            // _profile is threaded into executeStep so capability-based skip gates
+            // (e.g. account-mode branching) can read raw_capabilities at step time.
+            if (!options.agentTools && profile?.tools) {
+                options = { ...options, agentTools: profile.tools, _profile: profile };
+            }
+            else if (profile && !options._profile) {
+                options = { ...options, _profile: profile };
+            }
+        }
+        else {
+            profile = options._profile;
+        }
     }
     // Evaluate requires_capability predicate before any phase setup.
     // When the agent explicitly declared it doesn't support what this storyboard
@@ -624,23 +909,31 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     const priorProbes = new Map();
     const contextProvenance = new Map();
     const priorA2aEnvelopes = new Map();
+    const stepRequestStarts = new Map();
     const phaseResults = [];
     let passedCount = 0;
     let failedCount = 0;
     let skippedCount = 0;
-    // Stateful-cascade flags live at storyboard scope, NOT phase scope —
-    // cross-phase storyboards (e.g. signal_marketplace/governance_denied:
-    // setup in phases 1-2, consumption in phase 3) need the cascade to
-    // survive phase boundaries. Once a stateful step in any phase failed
-    // or skipped to materialize state, every downstream stateful step
-    // stays cascade-skipped regardless of which phase it lives in.
-    let statefulFailed = false;
-    // `substitution_chain` is set when the trigger came from a
-    // deferred-and-unrescued `peer_substitutes_for` declaration (#1144) so
-    // the cascade-detail message can name the substitute(s) that didn't
-    // pass. Absent for the immediate-trip path and the legacy any-peer
-    // not_applicable path.
-    let statefulSkipTrigger = null;
+    const phaseStatefulCascades = new Map();
+    // Phase IDs in declaration order, accumulated as we iterate so the
+    // default `depends_on` resolution ("all prior phases") doesn't re-scan
+    // the storyboard. Phases push their own id at end-of-phase.
+    const priorPhaseIds = [];
+    // Helpers for per-phase cascade state.
+    const effectiveDependsOn = (phase, prior) => phase.depends_on ?? prior;
+    const cascadeForPhase = (phase, prior) => {
+        // Within-phase cascade always counts — stateful steps later in this
+        // phase depend on state from stateful steps earlier in this phase.
+        if (phaseStatefulCascades.has(phase.id)) {
+            return { tripped: true, trigger: phaseStatefulCascades.get(phase.id) ?? null };
+        }
+        for (const depId of effectiveDependsOn(phase, prior)) {
+            if (phaseStatefulCascades.has(depId)) {
+                return { tripped: true, trigger: phaseStatefulCascades.get(depId) ?? null };
+            }
+        }
+        return { tripped: false };
+    };
     // Step results whose failures the main loop added to failedCount. The
     // branch-set post-pass decrements only for entries that were actually
     // counted, so an optional phase that hit `presenceDetected` (a PRM 2xx
@@ -671,8 +964,13 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     const allSteps = flattenSteps(storyboard);
     // Inner passes always dispatch round-robin; only the outer runMultiPass
     // caller knows about the multi-pass strategy. This keeps createDispatcher's
-    // strategy parameter narrow.
-    const dispatch = createDispatcher(agentUrls, clients, 'round-robin', dispatchOffset);
+    // strategy parameter narrow. Per-specialism routing (#1066) takes the
+    // routing dispatcher path, which reads `options.agents` directly and
+    // ignores `agentUrls` ordering for selection (still uses URL list for
+    // result-record `agent_url:` echo).
+    const dispatch = routingContext && options.agents
+        ? createRoutingDispatcher(routingContext, options, options.agents)
+        : createDispatcher(agentUrls, clients, 'round-robin', dispatchOffset);
     // Resolve cross-step assertions declared on `storyboard.invariants`.
     // `resolveAssertions` throws on unknown ids — fail fast here rather than
     // silently skip, since a missing assertion means unknown conformance gaps.
@@ -816,10 +1114,12 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
         // Path (2): index of declared substitutions for this phase. Map keys
         // are target step IDs (the steps being substituted FOR); values are the
         // step IDs that declared the substitution. Built once per phase from
-        // each step's `peer_substitutes_for` field.
+        // each step's `provides_state_for` field (or the deprecated
+        // `peer_substitutes_for` synonym; the loader normalizes both onto
+        // `provides_state_for` at parse time, so reading either works).
         const phaseSubstitutes = new Map();
         for (const declaringStep of phase.steps) {
-            const decl = declaringStep.peer_substitutes_for;
+            const decl = declaringStep.provides_state_for ?? declaringStep.peer_substitutes_for;
             if (decl === undefined)
                 continue;
             const targets = Array.isArray(decl) ? decl : [decl];
@@ -836,9 +1136,15 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
         // references the leftmost step.
         let phasePendingMissingTool = null;
         // Targets actually rescued by a passing declared substitute. Populated
-        // when a step with `peer_substitutes_for: X` passes — every X in its
-        // declaration list lands here.
+        // when a step with `provides_state_for: X` (or the deprecated synonym
+        // `peer_substitutes_for: X`) passes — every X in its declaration list
+        // lands here.
         const phaseRescuedTargets = new Set();
+        // Map from rescued target id → the substitute step id that rescued it.
+        // Populated when the substitute passes; consumed at phase end to format
+        // the spec-mandated `peer_substituted` detail string. First substitute
+        // wins if multiple peers cover the same target.
+        const phaseRescueSource = new Map();
         // Stateful step IDs in the phase. Used at phase end to decide whether
         // a deferred not_applicable trigger should cascade: if the sole stateful
         // step in the phase returned not_applicable AND there were no peers that
@@ -940,12 +1246,18 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
             // reason is `missing_tool` (a benign, passed: true skip) —
             // not `prerequisite_failed` (a failed skip). This distinguishes
             // "this agent has a real setup bug" from "this agent doesn't
-            // claim this surface, by design" (adcp-client#1169).
+            // claim this surface, by design" (adcp-client#1169 / #1171).
             //
             // Uses resolveTaskName so that $test_kit.* steps are checked
             // against the resolved concrete task name, not the template
             // string (which would never be in agentTools).
-            if (statefulFailed && step.stateful) {
+            //
+            // Per-phase cascade scoping (#1161): consults `phase.depends_on`
+            // (default: all prior phases) plus the current phase's own
+            // within-phase cascade state. Replaces the storyboard-scope
+            // `statefulFailed` boolean.
+            const cascade = step.stateful ? cascadeForPhase(phase, priorPhaseIds) : { tripped: false };
+            if (cascade.tripped && step.stateful) {
                 const resolvedTask = resolveTaskName(step, options);
                 if (options.agentTools && resolvedTask && !options.agentTools.includes(resolvedTask)) {
                     const toolDetail = `Agent did not advertise tool "${resolvedTask}"; agent tools: [${options.agentTools.join(', ')}].`;
@@ -969,10 +1281,11 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
                     skippedCount++;
                     continue;
                 }
-                const detail = statefulSkipTrigger
-                    ? statefulSkipTrigger.substitution_chain
-                        ? `Skipped: prior stateful step "${statefulSkipTrigger.stepId}" skipped (${statefulSkipTrigger.reason}); ${statefulSkipTrigger.substitution_chain}; state never materialized.`
-                        : `Skipped: prior stateful step "${statefulSkipTrigger.stepId}" skipped (${statefulSkipTrigger.reason}); state never materialized.`
+                const trigger = cascade.trigger;
+                const detail = trigger
+                    ? trigger.substitution_chain
+                        ? `Skipped: prior stateful step "${trigger.stepId}" skipped (${trigger.reason}); ${trigger.substitution_chain}; state never materialized.`
+                        : `Skipped: prior stateful step "${trigger.stepId}" skipped (${trigger.reason}); state never materialized.`
                     : 'Skipped: prior stateful step failed.';
                 stepResults.push({
                     storyboard_id: storyboard.id,
@@ -994,7 +1307,38 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
                 phasePassed = false;
                 continue;
             }
-            const assignment = dispatch.nextFor(step);
+            let assignment;
+            try {
+                assignment = dispatch.nextFor(step);
+            }
+            catch (err) {
+                // Routing failures land here when no agent in the map serves a
+                // step's tool's protocol. Build-time conflict detection already
+                // catches the multi-claim case, so this branch covers genuine
+                // coverage gaps (storyboard authored a tool the topology can't
+                // serve) and unmapped tools without a `default_agent`. Render as
+                // a failed step with the routing error verbatim so the report
+                // tells the operator exactly what's missing.
+                const detail = err instanceof agent_routing_1.RoutingError ? err.message : (err?.message ?? String(err));
+                const failed = {
+                    storyboard_id: storyboard.id,
+                    step_id: step.id,
+                    phase_id: phase.id,
+                    title: step.title,
+                    task: step.task,
+                    passed: false,
+                    duration_ms: 0,
+                    validations: [],
+                    context,
+                    error: detail,
+                    extraction: { path: 'none' },
+                };
+                stepResults.push(failed);
+                priorStepResults.set(step.id, failed);
+                failedCount++;
+                phasePassed = false;
+                continue;
+            }
             const rawResult = await executeStep(assignment.client, step, phase.id, context, allSteps, options, {
                 contributions,
                 priorStepResults,
@@ -1004,10 +1348,15 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
                 runnerVars,
                 contextProvenance,
                 priorA2aEnvelopes,
+                stepRequestStarts,
                 agentLibraryVersion: profile?.library_version,
             });
             const result = { ...rawResult, storyboard_id: storyboard.id };
-            if (isMultiInstance) {
+            if (isMultiInstance || useRouting) {
+                // Echo per-step routing on the result so JUnit/CI consumers and
+                // bug reports show which agent served which tool. In routed mode
+                // every step gets the field; in replica round-robin only when
+                // there are 2+ URLs.
                 result.agent_url = assignment.agentUrl;
                 result.agent_index = assignment.instanceIndex + 1;
             }
@@ -1118,13 +1467,15 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
                             }
                         }
                         else {
-                            statefulFailed = true;
-                            // Record provenance for the cascade detail message. First trip
-                            // wins — subsequent triggers don't overwrite, since the cascade
-                            // text references the originating diagnostic (the leftmost
+                            // Trip this phase's cascade. First trip wins — subsequent
+                            // triggers don't overwrite, since the cascade text
+                            // references the originating diagnostic (the leftmost
                             // missing-state stateful step in the phase).
-                            if (statefulSkipTrigger === null) {
-                                statefulSkipTrigger = { stepId: step.id, reason: result.skip_reason ?? 'missing_tool' };
+                            if (!phaseStatefulCascades.has(phase.id)) {
+                                phaseStatefulCascades.set(phase.id, {
+                                    stepId: step.id,
+                                    reason: result.skip_reason ?? 'missing_tool',
+                                });
                             }
                         }
                     }
@@ -1163,14 +1514,20 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
                 if (step.stateful) {
                     phaseEstablishedStatefulState = true;
                     // Path (2) rescue tracking: a passing step that declared
-                    // `peer_substitutes_for: X` rescues X. Recorded against every
+                    // `provides_state_for: X` (or the deprecated synonym
+                    // `peer_substitutes_for`) rescues X. Recorded against every
                     // declared target so phase-end resolution sees the target as
                     // covered even if its skip arrives later in the loop.
-                    const decl = step.peer_substitutes_for;
+                    const decl = step.provides_state_for ?? step.peer_substitutes_for;
                     if (decl !== undefined) {
                         const targets = Array.isArray(decl) ? decl : [decl];
                         for (const target of targets) {
                             phaseRescuedTargets.add(target);
+                            // Track the rescuing substitute's id so phase-end can format
+                            // the contract-mandated `peer_substituted` detail string.
+                            if (!phaseRescueSource.has(target)) {
+                                phaseRescueSource.set(target, step.id);
+                            }
                         }
                     }
                 }
@@ -1188,13 +1545,13 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
                     countedAsFailed.add(result);
                 }
                 if (step.stateful) {
-                    statefulFailed = true;
                     // Real failure takes precedence over a prior skip-trigger in
                     // the cascade detail message — failures are the worse
                     // diagnostic, so downstream cascade-skipped steps should
                     // reference the failure rather than the earlier benign-ish
-                    // missing-state skip.
-                    statefulSkipTrigger = null;
+                    // missing-state skip. `null` trigger encodes "real failure,
+                    // detail says 'prior stateful step failed'."
+                    phaseStatefulCascades.set(phase.id, null);
                 }
                 // In multi-instance mode, annotate the failure with the cross-instance
                 // attribution block so CI readers pattern-match it as a deployment bug.
@@ -1210,46 +1567,70 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
         //
         // Cascade fires ONLY when there was at least one other stateful step in
         // the phase that could have served as a substitute — i.e. the phase had
-        // peer steps, but none of them established state. A peer that passed
-        // (e.g. `list_accounts` substituting for an explicit-mode `sync_accounts`)
-        // cancels the trigger entirely. A peer that *failed* already tripped
-        // `statefulFailed` at the failure site with the worse-diagnostic real-
-        // failure message; we defer to that and don't overwrite.
+        // peer steps, but none of them established state (#1146). A peer that
+        // passed (e.g. `list_accounts` substituting for an explicit-mode
+        // `sync_accounts`) cancels the trigger entirely. A peer that *failed*
+        // already tripped this phase's cascade at the failure site with the
+        // worse-diagnostic real-failure message; we defer to that and don't
+        // overwrite.
         //
         // When the not_applicable step was the SOLE stateful step in the phase
         // (no peers existed at all), the cascade does NOT fire. That platform
         // simply doesn't use this sync pathway — which is valid. Cascading on a
-        // sole not_applicable would incorrectly penalise adapters like citrusad,
-        // amazon, criteo, and google that manage account state implicitly and
-        // have no list_accounts peer in the account_setup phase (adcp-client#1144).
-        if (phasePendingNotApplicable && !phaseEstablishedStatefulState && !statefulFailed) {
+        // sole not_applicable would incorrectly penalise adapters that manage
+        // state implicitly and have no list_accounts peer (adcp-client#1146).
+        if (phasePendingNotApplicable && !phaseEstablishedStatefulState && !phaseStatefulCascades.has(phase.id)) {
             const hadStatefulPeers = phaseStatefulStepIds.some(id => id !== phasePendingNotApplicable.stepId);
             if (hadStatefulPeers) {
-                statefulFailed = true;
-                if (statefulSkipTrigger === null) {
-                    statefulSkipTrigger = phasePendingNotApplicable;
-                }
+                phaseStatefulCascades.set(phase.id, phasePendingNotApplicable);
             }
         }
         // Phase-end cascade resolution for deferred `missing_tool` triggers
         // (#1144). A stateful step that skipped with a hard-missing reason
-        // and had at least one declared substitute (`peer_substitutes_for`)
-        // was deferred above. If none of the declared substitutes passed,
-        // the substitution path failed to establish state — promote to a
-        // hard cascade with a detail message that names the substitute(s)
-        // tried so adopters reading the report see the substitution chain
-        // rather than a bare `missing_tool` cascade origin.
-        if (phasePendingMissingTool && !phaseRescuedTargets.has(phasePendingMissingTool.stepId) && !statefulFailed) {
-            statefulFailed = true;
-            if (statefulSkipTrigger === null) {
-                const subs = phasePendingMissingTool.substitutes;
-                const subsList = subs.length === 1 ? `"${subs[0]}"` : subs.map(s => `"${s}"`).join(', ');
-                statefulSkipTrigger = {
-                    stepId: phasePendingMissingTool.stepId,
-                    reason: phasePendingMissingTool.reason,
-                    substitution_chain: `declared substitute ${subsList} did not pass`,
-                };
-            }
+        // and had at least one declared substitute (`provides_state_for`,
+        // formerly `peer_substitutes_for`) was deferred above. If none of
+        // the declared substitutes passed, the substitution path failed to
+        // establish state — promote to a hard cascade with a detail message
+        // that names the substitute(s) tried so adopters reading the report
+        // see the substitution chain rather than a bare `missing_tool`
+        // cascade origin.
+        if (phasePendingMissingTool &&
+            !phaseRescuedTargets.has(phasePendingMissingTool.stepId) &&
+            !phaseStatefulCascades.has(phase.id)) {
+            const subs = phasePendingMissingTool.substitutes;
+            const subsList = subs.length === 1 ? `"${subs[0]}"` : subs.map(s => `"${s}"`).join(', ');
+            phaseStatefulCascades.set(phase.id, {
+                stepId: phasePendingMissingTool.stepId,
+                reason: phasePendingMissingTool.reason,
+                substitution_chain: `declared substitute ${subsList} did not pass`,
+            });
+        }
+        // Phase-end re-grading for rescued targets (adcp#3734, AdCP 3.0.3+).
+        // When a deferred `missing_tool` / `missing_test_controller` skip was
+        // rescued by a passing same-phase substitute, the spec mandates the
+        // target be re-graded with `skip_reason: 'peer_substituted'` and the
+        // detail string `"<target_step_id> state provided by <phase_id>.<substitute_step_id>"`
+        // — see `runner-output-contract.yaml` > `skip_result.reasons.peer_substituted`.
+        // Without this re-grading the target keeps its original `missing_tool`
+        // grade, which is misleading: state DID materialize, just via a
+        // declared substitute path. Tracked: adcp-client#1267.
+        for (const target of phaseRescuedTargets) {
+            const sourceId = phaseRescueSource.get(target);
+            if (!sourceId)
+                continue;
+            const targetResult = stepResults.find(r => r.step_id === target);
+            if (!targetResult || !targetResult.skipped)
+                continue;
+            // Only re-grade hard-missing-state skips. Other skip reasons (e.g.
+            // `prerequisite_failed`, `peer_branch_taken`) on the target are
+            // outside the substitute-rescue contract. Uses the same helper as
+            // the deferral path (line ~1269 above) so the two sides stay in
+            // lockstep when a future RunnerSkipReason joins the family.
+            if (!isHardMissingStateSkipReason(targetResult.skip_reason))
+                continue;
+            const detail = `${target} state provided by ${phase.id}.${sourceId}`;
+            targetResult.skip_reason = 'peer_substituted';
+            targetResult.skip = { reason: 'peer_substituted', detail };
         }
         phaseResults.push({
             phase_id: phase.id,
@@ -1258,6 +1639,9 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
             steps: stepResults,
             duration_ms: Date.now() - phaseStart,
         });
+        // Accumulate phase id for default `depends_on` resolution in the next
+        // iteration — phases declared later see this one as a prior phase.
+        priorPhaseIds.push(phase.id);
     }
     // Branch-set post-pass: phases in a branch set (explicit `branch_set:`
     // declaration or implicit detection via shared `contributes_to` + a later
@@ -1313,6 +1697,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
         phaseResults.unshift(seedingPhaseResult);
     const schemasUsed = collectSchemasUsed(phaseResults);
     const strictSummary = summarizeStrictValidation(phaseResults);
+    const validationsNotApplicable = countValidationsNotApplicable(phaseResults);
     const result = {
         storyboard_id: storyboard.id,
         storyboard_title: storyboard.title,
@@ -1322,6 +1707,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
         // individually); the aggregating wrapper relabels the top-level result
         // `multi-pass`.
         ...(isMultiInstance && { multi_instance_strategy: 'round-robin' }),
+        ...(routingContext && { agent_map: { ...routingContext.agentMap } }),
         overall_passed: failedCount === 0 && requiredPhasesPassed && !assertionsFailed,
         phases: phaseResults,
         context,
@@ -1329,6 +1715,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
         passed_count: passedCount,
         failed_count: failedCount,
         skipped_count: skippedCount,
+        ...(validationsNotApplicable > 0 ? { validations_not_applicable: validationsNotApplicable } : {}),
         tested_at: new Date().toISOString(),
         ...(schemasUsed.length > 0 ? { schemas_used: schemasUsed } : {}),
         ...(assertionResults.length > 0 ? { assertions: assertionResults } : {}),
@@ -1392,6 +1779,7 @@ async function runMultiPass(agentUrls, storyboard, options) {
             passed_count: result.passed_count,
             failed_count: result.failed_count,
             skipped_count: result.skipped_count,
+            ...(result.validations_not_applicable ? { validations_not_applicable: result.validations_not_applicable } : {}),
             duration_ms: result.total_duration_ms,
         });
     }
@@ -1400,6 +1788,7 @@ async function runMultiPass(agentUrls, storyboard, options) {
     const passed = passes.reduce((sum, p) => sum + p.passed_count, 0);
     const failed = passes.reduce((sum, p) => sum + p.failed_count, 0);
     const skipped = passes.reduce((sum, p) => sum + p.skipped_count, 0);
+    const notApplicable = passes.reduce((sum, p) => sum + (p.validations_not_applicable ?? 0), 0);
     const schemasUsed = passResults.flatMap(r => r.schemas_used ?? []);
     const schemasDedup = [...new Map(schemasUsed.map(s => [s.schema_id, s])).values()];
     // Assertions are scoped per-pass — each pass's runner resolved them
@@ -1421,6 +1810,7 @@ async function runMultiPass(agentUrls, storyboard, options) {
         passed_count: passed,
         failed_count: failed,
         skipped_count: skipped,
+        ...(notApplicable > 0 ? { validations_not_applicable: notApplicable } : {}),
         tested_at: new Date().toISOString(),
         ...(schemasDedup.length > 0 ? { schemas_used: schemasDedup } : {}),
         ...(assertionsAgg.length > 0 ? { assertions: assertionsAgg } : {}),
@@ -1431,6 +1821,27 @@ async function runMultiPass(agentUrls, storyboard, options) {
  * from every validation result with a schema_id; dropping empties keeps
  * the list proportional to what actually ran.
  */
+/**
+ * Count validation results graded `not_applicable` across every step. Per
+ * runner-output-contract.yaml v2.0.0 these come from the forward-compat
+ * default in the validation dispatcher: when a storyboard declares an
+ * authored `check` value the runner does not implement, the dispatcher
+ * grades it `passed: true, not_applicable: true` rather than failing the
+ * step. Surfacing the count separately lets consumers distinguish
+ * "runner is older than the storyboard" from clean passes.
+ */
+function countValidationsNotApplicable(phases) {
+    let n = 0;
+    for (const phase of phases) {
+        for (const step of phase.steps) {
+            for (const v of step.validations) {
+                if (v.not_applicable)
+                    n++;
+            }
+        }
+    }
+    return n;
+}
 function collectSchemasUsed(phases) {
     const seen = new Set();
     const out = [];
@@ -1566,14 +1977,21 @@ async function runStoryboardStep(agentUrl, storyboard, stepId, options = {}) {
     const context = { ...options.context };
     if (options.context)
         (0, context_1.forwardAliasCache)(options.context, context);
-    const webhookReceiver = options.webhook_receiver
-        ? await (0, webhook_receiver_1.createWebhookReceiver)({
-            ...(options.webhook_receiver.mode && { mode: options.webhook_receiver.mode }),
-            ...(options.webhook_receiver.host !== undefined && { host: options.webhook_receiver.host }),
-            ...(options.webhook_receiver.port !== undefined && { port: options.webhook_receiver.port }),
-            ...(options.webhook_receiver.public_url !== undefined && { public_url: options.webhook_receiver.public_url }),
-        })
-        : undefined;
+    // `_webhookReceiver` is a test-only injection point; production callers
+    // pass `webhook_receiver` and the runner constructs the listener.
+    const injectedReceiver = options._webhookReceiver;
+    const webhookReceiver = injectedReceiver ??
+        (options.webhook_receiver
+            ? await (0, webhook_receiver_1.createWebhookReceiver)({
+                ...(options.webhook_receiver.mode && { mode: options.webhook_receiver.mode }),
+                ...(options.webhook_receiver.host !== undefined && { host: options.webhook_receiver.host }),
+                ...(options.webhook_receiver.port !== undefined && { port: options.webhook_receiver.port }),
+                ...(options.webhook_receiver.public_url !== undefined && {
+                    public_url: options.webhook_receiver.public_url,
+                }),
+            })
+            : undefined);
+    const ownsWebhookReceiver = !injectedReceiver && !!webhookReceiver;
     const runnerVars = (0, context_1.createRunnerVariables)({
         ...(webhookReceiver && { webhookBase: webhookReceiver.base_url }),
     });
@@ -1583,7 +2001,7 @@ async function runStoryboardStep(agentUrl, storyboard, stepId, options = {}) {
     const allSteps = flattenSteps(storyboard);
     const found = allSteps.find(s => s.step.id === stepId);
     if (!found) {
-        if (webhookReceiver)
+        if (ownsWebhookReceiver && webhookReceiver)
             await webhookReceiver.close();
         throw new Error(`Step "${stepId}" not found in storyboard "${storyboard.id}". ` +
             `Available steps: ${allSteps.map(s => s.step.id).join(', ')}`);
@@ -1601,12 +2019,13 @@ async function runStoryboardStep(agentUrl, storyboard, stepId, options = {}) {
         runnerVars,
         contextProvenance,
         priorA2aEnvelopes: new Map(),
+        stepRequestStarts: new Map(),
         agentLibraryVersion: profile?.library_version,
     });
     if (!options._client) {
         await (0, protocols_1.closeConnections)(options.protocol);
     }
-    if (webhookReceiver)
+    if (ownsWebhookReceiver && webhookReceiver)
         await webhookReceiver.close();
     return result;
 }
@@ -1620,6 +2039,7 @@ client, step, phaseId, context, allSteps, options, state) {
         priorProbes: new Map(),
         agentUrl: '',
         contextProvenance: new Map(),
+        stepRequestStarts: new Map(),
     };
     // HTTP probe tasks bypass the MCP client entirely.
     if (probes_1.PROBE_TASKS.has(step.task)) {
@@ -1761,6 +2181,19 @@ client, step, phaseId, context, allSteps, options, state) {
     // prevents session-key divergence across create/get/update/delete steps
     // when individual builders or sample_request YAML omit brand.
     request = applyBrandInvariant(request, options, effectiveStep.task);
+    // Per-run sandbox-bypass hint (#841). When the operator passes
+    // `--no-sandbox` (or sets `disable_sandbox: true` programmatically), the
+    // runner stamps `ext.adcp.disable_sandbox: true` on every outgoing
+    // request. Adopters that read this field bypass their internal sandbox
+    // routing — env-var fallbacks, brand-domain heuristics, fixture
+    // substitutes — and exercise their real adapter path. Agents that
+    // don't recognize the field ignore it (per spec, `ext` is accepted
+    // without error and not echoed). Gated on the schema check that
+    // `applyBrandInvariant` uses for `account` and `brand` so tools whose
+    // `additionalProperties: false` schema would reject `ext` aren't broken.
+    if (options.disable_sandbox === true) {
+        request = applyDisableSandboxHint(request, effectiveStep.task);
+    }
     // Mutating AdCP requests require idempotency_key per spec. Storyboard
     // yamls generally omit it so authors don't have to remember it on every
     // mutating step — mint one here on the runner's behalf, matching how a
@@ -1773,7 +2206,32 @@ client, step, phaseId, context, allSteps, options, state) {
     const unresolvedVars = findUnresolvedContextVars(request);
     if (unresolvedVars.length > 0 && !step.expect_error) {
         const next = getNextStepPreview(step.id, allSteps, context, runState.runnerVars);
-        const detail = `Skipped: unresolved context variables from prior steps: ${unresolvedVars.join(', ')}.`;
+        const detail = `Skipped: unresolved context variables from prior steps: ${unresolvedVars.map(v => v.key).join(', ')}.`;
+        // Per runner-output-contract.yaml v2.0.0, a skipped consumer step MUST
+        // carry an `unresolved_substitution` validation result for each missing
+        // token — `expected` is the token string, `actual` / `json_pointer` /
+        // `request` / `response` are null (pre-wire failure; no response payload
+        // exists). Surfacing this as a validation rather than only a skip detail
+        // keeps the runner-output contract's "failed/skipped steps include at
+        // least one validation result" invariant intact and lets dashboards
+        // attribute the cascade origin without parsing the skip message.
+        const seenTokens = new Set();
+        const synthesized = [];
+        for (const v of unresolvedVars) {
+            if (seenTokens.has(v.token))
+                continue;
+            seenTokens.add(v.token);
+            synthesized.push({
+                check: 'unresolved_substitution',
+                passed: false,
+                description: `request token "${v.token}" did not resolve — prior step did not populate context.${v.key}`,
+                json_pointer: null,
+                expected: v.token,
+                actual: null,
+                schema_id: null,
+                schema_url: null,
+            });
+        }
         return {
             step_id: step.id,
             phase_id: phaseId,
@@ -1784,7 +2242,7 @@ client, step, phaseId, context, allSteps, options, state) {
             skip_reason: 'prerequisite_failed',
             skip: buildSkip('prerequisite_failed', detail),
             duration_ms: 0,
-            validations: [],
+            validations: synthesized,
             context,
             error: detail,
             next,
@@ -1821,6 +2279,14 @@ client, step, phaseId, context, allSteps, options, state) {
     let httpResult;
     let responseRecord;
     let a2aEnvelope;
+    // Capture the ISO timestamp immediately before the step's AdCP request
+    // dispatch. `upstream_traffic` validations use this as the default
+    // `since_timestamp` window bound when querying the controller. Recorded
+    // on `runState.stepRequestStarts` so a later step's `since: prior_step_id`
+    // reference can resolve back to it.
+    const requestStartIso = new Date().toISOString();
+    if (runState.stepRequestStarts)
+        runState.stepRequestStarts.set(step.id, requestStartIso);
     if (useRawProbe) {
         const started = Date.now();
         try {
@@ -1842,7 +2308,7 @@ client, step, phaseId, context, allSteps, options, state) {
             const filteredHeaders = filterResponseHeaders(httpResult.headers);
             responseRecord = {
                 transport: 'mcp',
-                payload: redactSecrets(httpResult.body),
+                payload: (0, redact_secrets_1.redactSecrets)(httpResult.body),
                 ...(typeof httpResult.status === 'number' ? { status: httpResult.status } : {}),
                 ...(filteredHeaders && { headers: filteredHeaders }),
                 duration_ms: durationMs,
@@ -1902,7 +2368,7 @@ client, step, phaseId, context, allSteps, options, state) {
         if (taskResult) {
             responseRecord = {
                 transport: options.protocol === 'a2a' ? 'a2a' : 'mcp',
-                payload: redactSecrets(taskResult.data ?? taskResult.error ?? null),
+                payload: (0, redact_secrets_1.redactSecrets)(taskResult.data ?? taskResult.error ?? null),
                 duration_ms: stepResult.duration_ms,
             };
         }
@@ -1910,7 +2376,7 @@ client, step, phaseId, context, allSteps, options, state) {
     const requestRecord = {
         transport: useRawProbe ? 'mcp' : options.protocol === 'a2a' ? 'a2a' : 'mcp',
         operation: effectiveStep.task,
-        payload: redactSecrets(request),
+        payload: (0, redact_secrets_1.redactSecrets)(request),
         ...(runState.agentUrl ? { url: runState.agentUrl } : {}),
     };
     // Feature-unsupported or unknown-tool errors → treat as skip
@@ -1968,6 +2434,14 @@ client, step, phaseId, context, allSteps, options, state) {
             }
             return resolved;
         });
+        // Pre-fetch upstream_traffic data: any `check: upstream_traffic`
+        // validation needs the controller's `query_upstream_traffic` response,
+        // but the validation dispatcher is synchronous. Async-fetch here once
+        // per unique `since_timestamp` window so the validator can grade
+        // synchronously. Adopters who don't advertise the scenario short-
+        // circuit to a single `advertised: false` marker and every
+        // upstream_traffic check on the step grades not_applicable.
+        const upstreamTraffic = await prefetchUpstreamTraffic(step.id, resolvedValidations, client, options, runState, requestStartIso);
         const vctx = {
             taskName: effectiveStep.task,
             ...(taskResult && { taskResult }),
@@ -1979,6 +2453,8 @@ client, step, phaseId, context, allSteps, options, state) {
             ...(responseRecord && { response: responseRecord }),
             storyboardContext: context,
             ...(a2aEnvelope && { a2aEnvelope }),
+            ...(upstreamTraffic && { upstreamTraffic }),
+            ...(step.sample_request && { storyboardStep: { sample_request: step.sample_request } }),
             ...(() => {
                 // Walk back through the run's captured A2A envelopes and use
                 // the most recent prior step's envelope as the comparison
@@ -2001,7 +2477,6 @@ client, step, phaseId, context, allSteps, options, state) {
         };
         validations = (0, validations_1.runValidations)(resolvedValidations, vctx);
     }
-    const allValidationsPassed = validations.every(v => v.passed);
     // Persist the captured A2A envelope keyed by step id so cross-step
     // validators (`a2a_context_continuity`) on subsequent steps can
     // compare against it. Only fires when this step actually captured
@@ -2038,14 +2513,83 @@ client, step, phaseId, context, allSteps, options, state) {
     // ensures the minted value from any same-step $generate:…#<key> inline
     // substitution is visible here.
     if (step.context_outputs?.length) {
-        const explicit = (0, context_1.applyContextOutputsWithProvenance)(hasData && taskResult ? taskResult.data : undefined, step.context_outputs, step.id, effectiveStep.task, updatedContext);
+        // Resolve `task_completion.<path>` outputs against the eventual task
+        // artifact rather than the immediate response. When the immediate
+        // response is a submitted-arm envelope (HITL / async-signed-IO flows),
+        // the seller-assigned IDs only exist on the completion artifact — the
+        // sync-shape path resolves to nothing and the storyboard fails on
+        // `capture_path_not_resolvable` for a value the seller correctly
+        // produces, just on a later message. The `task_completion.` prefix is
+        // an explicit author-side opt-in: "poll tasks/get for terminal status,
+        // then resolve the rest of the path against the artifact data."
+        //
+        // Polling failures (timeout, terminal failed/canceled/rejected) emit
+        // `capture_poll_timeout` instead of recycling
+        // `capture_path_not_resolvable` so the failure-class is distinct from
+        // the original "field absent in immediate response" diagnostic.
+        const taskCompletionResolution = await resolveTaskCompletionOutputs(taskResult, step.context_outputs, client, runState.webhookReceiver);
+        // `'data' in resolution` distinguishes "polled, artifact had no data"
+        // (use undefined → outputs fail with capture_path_not_resolvable) from
+        // "did not poll" (fall back to the immediate response data).
+        const extractionData = 'data' in taskCompletionResolution
+            ? taskCompletionResolution.data
+            : hasData && taskResult
+                ? taskResult.data
+                : undefined;
+        const remappedOutputs = remapTaskCompletionOutputs(step.context_outputs);
+        const explicit = (0, context_1.applyContextOutputsWithProvenance)(extractionData, remappedOutputs, step.id, effectiveStep.task, updatedContext);
         Object.assign(updatedContext, explicit.values);
         if (runState.contextProvenance) {
             for (const [key, entry] of Object.entries(explicit.provenance)) {
                 runState.contextProvenance.set(key, entry);
             }
         }
+        // Per runner-output-contract.yaml v2.0.0, a `context_outputs.path` that
+        // resolves to absent / null / "" is a producer-side conformance failure
+        // on THIS step (capture_path_not_resolvable), not on a downstream
+        // consumer. Synthesize a failed validation_result so the failure is
+        // attributed where it actually originated. Emitted regardless of whether
+        // the step's authored validations passed — a clean response_schema with
+        // a failed capture is the exact case adcp#3796 set out to fix.
+        if (explicit.failures && explicit.failures.length > 0) {
+            for (const failure of explicit.failures) {
+                const wasTaskCompletion = step.context_outputs.some(o => o.key === failure.key && typeof o.path === 'string' && o.path.startsWith(TASK_COMPLETION_PATH_PREFIX));
+                const pollTimedOut = wasTaskCompletion && taskCompletionResolution.timedOut === true;
+                const taskFailed = wasTaskCompletion && taskCompletionResolution.taskFailed === true;
+                const originalPath = wasTaskCompletion ? `${TASK_COMPLETION_PATH_PREFIX}${failure.path}` : failure.path;
+                let check;
+                let description;
+                if (pollTimedOut) {
+                    check = 'capture_poll_timeout';
+                    description = `context_outputs path "${originalPath}" (key "${failure.key}") did not resolve before tasks/get poll timed out (${taskCompletionResolution.pollTimeoutMs}ms)`;
+                }
+                else if (taskFailed) {
+                    check = 'capture_task_failed';
+                    description = `context_outputs path "${originalPath}" (key "${failure.key}") did not resolve because the task reached a terminal failed/canceled/rejected state`;
+                }
+                else {
+                    check = 'capture_path_not_resolvable';
+                    description = `context_outputs path "${originalPath}" (key "${failure.key}") did not resolve to a usable value`;
+                }
+                const synthetic = {
+                    check,
+                    passed: false,
+                    description,
+                    json_pointer: (0, path_1.toJsonPointer)(failure.path),
+                    expected: originalPath,
+                    actual: failure.resolved,
+                    schema_id: null,
+                    schema_url: null,
+                    ...(requestRecord && { request: requestRecord }),
+                    ...(responseRecord && { response: responseRecord }),
+                };
+                validations.push(synthetic);
+            }
+        }
     }
+    // Re-evaluate after any synthesized capture-failure validations are
+    // appended — the step's overall pass/fail must reflect them.
+    const allValidationsPassedFinal = validations.every(v => v.passed);
     // Emit context-value-rejected hints when the seller's error lists the
     // values it would have accepted and the rejected request value traces
     // back to a prior-step $context.* write. Non-fatal: doesn't flip
@@ -2070,7 +2614,7 @@ client, step, phaseId, context, allSteps, options, state) {
     // Hints trace to context that existed BEFORE this step's own writes,
     // since the rejected value can't have come from this step's own
     // extraction.
-    const stepFailed = !(passed && allValidationsPassed);
+    const stepFailed = !(passed && allValidationsPassedFinal);
     const contextRejectionHints = stepFailed && runState.contextProvenance
         ? (0, rejection_hints_1.detectContextRejectionHints)(taskResult, request, context, runState.contextProvenance, effectiveStep.task)
         : [];
@@ -2112,13 +2656,13 @@ client, step, phaseId, context, allSteps, options, state) {
         phase_id: phaseId,
         title: step.title,
         task: step.task,
-        passed: passed && allValidationsPassed,
+        passed: passed && allValidationsPassedFinal,
         expect_error: step.expect_error,
         duration_ms: stepResult.duration_ms,
         // Legacy `response` field (new code reads `response_record`).
         // Redact in case a downstream consumer still keys off it; the
         // modern `response_record.payload` path is already redacted.
-        response: redactSecrets(taskResult?.data),
+        response: (0, redact_secrets_1.redactSecrets)(taskResult?.data),
         validations,
         context: updatedContext,
         ...(runState.contextProvenance &&
@@ -2179,7 +2723,7 @@ async function executeProbeStep(step, phaseId, context, allSteps, options, runSt
     const responseRecord = httpResult
         ? {
             transport: 'http',
-            payload: redactSecrets(httpResult.body),
+            payload: (0, redact_secrets_1.redactSecrets)(httpResult.body),
             status: httpResult.status,
             ...(filteredProbeHeaders && { headers: filteredProbeHeaders }),
             duration_ms: duration,
@@ -2323,14 +2867,14 @@ function parseLastA2aMessageSendCapture(captures) {
     // `envelope.result` keeps presence-of-key fidelity for validators
     // that need to distinguish "result was null" from "result was
     // omitted". Both paths run through `redactSecrets`.
-    const redactedResult = envelope.result !== undefined ? redactSecrets(envelope.result) : null;
+    const redactedResult = envelope.result !== undefined ? (0, redact_secrets_1.redactSecrets)(envelope.result) : null;
     return {
         result: redactedResult,
         envelope: {
             ...(envelope.jsonrpc !== undefined && { jsonrpc: envelope.jsonrpc }),
             ...(envelope.id !== undefined && { id: envelope.id }),
             ...(envelope.result !== undefined && { result: redactedResult }),
-            ...(envelope.error !== undefined && { error: redactSecrets(envelope.error) }),
+            ...(envelope.error !== undefined && { error: (0, redact_secrets_1.redactSecrets)(envelope.error) }),
         },
         http_status: cap.status,
     };
@@ -2572,7 +3116,17 @@ function applyBrandInvariant(request, options, taskName) {
             const acct = existingAccount;
             const isNaturalKeyVariant = 'brand' in acct || 'operator' in acct;
             if (isNaturalKeyVariant) {
-                result.account = { ...acct, brand };
+                const merged = { ...acct, brand };
+                // The natural-key arm of AccountReference requires `operator` (per
+                // schemas/cache/{version}/core/account-ref.json). A fixture or earlier
+                // context-extraction step that produced `{brand, sandbox}` without
+                // operator would otherwise be passed through and rejected by a
+                // strict-validating seller. Default operator to brand.domain — same
+                // convention `resolveAccount` uses for synthetic refs.
+                if (typeof merged.operator !== 'string' && typeof brand.domain === 'string') {
+                    merged.operator = brand.domain;
+                }
+                result.account = merged;
             }
         }
     }
@@ -2584,6 +3138,44 @@ function applyBrandInvariant(request, options, taskName) {
     }
     return result;
 }
+/**
+ * Inject `ext.adcp.disable_sandbox: true` into the outgoing request when the
+ * operator passed `--no-sandbox` (or `disable_sandbox: true` programmatically).
+ * Issue #841.
+ *
+ * `ext` is the spec-blessed channel for read-by-agent extensions and is
+ * accepted-without-error on every tool, so the schema check is conservative
+ * — only inject when the tool's request schema permits a top-level `ext`
+ * field. Tools with `additionalProperties: false` that don't list `ext`
+ * would fail strict AJV validation otherwise.
+ *
+ * Merging strategy: preserve any existing `ext.adcp` block the storyboard
+ * fixture or builder authored (e.g. vendor extensions a future scenario
+ * might exercise). The injected `disable_sandbox` flag rides alongside
+ * those rather than overwriting them.
+ */
+function applyDisableSandboxHint(request, taskName) {
+    if (taskName && !(0, schema_loader_1.schemaAllowsTopLevelField)(taskName, 'ext'))
+        return request;
+    const existingExt = request.ext;
+    const existingExtObj = existingExt != null && typeof existingExt === 'object' && !Array.isArray(existingExt)
+        ? existingExt
+        : {};
+    const existingAdcpExt = existingExtObj.adcp;
+    const existingAdcpExtObj = existingAdcpExt != null && typeof existingAdcpExt === 'object' && !Array.isArray(existingAdcpExt)
+        ? existingAdcpExt
+        : {};
+    return {
+        ...request,
+        ext: {
+            ...existingExtObj,
+            adcp: {
+                ...existingAdcpExtObj,
+                disable_sandbox: true,
+            },
+        },
+    };
+}
 /**
  * Mint an `idempotency_key` for mutating storyboard requests when one wasn't
  * supplied. Storyboard `sample_request` blocks generally omit it; the runner
@@ -2617,8 +3209,109 @@ function truncateError(error) {
         return undefined;
     return error.length > MAX_ERROR_LENGTH ? error.slice(0, MAX_ERROR_LENGTH) + '...[truncated]' : error;
 }
+/**
+ * Pre-fetch `query_upstream_traffic` responses for every unique
+ * `since_timestamp` window declared by `upstream_traffic` validations on
+ * THIS step. The dispatcher is synchronous; the controller call is async
+ * — running it once here keeps the validator simple and avoids redundant
+ * controller traffic when a step has multiple upstream_traffic checks
+ * sharing a window.
+ *
+ * Returns `undefined` when the step declares no upstream_traffic checks
+ * (no work to do), or a context with `advertised: false` when the
+ * controller does not advertise `query_upstream_traffic` (every check
+ * grades not_applicable per the spec's adopter-opt-in rule).
+ */
+async function prefetchUpstreamTraffic(stepId, resolvedValidations, client, options, runState, requestStartIso) {
+    const upstreamChecks = resolvedValidations.filter(v => v.check === 'upstream_traffic');
+    if (upstreamChecks.length === 0)
+        return undefined;
+    const advertised = options._controllerCapabilities?.detected === true &&
+        options._controllerCapabilities.scenarios.includes('query_upstream_traffic');
+    if (!advertised) {
+        return {
+            advertised: false,
+            queries: new Map(),
+            thisStepSince: requestStartIso,
+        };
+    }
+    // Resolve `since: prior_step_id` references against runState's
+    // recorded request timestamps. Validations that name an unknown step
+    // fall back to this step's own start (matching default behavior).
+    const priorStepSinceMap = new Map();
+    const unresolvedSinceRefs = new Set();
+    const sinceTimestamps = new Set([requestStartIso]);
+    for (const v of upstreamChecks) {
+        if (!v.since)
+            continue;
+        const priorStart = runState.stepRequestStarts?.get(v.since);
+        if (priorStart) {
+            priorStepSinceMap.set(v.since, priorStart);
+            sinceTimestamps.add(priorStart);
+        }
+        else {
+            // Spec PR adcp#3816: a `since: prior_step_id` that doesn't resolve
+            // is a storyboard authoring bug — silently masking it as "use this
+            // step's start" lets misspelled refs pass vacuously. Track and
+            // surface as a typed failure on the validation result.
+            priorStepSinceMap.set(v.since, requestStartIso);
+            unresolvedSinceRefs.add(v.since);
+        }
+    }
+    const queries = new Map();
+    for (const sinceTs of sinceTimestamps) {
+        // Per spec PR adcp#3816: runners SHOULD subtract a clock-skew tolerance
+        // (50ms minimum, 250ms recommended) before sending the bound to the
+        // controller, so a recorded call timestamped microseconds before the
+        // runner's clock measurement isn't silently excluded. We use 250ms (the
+        // spec's recommended value).
+        const adjustedSince = new Date(new Date(sinceTs).getTime() - 250).toISOString();
+        const params = { since_timestamp: adjustedSince, limit: 100 };
+        const requestRecord = {
+            transport: options.protocol === 'a2a' ? 'a2a' : 'mcp',
+            operation: 'comply_test_controller',
+            payload: (0, redact_secrets_1.redactSecrets)({ scenario: 'query_upstream_traffic', params }),
+            ...(runState.agentUrl ? { url: runState.agentUrl } : {}),
+        };
+        const startMs = Date.now();
+        let payload;
+        try {
+            const result = await (0, test_controller_1.queryUpstreamTraffic)(client, params, options);
+            if ('success' in result && result.success === true) {
+                payload = result;
+            }
+            else {
+                const errResult = result;
+                const message = errResult.error_detail
+                    ? `${errResult.error ?? 'controller_error'}: ${errResult.error_detail}`
+                    : (errResult.error ?? 'controller returned a non-success response');
+                payload = { error: message };
+            }
+        }
+        catch (err) {
+            payload = { error: err instanceof Error ? err.message : String(err) };
+        }
+        const responseRecord = {
+            transport: options.protocol === 'a2a' ? 'a2a' : 'mcp',
+            payload: (0, redact_secrets_1.redactSecrets)(payload),
+            duration_ms: Date.now() - startMs,
+        };
+        queries.set(sinceTs, { request: requestRecord, response: responseRecord, payload });
+    }
+    return {
+        advertised: true,
+        queries,
+        thisStepSince: requestStartIso,
+        ...(priorStepSinceMap.size > 0 ? { priorStepSinceMap } : {}),
+        ...(unresolvedSinceRefs.size > 0 ? { unresolvedSinceRefs } : {}),
+    };
+}
 /**
  * Find any "$context.xxx" strings that weren't resolved during injection.
+ * Returns one entry per occurrence with both the bare key (for legacy
+ * detail-string formatting) and the full token (for the
+ * `unresolved_substitution` validation result's `expected` field, per
+ * runner-output-contract.yaml v2.0.0).
  */
 function findUnresolvedContextVars(obj) {
     const vars = [];
@@ -2626,7 +3319,7 @@ function findUnresolvedContextVars(obj) {
         if (typeof val === 'string') {
             const match = val.match(/^\$context\.(\w+)$/);
             if (match?.[1])
-                vars.push(match[1]);
+                vars.push({ key: match[1], token: val });
         }
         else if (Array.isArray(val)) {
             val.forEach(walk);
@@ -2696,6 +3389,36 @@ function createDispatcher(agentUrls, clients, _strategy, startOffset = 0) {
         },
     };
 }
+/**
+ * Per-specialism routing dispatcher (#1066). Picks the agent that claims
+ * each step's tool's protocol via the routing context. Throws
+ * `RoutingError` mid-step when no route can be determined; the runner's
+ * step loop catches and converts to a synthetic `unroutable_task` skip.
+ *
+ * `instanceIndex` reflects the agent key's insertion order in the map —
+ * deterministic and matches the index used for downstream `agent_urls`
+ * exposure on the storyboard result.
+ */
+function createRoutingDispatcher(ctx, options, agents) {
+    const keyOrder = Object.keys(agents);
+    const keyToIndex = new Map(keyOrder.map((k, i) => [k, i]));
+    return {
+        nextFor(step) {
+            const key = (0, agent_routing_1.resolveAgentForStep)(step, options, ctx);
+            const client = ctx.clients.get(key);
+            const url = agents[key]?.url;
+            if (!client || !url) {
+                throw new agent_routing_1.RoutingError(`Internal: resolved agent key "${key}" has no client/url. ` +
+                    `This indicates a bug in routing-context construction.`, step.task, `key ${key} unbound`);
+            }
+            return {
+                client,
+                agentUrl: url,
+                instanceIndex: keyToIndex.get(key) ?? 0,
+            };
+        },
+    };
+}
 const HORIZONTAL_SCALING_DOCS_URL = 'https://adcontextprotocol.org/docs/building/validate-your-agent#verifying-cross-instance-state';
 const NOT_FOUND_PATTERN = /not[_ ]found|not-found|\b404\b/i;
 // Agent-controlled text (error messages, response payloads) lands in terminal