@adcp/sdk 16.4.0 → 16.5.0

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

@@ -1,12 +1,14 @@
 import { createHash, createHmac } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import { ACCOUNT_FREE_DISCOVERY_TASKS } from "./account-policy.mjs";
 import { prepareCreativeBuildProbe } from "./creative-build-probe.mjs";
 import {
   createTestClient,
   getOrCreateClientResolution,
-  getOrDiscoverProfile,
+  getOrDiscoverStoryboardProfile,
+  describeProfileDiscoveryFailure,
   hasTestClientScope,
   runStep
 } from "../client.mjs";
@@ -38,7 +40,9 @@ import {
   buildPreparedBinding,
   createPreparedStoryboardFixtures,
   preparedBindingRegistryFor,
-  resolvePreparedFixtures
+  resolvePreparedFixtures,
+  isTrustedPreparedFixtures,
+  assertNoPreparationAuthorizer
 } from "./prepared-fixtures.mjs";
 import { detectContextRejectionHints } from "./rejection-hints.mjs";
 import { detectShapeDriftHints } from "./shape-drift-hints.mjs";
@@ -215,6 +219,11 @@ function applyStoryboardVersionOptions(storyboard, options) {
 function applyReusableProfileOptions(options) {
   const profile = options.profile ?? options._profile;
   if (!profile) return options;
+  if (options.agents === void 0 && options.profile !== void 0 && (typeof profile !== "object" || !Array.isArray(profile.tools) || profile.tools.some(
+    (tool) => typeof tool !== "string" && !(tool && typeof tool === "object" && typeof tool.name === "string")
+  ))) {
+    throw new Error("Storyboard profile must contain an array of tool names.");
+  }
   const profileTools = options.agents === void 0 ? normalizeAgentToolNames(profile.tools) ?? [] : void 0;
   return {
     ...options,
@@ -278,6 +287,9 @@ const CANONICAL_SKIP_DETAILS = {
 };
 const MCP_SESSION_PROBE_REQUEST_TIMEOUT_MS = 5e3;
 const REPLAY_WEBHOOK_VECTOR_TASK = "replay_webhook_vector";
+function isRunnerOwnedTask(task) {
+  return task === VALIDATION_ONLY_TASK || task === MCP_SESSION_PROBE_TASK || task === "assert_contribution" || task === REPLAY_WEBHOOK_VECTOR_TASK || TRUSTED_MATCH_PUBLISHER_AUTH_TASKS.has(task) || PROBE_TASKS.has(task) || WEBHOOK_ASSERTION_TASKS.has(task);
+}
 const REPLAY_TRUSTED_MATCH_CONTEXT_VECTOR_TASK = "replay_trusted_match_context_vector";
 const WEBHOOK_REPLAY_DEFAULT_TIMEOUT_MS = 1e4;
 function selectionForProbeSkip(reason, detail) {
@@ -408,6 +420,15 @@ function evaluateRequiresCapabilityGate(predicate, profile, agentTools, adcpVers
   }
   return null;
 }
+function storyboardAllowsCapabilityDiagnostic(storyboard) {
+  const steps = storyboard.phases.flatMap((phase) => phase.steps);
+  return !storyboardRequiresCapabilityEvidence(storyboard) && steps.length > 0 && steps.every((step) => step.task === "get_adcp_capabilities");
+}
+function storyboardRequiresCapabilityEvidence(storyboard) {
+  return Boolean(
+    storyboard.requires_capability || storyboard.requires_all_capabilities?.length || storyboard.phases.some((phase) => phase.requires_capability || phaseContainsOauthMetadataProbe(phase)) || storyboard.requires?.includes("request_signer") || detectImplicitRequires(storyboard).includes("request_signer") || storyboard.phases.some((phase) => phase.steps.some((step) => step.task === "sync_accounts")) || storyboard.creative_build_probe
+  );
+}
 function storyboardCapabilityPredicates(storyboard) {
   return [
     ...storyboard.requires_capability ? [storyboard.requires_capability] : [],
@@ -840,7 +861,12 @@ function filterResponseHeaders(headers) {
   return Object.keys(out).length > 0 ? out : void 0;
 }
 async function runStoryboard(agentUrlOrUrls, storyboard, options = {}) {
-  options = applyReusableProfileOptions(options);
+  assertNoPreparationAuthorizer(options);
+  options = {
+    ...applyReusableProfileOptions(options),
+    _requireValidCapabilityEvidence: storyboardRequiresCapabilityEvidence(storyboard),
+    _allowCapabilityDiagnostic: storyboardAllowsCapabilityDiagnostic(storyboard)
+  };
   if (hasTestClientScope() && !options._discoveryPass) options = { ...options, _discoveryPass: {} };
   return withPropertyListCredentialRedaction(
     () => withMCPConnectionScope(
@@ -891,7 +917,14 @@ async function runStoryboard(agentUrlOrUrls, storyboard, options = {}) {
               typeof agentUrlOrUrls === "string" ? agentUrlOrUrls : agentUrlOrUrls[0],
               options
             );
-            const discovered = await getOrDiscoverProfile(resolution.client, options);
+            const discovered = await getOrDiscoverStoryboardProfile(resolution.client, options);
+            if (!discovered.step.passed)
+              return buildDiscoveryFailedResult(
+                resolveBindingAgentUrls(agentUrlOrUrls, options),
+                storyboard,
+                discovered.step,
+                discovered.profile
+              );
             options = {
               ...options,
               _profile: discovered.step.passed ? discovered.profile : void 0,
@@ -923,6 +956,14 @@ async function runStoryboardBody(agentUrlOrUrls, storyboard, options) {
   if (!options.agents && agentUrls.length === 0) {
     throw new Error("runStoryboard: at least one agent URL required");
   }
+  const suppliedDiscoveryFailure = options._profile && describeProfileDiscoveryFailure(
+    options._profile,
+    options._requireValidCapabilityEvidence === true,
+    options._allowCapabilityDiagnostic === true
+  );
+  if (!options.agents && suppliedDiscoveryFailure) {
+    return buildDiscoveryFailedResult(agentUrls, storyboard, suppliedDiscoveryFailure, options._profile);
+  }
   const isMultiInstance = agentUrls.length > 1;
   if (isMultiInstance && options._client) {
     throw new Error(
@@ -1460,21 +1501,25 @@ function signingCoverageUnverified(steps) {
   const coverage = signingCoverage(steps);
   return coverage !== "not_probed" && coverage !== "graded";
 }
-function buildDiscoveryFailedResult(agentUrls, storyboard, discoveryStep) {
+function buildDiscoveryFailedResult(agentUrls, storyboard, discoveryStep, profile) {
   const detail = discoveryStep.error ?? "Discovery failed (no agent tools advertised).";
   const syntheticStep = {
     storyboard_id: storyboard.id,
     step_id: "discovery_failed",
     phase_id: "discovery_failed",
     title: "Storyboard failed: agent capability discovery did not succeed",
-    task: "",
+    task: discoveryStep.task ?? "",
     passed: false,
     skipped: false,
     duration_ms: discoveryStep.duration_ms,
     validations: [],
     context: {},
-    error: `Discovery failure: ${detail}. The runner refuses to proceed with empty agentTools \u2014 that mode produces silent "all clean" reports when the underlying transport / auth / network policy is broken. Fix the discovery error before re-running.`,
-    extraction: { path: "none" }
+    error: `Discovery failure: ${detail}. The runner cannot evaluate storyboard applicability from failed discovery evidence. Fix the discovery error before re-running.`,
+    extraction: discoveryStep.extraction ?? { path: "none" },
+    ...discoveryStep.request && { request: discoveryStep.request },
+    ...discoveryStep.response_record && { response_record: discoveryStep.response_record },
+    ...discoveryStep.adcp_error && { adcp_error: discoveryStep.adcp_error },
+    ...discoveryStep.authorization_required && { authorization_required: discoveryStep.authorization_required }
   };
   return {
     storyboard_id: storyboard.id,
@@ -1505,7 +1550,7 @@ function buildDiscoveryFailedResult(agentUrls, storyboard, discoveryStep) {
       strict_only_failures: 0,
       lenient_also_failed: 0
     },
-    notices: []
+    notices: collectCapabilityNotices(storyboard, profile)
   };
 }
 function buildRequiredToolsMissingResult(agentUrls, storyboard, detail) {
@@ -1756,7 +1801,11 @@ function hydratePreparedCaptures(state, context, protectedWriter, contextProvena
   );
 }
 async function prepareStoryboardFixtures(agentUrl, storyboard, options = {}) {
-  options = applyReusableProfileOptions(options);
+  options = {
+    ...applyReusableProfileOptions(options),
+    _requireValidCapabilityEvidence: storyboardRequiresCapabilityEvidence(storyboard),
+    _allowCapabilityDiagnostic: storyboardAllowsCapabilityDiagnostic(storyboard)
+  };
   return withPropertyListCredentialRedaction(
     () => withMCPConnectionScope(
       async () => {
@@ -1795,8 +1844,46 @@ function resolvePreparationRouteOptions(agentUrl, options) {
     ...entry?.transport !== void 0 && { protocol: entry.transport }
   };
 }
+async function resolvePreparationAuthorization(authorizer, current) {
+  const refusal = {
+    code: "authorizer_denied",
+    detail: "fixture preparation was refused by the configured authorizer"
+  };
+  try {
+    const decision = await authorizer({ current: structuredClone(current), gate: "prepare" });
+    return decision?.authorized === true ? { ok: true } : { ok: false, refusal };
+  } catch {
+    return { ok: false, refusal };
+  }
+}
+function snapshotPreparationAuth(auth) {
+  if (auth === void 0) return void 0;
+  if (auth.type === "oauth") {
+    const { storage, ...data } = auth;
+    return { ...structuredClone(data), ...storage && { storage } };
+  }
+  return structuredClone(auth);
+}
+function snapshotPreparationOptions(options) {
+  return {
+    ...options,
+    ...options.context && { context: structuredClone(options.context) },
+    ...options.brand && { brand: { ...options.brand } },
+    ...options.brand_manifest && { brand_manifest: structuredClone(options.brand_manifest) },
+    ...options.headers && { headers: { ...options.headers } },
+    ...options.auth && { auth: snapshotPreparationAuth(options.auth) },
+    ...options.agents && {
+      agents: Object.fromEntries(
+        Object.entries(options.agents).map(([key, agent]) => [
+          key,
+          { ...agent, ...agent.auth && { auth: snapshotPreparationAuth(agent.auth) } }
+        ])
+      )
+    }
+  };
+}
 async function prepareStoryboardFixturesBody(agentUrl, storyboard, options) {
-  const agentUrls = resolveBindingAgentUrls(agentUrl, options);
+  const agentUrls = [...resolveBindingAgentUrls(agentUrl, options)];
   const metadataRefusal = describeReservedCallerOptions(options);
   if (metadataRefusal !== void 0) {
     return buildPreparedFixtures(storyboard, agentUrls, options, void 0, {
@@ -1810,21 +1897,89 @@ async function prepareStoryboardFixturesBody(agentUrl, storyboard, options) {
       detail: "prepareStoryboardFixtures() does not accept prepared_fixtures: it produces prepared state, it does not consume it. Passing state here authorizes nothing \u2014 the authorizer is never consulted \u2014 and preparation would re-resolve the graph against the seller anyway. Pass the state to runStoryboard() or runStoryboardStep() instead, with prepared_fixtures_authorizer. See docs/guides/COLLECTION-FIXTURE-FOUNDATION.md section 4."
     });
   }
+  const bindingOptions = options;
+  const bindingStoryboard = storyboard;
+  let authorizedBinding;
+  const refusePreparation = (refusal, seeding) => {
+    const record = buildPreparedRefusalRunResult(agentUrls, storyboard, refusal, "prepare");
+    if (seeding) {
+      record.phases = [seeding.phase, ...record.phases];
+      record.fixture_resolutions = seeding.resolutionRecords ?? [];
+      const auditSteps = record.phases.flatMap((phase) => phase.steps);
+      record.passed_count = auditSteps.filter((step) => step.passed && !step.skipped).length;
+      record.failed_count = auditSteps.filter((step) => !step.passed && !step.skipped).length;
+      record.skipped_count = auditSteps.filter((step) => step.skipped).length;
+    }
+    return denyPreparedFixtures(options, record, refusal.code);
+  };
+  const scopeStillMatches = () => {
+    if (!authorizedBinding) return true;
+    try {
+      return isDeepStrictEqual(
+        authorizedBinding,
+        buildCurrentPreparedBinding(
+          bindingStoryboard,
+          resolveBindingAgentUrls(agentUrl, bindingOptions),
+          bindingOptions
+        )
+      );
+    } catch {
+      return false;
+    }
+  };
+  const driftRefusal = {
+    code: "binding_mismatch",
+    detail: "fixture preparation scope changed after host authorization"
+  };
+  if (options.prepared_fixtures_preparation_authorizer !== void 0) {
+    authorizedBinding = buildCurrentPreparedBinding(storyboard, agentUrls, options);
+    const decision = await resolvePreparationAuthorization(
+      options.prepared_fixtures_preparation_authorizer,
+      authorizedBinding
+    );
+    if (!decision.ok) {
+      return refusePreparation(decision.refusal);
+    }
+    if (!scopeStillMatches()) return refusePreparation(driftRefusal);
+    storyboard = structuredClone(storyboard);
+    options = snapshotPreparationOptions(options);
+  }
   const callerOwnsClients = hasTestClientScope();
   const preparationOptions = resolvePreparationRouteOptions(agentUrls[0], options);
   const resolution = getOrCreateClientResolution(agentUrls[0], preparationOptions);
   const client = resolution.client;
-  const bindingOptions = options;
+  const finishPreparation = (seeding, disposition) => {
+    if (!scopeStillMatches()) {
+      return refusePreparation(driftRefusal, seeding ?? void 0);
+    }
+    return buildPreparedFixtures(storyboard, agentUrls, bindingOptions, seeding, disposition);
+  };
   options = preparationOptions;
   try {
     let profile = options._profile;
+    const suppliedFailure = profile && describeProfileDiscoveryFailure(
+      profile,
+      options._requireValidCapabilityEvidence === true,
+      options._allowCapabilityDiagnostic === true
+    );
+    if (suppliedFailure) {
+      const failed = buildDiscoveryFailedResult(agentUrls, storyboard, suppliedFailure, profile);
+      return await finishPreparation(
+        { phase: failed.phases[0], allPassed: false, passedCount: 0, failedCount: 1 },
+        { status: "failed", detail: suppliedFailure.error ?? "agent discovery failed" }
+      );
+    }
     if (!profile && !resolution.reusedShared) {
-      const discovered = await getOrDiscoverProfile(client, options);
+      const discovered = await getOrDiscoverStoryboardProfile(client, options);
       if (discovered.step.passed === false) {
-        return buildPreparedFixtures(storyboard, agentUrls, bindingOptions, void 0, {
-          status: "failed",
-          detail: discovered.step.error ?? "agent discovery failed before fixture preparation"
-        });
+        const failed = buildDiscoveryFailedResult(agentUrls, storyboard, discovered.step, discovered.profile);
+        return await finishPreparation(
+          { phase: failed.phases[0], allPassed: false, passedCount: 0, failedCount: 1 },
+          {
+            status: "failed",
+            detail: discovered.step.error ?? "agent discovery failed before fixture preparation"
+          }
+        );
       }
       profile = discovered.profile;
     }
@@ -1835,16 +1990,17 @@ async function prepareStoryboardFixturesBody(agentUrl, storyboard, options) {
         ...!options.agentTools && { agentTools: normalizeAgentToolNames(profile.tools) }
       };
     }
+    if (!scopeStillMatches()) return await refusePreparation(driftRefusal);
     const context = createRunContext(storyboard, options).context;
     const seeding = await runControllerSeeding(client, storyboard, options, context);
     if (!seeding) {
-      return buildPreparedFixtures(storyboard, agentUrls, bindingOptions, void 0, { status: "resolved" });
+      return await finishPreparation(void 0, { status: "resolved" });
     }
-    const disposition = seeding.missingController ? { status: "unsupported", detail: "agent does not advertise comply_test_controller" } : seeding.seedUnsupported ? { status: "unsupported", detail: "agent did not advertise a required seed_* scenario" } : seeding.failedCount > 0 ? {
+    const disposition = seeding.fixtureUnavailable && seeding.failedCount === 0 ? { status: "unsupported", reason: "not_applicable", detail: seeding.fixtureUnavailable } : seeding.missingController ? { status: "unsupported", detail: "agent does not advertise comply_test_controller" } : seeding.seedUnsupported ? { status: "unsupported", detail: "agent did not advertise a required seed_* scenario" } : seeding.failedCount > 0 ? {
       status: "failed",
-      detail: seeding.phase.steps.find((step) => step.error)?.error ?? "fixture resolution failed during preparation"
+      detail: seeding.phase.steps.find((step) => !step.passed && !step.skipped && step.error)?.error ?? "fixture resolution failed during preparation"
     } : seeding.fixtureUnsatisfied === true ? { status: "unsatisfied", detail: describeUnsatisfiedFixtures(seeding.resolutionRecords) } : { status: "resolved" };
-    return buildPreparedFixtures(storyboard, agentUrls, bindingOptions, seeding, disposition);
+    return await finishPreparation(seeding, disposition);
   } finally {
     if (!callerOwnsClients) await closeScopedConnections(options.protocol);
   }
@@ -2073,10 +2229,10 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     callerOwnsClients ||= clientResolutions.some((r) => r.reusedShared);
     resetClientSessions(clients);
     if (hasTestClientScope() || !callerOwnsClients) {
-      const discovered = await getOrDiscoverProfile(clients[0], options);
+      const discovered = await getOrDiscoverStoryboardProfile(clients[0], options);
       if (discovered.step.passed === false) {
         if (!callerOwnsClients) await closeScopedConnections(options.protocol);
-        return buildDiscoveryFailedResult(agentUrls, storyboard, discovered.step);
+        return buildDiscoveryFailedResult(agentUrls, storyboard, discovered.step, discovered.profile);
       }
       profile = discovered.profile;
       const profileTools = normalizeAgentToolNames(profile?.tools);
@@ -2093,9 +2249,9 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
       if (!options.agentTools && profileTools) {
         options = { ...options, agentTools: profileTools, _profile: profile };
       } else if (!options.agentTools && typeof clients[0]?.getAgentInfo === "function") {
-        const discovered = await getOrDiscoverProfile(clients[0], options);
+        const discovered = await getOrDiscoverStoryboardProfile(clients[0], options);
         if (discovered.step.passed === false) {
-          return buildDiscoveryFailedResult(agentUrls, storyboard, discovered.step);
+          return buildDiscoveryFailedResult(agentUrls, storyboard, discovered.step, discovered.profile);
         }
         profile = discovered.profile;
         const discoveredTools = normalizeAgentToolNames(profile?.tools);
@@ -2107,6 +2263,15 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
       }
     }
   }
+  const reusedDiscoveryFailure = profile && describeProfileDiscoveryFailure(
+    profile,
+    options._requireValidCapabilityEvidence === true,
+    options._allowCapabilityDiagnostic === true
+  );
+  if (reusedDiscoveryFailure) {
+    if (!callerOwnsClients) await closeScopedConnections(options.protocol);
+    return buildDiscoveryFailedResult(agentUrls, storyboard, reusedDiscoveryFailure, profile);
+  }
   if (preSeeded === void 0 && !preparedGate.used) {
     const resetTargets = routingContext && options.agents ? [...routingContext.profiles.entries()].map(([key, profile2]) => ({
       client: routingContext.clients.get(key),
@@ -2649,17 +2814,22 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
       const disposition = prepared.state.disposition;
       if (disposition.status === "failed") {
         if (!callerOwnsClients) await closeScopedConnections(options.protocol);
-        return buildDiscoveryFailedResult(agentUrls, storyboard, {
-          step: "Reuse prepared fixture state",
-          passed: false,
-          duration_ms: 0,
-          error: disposition.detail
-        });
+        return buildPreparationFailedRunResult(agentUrls, storyboard, prepared.state, disposition.detail);
       }
       if (disposition.status === "unsatisfied") {
         fixtureUnsatisfied = true;
         fixtureCoverageGap = prepared.state.coverageGaps[0] ?? fixtureCoverageGap;
       }
+      if (disposition.status === "unsupported" && disposition.reason === "not_applicable") {
+        if (!callerOwnsClients) await closeScopedConnections(options.protocol);
+        return buildFixtureDiscoveryUnavailableResult(
+          agentUrls,
+          storyboard,
+          disposition.detail,
+          prepared.state.phase,
+          prepared.state.resolutions
+        );
+      }
       if (disposition.status === "unsupported") seedingMissingController = true;
     }
   }
@@ -2717,6 +2887,17 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
       });
     }
     if (seeding) {
+      if (seeding.fixtureUnavailable && seeding.failedCount === 0) {
+        if (webhookReceiver) await webhookReceiver.close();
+        if (!callerOwnsClients) await closeScopedConnections(options.protocol);
+        return buildFixtureDiscoveryUnavailableResult(
+          agentUrls,
+          storyboard,
+          seeding.fixtureUnavailable,
+          seeding.phase,
+          seeding.resolutionRecords
+        );
+      }
       const attach = preSeeded === void 0 || preSeeded.attach;
       if (attach) {
         seedingPhaseResult = seeding.phase;
@@ -2726,7 +2907,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
         }
         passedCount += seeding.passedCount;
         failedCount += seeding.failedCount;
-        if (seeding.missingController || seeding.seedUnsupported || seeding.fixtureUnsatisfied) {
+        if (seeding.missingController || seeding.seedUnsupported || seeding.fixtureUnsatisfied || seeding.fixtureUnavailable) {
           skippedCount += seeding.phase.steps.filter((step) => step.skipped).length;
         }
       }
@@ -3148,7 +3329,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
       const cascade = step.stateful ? cascadeForPhase(phase, priorPhaseIds) : { tripped: false };
       if (cascade.tripped && step.stateful && routedCapabilityDetail === void 0) {
         const resolvedTask = resolveTaskName(step, selectedOptions);
-        const missingTool = selectedOptions.agentTools && (routingContext && step.requires_tool && !selectedOptions.agentTools.includes(step.requires_tool) ? step.requires_tool : resolvedTask && resolvedTask !== MCP_SESSION_PROBE_TASK && !selectedOptions.agentTools.includes(resolvedTask) ? resolvedTask : void 0);
+        const missingTool = selectedOptions.agentTools && (routingContext && step.requires_tool && !selectedOptions.agentTools.includes(step.requires_tool) ? step.requires_tool : resolvedTask && !isRunnerOwnedTask(resolvedTask) && !selectedOptions.agentTools.includes(resolvedTask) ? resolvedTask : void 0);
         if (missingTool) {
           const missingReason = routingContext && missingTool === "comply_test_controller" ? "missing_test_controller" : "missing_tool";
           const toolDetail = `Agent did not advertise tool "${missingTool}"; agent tools: [${selectedOptions.agentTools.join(", ")}].`;
@@ -3595,6 +3776,12 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     return p.steps.some((s) => !s.skipped && s.passed);
   });
   const requiredPhaseDefs = storyboard.phases.filter((phaseDef) => !phaseDef.optional);
+  const optionalOnlyHasExecutedPass = requiredPhaseDefs.length === 0 && failedCount === 0 && phaseResults.some((phase) => phase.passed && phase.steps.some((step) => !step.skipped && step.passed)) && phaseResults.every((phase) => {
+    if (phase.passed) return true;
+    const branchSet = branchSetsByPhaseId.get(phase.phase_id);
+    const source = branchSet && contributionSources.get(branchSet.id);
+    return branchSet?.semantics === "any_of" && source?.phaseId !== phase.phase_id && phaseResults.some((peer) => peer.phase_id === source?.phaseId && peer.passed);
+  });
   const requiredPhasesNonFailingSkipped = requiredPhaseDefs.length > 0 && requiredPhaseDefs.every((phaseDef) => {
     const phaseResult = phaseResults.find((p) => p.phase_id === phaseDef.id);
     return !!phaseResult && phaseResult.passed && phaseResult.steps.length > 0 && phaseResult.steps.every(
@@ -3606,7 +3793,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     const phaseResult = phaseResults.find((p) => p.phase_id === phaseDef.id);
     return !!phaseResult && phaseResult.passed && phaseResult.steps.some((s) => !s.skipped && s.passed);
   });
-  const requiredPhasesPassed = !hasExecutableSteps || requiredPhaseDefs.every((phaseDef) => phaseResults.find((p) => p.phase_id === phaseDef.id)?.passed === true) && (requiredPhaseHasExecutedPass || requiredPhasesNonFailingSkipped || failedCount === 0 && requiredPhasesCoveredByCapabilityGates);
+  const requiredPhasesPassed = !hasExecutableSteps || requiredPhaseDefs.every((phaseDef) => phaseResults.find((p) => p.phase_id === phaseDef.id)?.passed === true) && (requiredPhaseHasExecutedPass || optionalOnlyHasExecutedPass || requiredPhasesNonFailingSkipped || failedCount === 0 && requiredPhasesCoveredByCapabilityGates);
   const storyboardWideFixtureUnavailable = (seedingUnsupported || fixtureUnsatisfied || creativeAssetFixtureGap !== void 0) && failedCount === 0;
   const hasUnverifiedCoverage = signingCoverageUnverified(phaseResults.flatMap((phase) => phase.steps));
   if (seedingPhaseResult) phaseResults.unshift(seedingPhaseResult);
@@ -3685,10 +3872,10 @@ async function runMultiPass(agentUrls, storyboard, options) {
   const preSeedContext = createRunContext(storyboard, options).context;
   let preSeedProfile = options._profile;
   if (!preSeedProfile) {
-    const discovered = await getOrDiscoverProfile(preSeedClients[0], options);
+    const discovered = await getOrDiscoverStoryboardProfile(preSeedClients[0], options);
     if (discovered.step.passed === false) {
       await closeScopedConnections(options.protocol);
-      return buildDiscoveryFailedResult(agentUrls, storyboard, discovered.step);
+      return buildDiscoveryFailedResult(agentUrls, storyboard, discovered.step, discovered.profile);
     }
     preSeedProfile = discovered.profile;
   }
@@ -3769,6 +3956,16 @@ async function runMultiPass(agentUrls, storyboard, options) {
     // bindings — the reset is guarded above for the same reason.
     options.prepared_fixtures !== void 0 || preSeedFixtureGap || allExecutablePhasesCapabilitySkipped(storyboard, phaseCapabilitySkipDetails) ? null : await runControllerSeeding(preSeedClients[0], storyboard, options, preSeedContext)
   );
+  if (preSeededResult?.fixtureUnavailable && preSeededResult.failedCount === 0) {
+    await closeScopedConnections(options.protocol);
+    return buildFixtureDiscoveryUnavailableResult(
+      agentUrls,
+      storyboard,
+      preSeededResult.fixtureUnavailable,
+      preSeededResult.phase,
+      preSeededResult.resolutionRecords
+    );
+  }
   const passes = [];
   const passResults = [];
   for (let passIdx = 0; passIdx < agentUrls.length; passIdx++) {
@@ -3927,7 +4124,12 @@ function summarizeStrictValidation(phases) {
   };
 }
 async function runStoryboardStep(agentUrl, storyboard, stepId, options = {}) {
-  options = applyReusableProfileOptions(options);
+  assertNoPreparationAuthorizer(options);
+  options = {
+    ...applyReusableProfileOptions(options),
+    _requireValidCapabilityEvidence: storyboardRequiresCapabilityEvidence(storyboard),
+    _allowCapabilityDiagnostic: storyboardAllowsCapabilityDiagnostic(storyboard)
+  };
   return withPropertyListCredentialRedaction(
     () => withMCPConnectionScope(
       async () => {
@@ -3969,13 +4171,19 @@ async function emitPreparedFixturesAudit(options, record) {
   const sink = options.prepared_fixtures_audit_sink;
   if (!sink) return;
   try {
-    await sink(record);
+    const state = options.prepared_fixtures;
+    const auditRecord = isTrustedPreparedFixtures(state) && state.disposition.status === "failed" ? {
+      ...record,
+      fixture_resolutions: state.resolutions,
+      ...state.phase && { fixture_preparation: state.phase }
+    } : record;
+    await sink(auditRecord);
   } catch {
   }
 }
-function buildPreparedRefusalRunResult(agentUrls, storyboard, refusal) {
+function buildPreparedRefusalRunResult(agentUrls, storyboard, refusal, gate) {
   const base = buildDiscoveryFailedResult(agentUrls, storyboard, {
-    step: "Authorize prepared fixture state",
+    step: gate === "prepare" ? "Authorize fixture preparation" : "Authorize prepared fixture state",
     passed: false,
     duration_ms: 0,
     error: refusal.detail
@@ -3983,16 +4191,16 @@ function buildPreparedRefusalRunResult(agentUrls, storyboard, refusal) {
   const validation = {
     check: "prepared_fixtures_authorization",
     passed: false,
-    description: "Prepared fixture state is re-validated and re-authorized on every lookup",
+    description: gate === "prepare" ? "Fresh fixture preparation requires host authorization before seller contact" : "Prepared fixture state is re-validated and re-authorized on every lookup",
     error: refusal.detail,
     json_pointer: null,
-    expected: "an authorized prepared state bound to this exact run scope",
+    expected: gate === "prepare" ? "an authorized fixture preparation for this exact run scope" : "an authorized prepared state bound to this exact run scope",
     actual: refusal.code,
     schema_id: null,
     schema_url: null,
-    // Explicit nulls. This gate precedes all seller contact, so the
-    // exchange genuinely did not happen — and an omitted key cannot be
-    // told apart from a runner that forgot to record one.
+    // Explicit nulls: the refusal check itself makes no seller call.
+    // Earlier producer exchanges remain in the private audit record;
+    // an omitted key would be indistinguishable from missing evidence.
     request: null,
     response: null
   };
@@ -4039,7 +4247,91 @@ function buildPreparedRefusalStepResult(storyboard, found, context, refusal, con
     error: refusal.detail
   };
 }
-function buildPreparedDispositionStepResult(storyboard, found, context, disposition, contributions) {
+function preparedPhaseForOutput(phase) {
+  return { ...phase, steps: phase.steps.map((step) => ({ ...step, context: withoutProtectedCaptures(step.context) })) };
+}
+function buildPreparationFailedRunResult(agentUrls, storyboard, state, detail) {
+  const resolutions = state.resolutions;
+  const producerPhase = state.phase;
+  const failingStep = producerPhase?.steps.find((step) => step.passed === false);
+  const syntheticStep = {
+    storyboard_id: storyboard.id,
+    step_id: "prepared_fixtures_preparation_failed",
+    phase_id: "prepared_fixtures_preparation_failed",
+    title: "Storyboard failed: fixture preparation did not resolve",
+    task: failingStep?.task ?? "",
+    passed: false,
+    skipped: false,
+    duration_ms: 0,
+    validations: [
+      {
+        check: "fixture_capture_unbuildable",
+        passed: false,
+        description: "Fixture preparation must resolve before a run can reuse it",
+        error: detail,
+        json_pointer: null,
+        expected: "a fixture graph that resolved during preparation",
+        actual: "preparation_failed",
+        schema_id: null,
+        schema_url: null,
+        // Pre-wire for THIS run: the consumer never dispatched. The
+        // producer's own exchange is retained in fixture_preparation.
+        request: null,
+        response: null
+      }
+    ],
+    context: {},
+    extraction: { path: "none" },
+    error: detail
+  };
+  const phases = [
+    {
+      phase_id: "prepared_fixtures_preparation_failed",
+      phase_title: "Prepared fixture preparation failed",
+      passed: false,
+      steps: [syntheticStep],
+      duration_ms: 0
+    }
+  ];
+  return {
+    storyboard_id: storyboard.id,
+    storyboard_title: storyboard.title,
+    agent_url: redactOAuthUrlForOutput(agentUrls[0]),
+    agent_urls: agentUrls.map(redactOAuthUrlForOutput),
+    overall_passed: false,
+    ...resolutions.length > 0 && { fixture_resolutions: resolutions },
+    ...state.coverageGaps.length > 0 && { coverage_gaps: state.coverageGaps },
+    phases,
+    ...producerPhase && { fixture_preparation: preparedPhaseForOutput(producerPhase) },
+    context: {},
+    total_duration_ms: 0,
+    passed_count: 0,
+    failed_count: 1,
+    skipped_count: 0,
+    runner_capability_version: RUNNER_CAPABILITY_VERSION,
+    tested_at: (/* @__PURE__ */ new Date()).toISOString(),
+    strict_validation_summary: summarizeStrictValidation(phases),
+    notices: []
+  };
+}
+function buildFixtureDiscoveryUnavailableResult(agentUrls, storyboard, detail, producerPhase, resolutions = []) {
+  const result = buildCapabilityUnsupportedResult(agentUrls, storyboard, detail);
+  const phase = result.phases[0];
+  phase.phase_id = "fixture_discovery_unavailable";
+  phase.phase_title = "Fixture discovery unavailable";
+  const step = phase.steps[0];
+  step.step_id = phase.phase_id;
+  step.phase_id = phase.phase_id;
+  step.title = "Fixture discovery unavailable within runner budget";
+  step.task = "get_products";
+  step.skip_reason = "not_applicable";
+  step.skip = { reason: "not_applicable", detail };
+  result.fixture_resolutions = [...resolutions];
+  if (producerPhase) result.fixture_preparation = preparedPhaseForOutput(producerPhase);
+  return result;
+}
+function buildPreparedDispositionStepResult(storyboard, found, context, disposition, contributions, resolutions = [], producerPhase) {
+  const skipReason = disposition.status === "unsupported" && disposition.reason === "not_applicable" ? "not_applicable" : disposition.status === "unsatisfied" ? "fixture_unsatisfied" : "missing_test_controller";
   const detail = "detail" in disposition ? disposition.detail : "fixture preparation did not resolve";
   if (disposition.status === "failed") {
     return {
@@ -4067,9 +4359,19 @@ function buildPreparedDispositionStepResult(storyboard, found, context, disposit
           expected: "a fixture graph that resolved during preparation",
           actual: "preparation_failed",
           schema_id: null,
-          schema_url: null
+          schema_url: null,
+          // Pre-wire for THIS step: the consumer never dispatched. The
+          // producer's own exchange rides on its records below.
+          request: null,
+          response: null
         }
       ],
+      // The producer's own records, so a standalone consumer sees the same
+      // fixture-handle evidence a full run carries. It had none before:
+      // the caller was told preparation failed with no way to see which
+      // handle, which strategy, or what the seller actually returned.
+      ...resolutions.length > 0 && { fixture_resolutions: [...resolutions] },
+      ...producerPhase && { fixture_preparation: preparedPhaseForOutput(producerPhase) },
       context: withoutProtectedCaptures(context),
       extraction: { path: "none" },
       contributions: Array.from(contributions),
@@ -4084,7 +4386,7 @@ function buildPreparedDispositionStepResult(storyboard, found, context, disposit
     task: found.step.task,
     passed: true,
     skipped: true,
-    skip_reason: disposition.status === "unsatisfied" ? "fixture_unsatisfied" : "missing_test_controller",
+    skip_reason: skipReason,
     // Match the full runner: reporting a missing controller as a
     // branch-substitutable `not_applicable` would let a consumer credit a
     // peer path that does not exist.
@@ -4097,11 +4399,15 @@ function buildPreparedDispositionStepResult(storyboard, found, context, disposit
     // against the SDK. Promoting it in `RunnerSkipReason` fixed both paths
     // at once, so the two no longer disagree.
     skip: {
-      reason: disposition.status === "unsatisfied" ? "fixture_unsatisfied" : "missing_test_controller",
+      reason: skipReason,
       detail
     },
     duration_ms: 0,
     validations: [],
+    ...skipReason === "not_applicable" && {
+      fixture_resolutions: [...resolutions],
+      ...producerPhase && { fixture_preparation: preparedPhaseForOutput(producerPhase) }
+    },
     context: withoutProtectedCaptures(context),
     extraction: { path: "none" },
     contributions: Array.from(contributions)
@@ -4176,8 +4482,12 @@ async function runStoryboardStepBody(agentUrl, storyboard, stepId, options) {
   const clientResolution = getOrCreateClientResolution(agentUrl, options);
   const client = clientResolution.client;
   let profile;
-  if (!clientResolution.reusedShared) {
-    const discovered = await getOrDiscoverProfile(client, options);
+  if (!clientResolution.reusedShared || hasTestClientScope()) {
+    const discovered = await getOrDiscoverStoryboardProfile(client, options);
+    if (!discovered.step.passed) {
+      if (!clientResolution.reusedShared) await closeScopedConnections(options.protocol);
+      return buildDiscoveryFailedResult([agentUrl], storyboard, discovered.step, discovered.profile).phases[0].steps[0];
+    }
     profile = discovered.profile;
     if (profile && (!options._profile || !options.agentTools)) {
       options = {
@@ -4189,6 +4499,15 @@ async function runStoryboardStepBody(agentUrl, storyboard, stepId, options) {
   } else {
     profile = options._profile;
   }
+  const reusedDiscoveryFailure = profile && describeProfileDiscoveryFailure(
+    profile,
+    options._requireValidCapabilityEvidence === true,
+    options._allowCapabilityDiagnostic === true
+  );
+  if (reusedDiscoveryFailure) {
+    if (!clientResolution.reusedShared) await closeScopedConnections(options.protocol);
+    return buildDiscoveryFailedResult([agentUrl], storyboard, reusedDiscoveryFailure, profile).phases[0].steps[0];
+  }
   const standaloneRunContext = createRunContext(storyboard, options);
   const protectedWriter = standaloneRunContext.protectedWriter;
   const context = standaloneRunContext.context;
@@ -4354,7 +4673,15 @@ async function runStoryboardStepBody(agentUrl, storyboard, stepId, options) {
     if (prepared.used && "state" in prepared) {
       const disposition = prepared.state.disposition;
       if (disposition.status !== "resolved") {
-        return buildPreparedDispositionStepResult(storyboard, found, context, disposition, contributions);
+        return buildPreparedDispositionStepResult(
+          storyboard,
+          found,
+          context,
+          disposition,
+          contributions,
+          prepared.state.resolutions,
+          prepared.state.phase
+        );
       }
       const hydrationViolation = hydratePreparedCaptures(prepared.state, context, protectedWriter, contextProvenance);
       if (hydrationViolation) {
@@ -7922,7 +8249,9 @@ export {
   runStoryboardStep,
   signingCoverage,
   signingCoverageUnverified,
+  storyboardAllowsCapabilityDiagnostic,
   storyboardCapabilityGateUnmet,
   storyboardCapabilityPredicates,
+  storyboardRequiresCapabilityEvidence,
   summarizeStrictValidation
 };